International Payments

Send and receive payments in 20 currencies over SWIFT, the network banks use for cross-border payments. SWIFT payments pass through one or more correspondent banks on the way, so they are not instant and their timing depends on banks outside Modulr.

At a glance

When a payment goes via SWIFT

Modulr picks the most appropriate rail for each payment, based on the payment currency and the country of the beneficiary's bank:

• EUR to a SEPA country goes via SEPA, except EUR to the United Kingdom, which goes via SWIFT.
• GBP to the United Kingdom goes via Faster Payments or CHAPS.
• Any supported currency to any other allowed destination goes via SWIFT.

If the country isn't on the allowed destinations list for that currency, the request is rejected.

Supported currencies

Currency restrictions

THB and TRY: you can send these to any allowed destination, but the receiving account must be in the same name as the Modulr account you're paying from. This is a compliance requirement.

Sending a payment

Send international payments with Create a payment (POST /payments), the same endpoint you use for other payments.

1. Choose the destination type

Set destination.type according to where the beneficiary's bank account is held and what account details the beneficiary has given you.

A national bank code identifies the bank on its domestic network and is not the same as the BIC: for example the BSB in Australia, the IFSC in India and the routing (transit) number in Canada.

2. Add the required fields

Every international payment needs these fields, on top of the account identifier fields above.

3. Add as much beneficiary detail as you can

Banks along the payment chain screen each SWIFT payment, and missing beneficiary details can lead to delays or returns. Include these fields whenever you have them:

• destination.address.addressLine2, postCode (up to 10 characters) and countrySubDivision (up to 35 characters)
• countrySpecificDetails.business: true if the beneficiary is a business, false if an individual
• countrySpecificDetails.bankName, bankAddress, bankCity, bankBranchName and bankBranchCode
• destination.legalEntityIdentifier for business beneficiaries
• destination.birthdate, emailAddress and phoneNumber for individual beneficiaries
• purposeOfPayment, a code from the UK purpose code list. Some receiving banks require one.
• externalReference, your own reference of up to 50 characters, which comes back in webhooks

These request fields don't apply to international payments:

Allowed characters

Text fields can only contain:

• letters a-z and A-Z
• numbers 0-9
• space and . ( ) - / < + & $ * ; % @ = " \

Strip or replace anything else, including accented letters, before you submit.

Example requests

{
  "sourceAccountId": "A210000005",
  "currency": "AED",
  "amount": 2500.00,
  "reference": "INV 2026-0412",
  "externalReference": "po-88412",
  "purposeOfPayment": "GDSV",
  "destination": {
    "type": "IBAN",
    "iban": "AE070331234567890123456",
    "bic": "EXAMAEADXXX",
    "name": "Desert Trading LLC",
    "address": {
      "addressLine1": "Office 1204 Example Tower",
      "addressLine2": "Sheikh Zayed Road",
      "postTown": "Dubai",
      "country": "AE"
    },
    "countrySpecificDetails": {
      "bankName": "Example Bank PJSC",
      "bankCity": "Dubai",
      "bankCountry": "AE",
      "business": true
    }
  }
}

{
  "sourceAccountId": "A210000007",
  "currency": "USD",
  "amount": 10000.00,
  "reference": "Invoice 100139005",
  "destination": {
    "type": "ANBRN",
    "accountNumber": "45678956",
    "bic": "EXAMUS33XXX",
    "name": "Example Supplies Inc",
    "address": {
      "addressLine1": "345 Broadway",
      "addressLine2": "Floor 12",
      "postTown": "New York",
      "countrySubDivision": "NY",
      "postCode": "10013",
      "country": "US"
    },
    "countrySpecificDetails": {
      "abaRoutingNumber": "123456789",
      "bankName": "Example Bank NA",
      "bankCity": "New York",
      "bankCountry": "US",
      "business": true
    }
  }
}

{
  "sourceAccountId": "A210000009",
  "currency": "JPY",
  "amount": 150000,
  "reference": "Licence fee Q3",
  "destination": {
    "type": "AN",
    "accountNumber": "1234567",
    "bic": "EXAMJPJTXXX",
    "name": "Example Kabushiki Kaisha",
    "address": {
      "addressLine1": "1-2-3 Marunouchi",
      "postTown": "Tokyo",
      "postCode": "100-0005",
      "country": "JP"
    },
    "countrySpecificDetails": {
      "bankName": "Example Bank Ltd",
      "bankCity": "Tokyo",
      "bankBranchName": "Marunouchi",
      "bankBranchCode": "001",
      "bankCountry": "JP",
      "business": true
    }
  }
}

{
  "sourceAccountId": "A210000005",
  "currency": "USD",
  "amount": 750.00,
  "reference": "Consulting Sept",
  "destination": {
    "type": "SCAN",
    "sortCode": "000000",
    "accountNumber": "45678958",
    "bic": "EXAMGB2LXXX",
    "name": "Jane Smith",
    "address": {
      "addressLine1": "10 Example Street",
      "postTown": "London",
      "postCode": "SW12 6TP",
      "country": "GB"
    },
    "emailAddress": "[email protected]",
    "countrySpecificDetails": {
      "bankName": "Example Bank PLC",
      "bankCity": "London",
      "bankCountry": "GB",
      "business": false
    }
  }
}

After you send

Statuses and webhooks

A successful request returns HTTP 201 with a payment id. Track it to a final status with the PAYOUT webhook or Retrieve payments. Use PaymentId to de-duplicate webhooks.

PROCESSED means Modulr has released the payment to the SWIFT network. It doesn't mean the beneficiary has been credited: that happens when the payment reaches their bank, usually within 1 to 3 business days. Some payments take up to 5, and longer if a correspondent bank has to intervene manually.

See Payment Statuses for every status.

Returned payments

A correspondent or beneficiary bank can return a payment, and there's no fixed timescale for SWIFT returns. The returned funds arrive as a separate credit to your account, with a PAYIN webhook of type PO_REV and a return reason.

Receiving payments

Your payer's bank needs four things to reach your Modulr account:

1. Your IBAN and account name
2. Your account BIC
3. The intermediary (correspondent) BIC for your account BIC and currency
4. The name and address of the Modulr entity that holds your account

Your IBAN and BIC are in the Modulr Portal, and in the identifiers returned by Get an account:

{
  "id": "A1111111",
  "name": "SWIFT Account",
  "currency": "USD",
  "status": "ACTIVE",
  "identifiers": [
    {
      "type": "IBAN",
      "iban": "GB99MODR12345612345678",
      "bic": "MODRGB23XXX"
    }
  ]
}

The intermediary BIC depends on your account BIC and the currency:

Entity names, LEIs and addresses for each BIC are on Routing details for receiving SWIFT payments.

Tips for your payer

• Pay in the currency of the receiving account.
• Leave the intermediary field blank unless their bank insists on it. Most banks fill in routing automatically from their standard settlement instructions (SSIs).
• If their bank fills in an intermediary different from the one above, ask them to update their SSIs before sending.

When the payment is credited to your account you'll receive a PAYIN webhook.

Payment queries

You can't cancel, recall or trace a SWIFT payment yourself. If there's a problem with a payment you've sent, or a payment you're expecting hasn't arrived, contact Modulr Support.

Payments you've sent

Give Support the Modulr payment ID, so we can find the payment and follow it up with the banks involved.

Payments you're expecting

Modulr may not be able to see a SWIFT payment before it reaches us. Before contacting Support, ask the sending bank for a copy of the payment message they sent: an MT103, or a pacs.008 if they use ISO 20022. Check these fields:

If any of them is missing or wrong, ask the sending bank to correct it and send the payment again. If they're all correct and the payment still hasn't arrived, contact Support and include a copy of the message.

Related pages

• Allowed destinations for supported currencies
• Routing details for receiving SWIFT payments
• European Payments
• Payment Statuses
• Returned Payments