Skip to main content
POST
/
v2
/
transactions
/
swift
Create Swift payment
curl --request POST \
  --url https://api.pgw-sandbox.finventi.com/v2/transactions/swift \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 1050299,
  "charges": {
    "agentBic": "CHRGBICXXXX",
    "amount": 2550,
    "bearer": "DEBT",
    "currency": "EUR"
  },
  "clearingChannel": "RTGS",
  "creditor": {
    "agentBic": "INVELT2XXXX",
    "iban": "DE89370400440532013000",
    "name": "Creditor Company Incorporated"
  },
  "currency": "EUR",
  "debtor": {
    "agentBic": "MLLKMTM2XXX",
    "iban": "LT121000011101001000",
    "name": "Debtor Company Limited"
  },
  "endToEndId": "TXN123456789012345",
  "instructionId": "INSTR001234567",
  "messageRouting": {
    "receiverBic": "DEUTDEFFXXX"
  },
  "priority": "HIGH",
  "remittance": "Payment for invoice #INV-2025-001234",
  "serviceLevel": "URGP",
  "settlement": {
    "date": "2025-07-04",
    "iban": "GB29NWBK60161331926819",
    "method": "INDA"
  }
}
'
{
  "amount": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "creditor": {
    "agentBic": "<string>",
    "iban": "<string>",
    "name": "<string>"
  },
  "currency": "<string>",
  "debtor": {
    "agentBic": "<string>",
    "iban": "<string>",
    "name": "<string>"
  },
  "endToEndId": "<string>",
  "method": "SEPA",
  "settlementDate": "2023-12-25",
  "status": "<string>",
  "transactionId": 123,
  "remittance": "<string>"
}

​
Overview

This endpoint creates SWIFT payments for international wire transfers. The payment is validated and submitted to the correspondent banking network.

​
Idempotent Endpoint

This endpoint supports idempotency to prevent duplicate transactions.

​
How to Use

  • Include an Idempotency-Key header with a unique value (UUID recommended)
  • The API returns the existing transaction when you reuse the same key
  • Retry requests safely without creating duplicates

​
Key Features

  • Supports multiple currencies
  • Handles correspondent bank routing
  • Validates BIC codes and account formats
  • Provides transaction tracking

Headers

​
Idempotency-Key
string
required

Unique identifier in scope of payment creation endpoints required to prevent unintended duplicate payments

Body

application/json

SWIFT payment request for creating cross-border payments

​
amount
integer
required

Transaction amount in cents

Example:

10102

​
creditor
object
required

Creditor information

​
currency
string
required

Currency code - must be from supported currencies per tenant

​
debtor
object
required

Debtor information

​
priority
enum<string>
required

Instruction priority: NORM (normal), HIGH (high) (optional)

Available options:
NORM,
HIGH
​
settlement
object
required

Settlement information

​
categoryPurposeCode
enum<string>

Category purpose code. Indicates the high-level purpose of the payment at a business level for accounting inside the payer/beneficiary company and for interbank and regulatory interpretation. Mutually exclusive with categoryPurposeProprietary.

Available options:
BONU,
CASH,
CBLK,
CCRD,
CORT,
DCRD,
DIVI,
DVPM,
EPAY,
FCIN,
FCOL,
GOVT,
HEDG,
ICCP,
IDCP,
INTC,
INTE,
LOAN,
MP2B,
MP2P,
OTHR,
PENS,
RPRE,
RRCT,
RVPM,
SALA,
SECU,
SSBE,
SUPP,
TAXS,
TRAD,
TREA,
VATX,
WHLD
​
categoryPurposeProprietary
string

Category purpose proprietary value. Free text alternative to categoryPurposeCode for non-standard category purposes. Mutually exclusive with categoryPurposeCode. Must contain at least one non-whitespace character. Maximum length is 35 characters.

Maximum string length: 35
​
charges
object

Charge information

​
clearingChannel
enum<string>

Clearing channel: BOOK (book transfer), MPNS (mass payment net system), RTGS (real-time gross settlement), RTNS (real-time net settlement) (optional)

Available options:
BOOK,
MPNS,
RTGS,
RTNS
​
endToEndId
string

End-to-end identification assigned by the initiating party (optional, defaults to NOTPROVIDED if not provided)

Required string length: 1 - 35
​
instructionId
string

Instruction ID assigned by the instructing party (optional, uses transaction.id if not provided)

Required string length: 1 - 16
​
messageRouting
object

Message routing information - identifies the sender and receiver institutions

​
purposeCode
enum<string>

Category purpose code. Allowed values: 'ADVA' - Advance payment, 'TAXS' - Tax payment,
'CSDB' - Cash Disbursement/Cash Management,
'GDSV' - Purchase Sale Of Goods And Services, 'GSCB' - Purchase Sale Of Goods And Services With Cash Back,
'COMP' - Compensation Payment, 'FEES' - Payment Of Fees, 'ICCP' - Irrevocable Credit Card Payment,
'IDCP' - Irrevocable Debit Card Payment, 'REFU' - Refund, 'RRCT' - Reimbursement Received Credit Transfer,
'RRTP' - Related Request To Pay, 'GVEA' - Austrian Government Employees Category A,
'GVEB' - Austrian Government Employees Category B, 'GVEC' - Austrian Government Employees Category C,
'GVED' - Austrian Government Employees Category D

Available options:
ADVA,
TAXS,
CSDB,
GDSV,
GSCB,
COMP,
FEES,
ICCP,
IDCP,
REFU,
RRCT,
RRTP,
GVEA,
GVEB,
GVEC,
GVED
Required string length: 1 - 4
​
remittance
string

Unstructured remittance information (payment details)

Maximum string length: 140
​
serviceLevel
enum<string>

Service level code: BKTR (book transfer), NUGP (non-urgent priority), NURG (non-urgent), SDVA (same day value), URGP (urgent payment), URNS (urgent net settlement) (optional)

Available options:
BKTR,
NUGP,
NURG,
SDVA,
URGP,
URNS

Response

A new SWIFT payment has been created

SWIFT payment creation response

​
amount
integer
required

Transaction amount in cents

​
createdAt
string<date-time>
required

Transaction creation timestamp

​
creditor
object
required

Creditor response

​
currency
string
required

Currency code

​
debtor
object
required

Debtor response

​
endToEndId
string
required

End-to-end identification

​
method
enum<string>
required

Transaction method (always SWIFT)

Available options:
SEPA,
INST,
SDD,
SWIFT
​
settlementDate
string<date>
required

Settlement date

​
status
string
required

Transaction status

​
transactionId
integer<int64>
required

Unique transaction identifier

​
remittance
string

Remittance information