Create international recipient

POST /recipients/international
Bearer auth

Create a recipient for international bank transfers. The data fields are specific to the transfer corridors. Please refer to the Schema section for the details.

Headers

  • Workspace-ID integer Required

    The workspace ID - to identify the sub-user

Query parameters

  • payoutMethod string Required

    Payment method (e.g., LOCAL, SWIFT)

    Values are LOCAL or SWIFT.

  • currencyCode string Required

    Destination currency code

  • countryCode string Required

    Destination country code

application/json

Body Required

  • alias string

    Optional recipient nickname

  • data object Required
    Hide data attributes Show data attributes object
    • beneficiaryAccountNumber string Required

      Recipient account number

    • beneficiaryAccountType string Required

      Account type (Individual/Corporate)

    • beneficiaryAddress string Required

      Recipient address

    • beneficiaryCountryCode string Required

      Recipient country code

    • beneficiaryName string Required

      Recipient full name

    • destinationCountry string Required

      Destination country code

    • routingCodeType1 string Required

      Routing code type (SWIFT / IFSC for India / SORT CODE for UK / ACH CODE for USA / BRANCH CODE for Brazil and Bangladesh / BSB CODE for Australia / BANK CODE for HongKong)

    • routingCodeValue1 string Required

      Routing code value (e.g., SWIFT code)

  • saved boolean Required

    Save recipient for future use

Responses

  • 201 application/json

    Recipient created successfully

    Hide response attributes Show response attributes object
    • accountCode string Required

      Recipient account code

    • alias string

      Recipient nickname

    • createdAt string

      Creation timestamp

    • edges object
      Hide edges attributes Show edges attributes object
      • bank object

        Bank information including name and SWIFT code

        Hide bank attributes Show bank attributes object
        • countryCode string

          Bank country code (ISO 3166-1 alpha-2)

        • createdAt string

          Creation timestamp

        • id integer Required

          Bank ID

        • name string Required

          Bank name

        • swiftCode string

          Bank SWIFT/BIC code

        • updatedAt string

          Last update timestamp

      • beneficiary object

        Beneficiary information for international transfers

        Hide beneficiary attributes Show beneficiary attributes object
        • createdAt string

          Creation timestamp

        • data object
        • id integer Required

          Beneficiary ID

        • updatedAt string

          Last update timestamp

      • currency object

        Currency information including symbol, code, and decimal places

        Hide currency attributes Show currency attributes object
        • code string Required

          ISO currency code (e.g., USD, EUR)

        • createdAt string

          Creation timestamp

        • decimals integer

          Number of decimal places

        • id integer Required

          Currency ID

        • name string Required

          Currency full name

        • swiftMinimumWithdrawalAmount string

          Minimum SWIFT withdrawal amount

        • symbol string

          Currency symbol (e.g., $, €)

        • updatedAt string

          Last update timestamp

    • id integer Required

      Recipient ID

    • name string Required

      Recipient name

    • saved boolean

      Whether recipient is saved

    • updatedAt string

      Last update timestamp
  • 400 application/json

    Invalid request

    Hide response attributes Show response attributes object
    • errorCode string Required

      Error code

    • message string Required

      Error message
  • 401 application/json

    Unauthorized

    Hide response attributes Show response attributes object
    • errorCode string Required

      Error code

    • message string Required

      Error message
  • 409

    Recipient already exists

POST /recipients/international 
curl \
 --request POST 'https://bank.bank.place/recipients/international?payoutMethod=LOCAL&currencyCode=VND&countryCode=VN' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "Workspace-ID: 42" \
 --data '{"data":{"beneficiaryName":"John Doe","routingCodeType1":"SWIFT","routingCodeValue1":"BFTVVNVX","beneficiaryAddress":"Street address","destinationCountry":"VN","beneficiaryAccountType":"Individual","beneficiaryCountryCode":"VN","beneficiaryAccountNumber":"190281938"},"alias":"","saved":true}'
Request example 
{
  "data": {
    "beneficiaryName": "John Doe",
    "routingCodeType1": "SWIFT",
    "routingCodeValue1": "BFTVVNVX",
    "beneficiaryAddress": "Street address",
    "destinationCountry": "VN",
    "beneficiaryAccountType": "Individual",
    "beneficiaryCountryCode": "VN",
    "beneficiaryAccountNumber": "190281938"
  },
  "alias": "",
  "saved": true
}
Response examples (201) 
{
  "accountCode": "string",
  "alias": "string",
  "createdAt": "string",
  "edges": {
    "bank": {
      "countryCode": "string",
      "createdAt": "string",
      "id": 42,
      "name": "string",
      "swiftCode": "string",
      "updatedAt": "string"
    },
    "beneficiary": {
      "createdAt": "string",
      "data": {},
      "id": 42,
      "updatedAt": "string"
    },
    "currency": {
      "code": "string",
      "createdAt": "string",
      "decimals": 42,
      "id": 42,
      "name": "string",
      "swiftMinimumWithdrawalAmount": "string",
      "symbol": "string",
      "updatedAt": "string"
    }
  },
  "id": 42,
  "name": "string",
  "saved": true,
  "updatedAt": "string"
}
Response examples (400) 
{
  "message": "Invalid request parameters",
  "errorCode": "invalid_request"
}
Response examples (401) 
{
  "message": "Invalid request parameters",
  "errorCode": "invalid_request"
}