SWIFT Beneficiary (USD)

SWIFT is the international wire rail for USD payouts to bank accounts in 110+ countries. A SWIFT beneficiary is created with the same Add Beneficiary endpoint as any other beneficiary; only the destination object differs.

This page is the single reference for the SWIFT destination schema. The country pages under Beneficiaries show a ready-to-run sample per country and list only the fields that are specific to that country.

Sample request

curl --location '{{baseURL}}/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{APIKEY}}' \
--data '{
  "reference": "<sample-reference>",
  "customerEmail": "customer@example.com",
  "callbackUrl": "https://example.com/webhooks/beneficiaries",
  "country": "GB",
  "currency": "USD",
  "destination": {
    "type": "SWIFT",
    "accountName": "Ada Lovelace",
    "accountNumber": "GB29NWBK60161331926819",
    "swiftCode": "NWBKGB2L",
    "sortCode": "601613",
    "bankName": "NatWest Bank",
    "bankAddress": "250 Bishopsgate",
    "bankCity": "London",
    "bankPostCode": "EC2M 4AA",
    "bankCountry": "GB",
    "remittancePurpose": "FAMILY_SUPPORT",
    "beneficiary": {
      "type": "INDIVIDUAL",
      "country": "GB",
      "city": "London",
      "state": "England",
      "postCode": "EC2M 4AA",
      "address": "12 Baker Street",
      "phoneNumber": "+447700900123",
      "nationality": "GB",
      "idType": "PASSPORT",
      "idNumber": "P1234567",
      "idExpiration": "2030-01-15",
      "gender": "FEMALE",
      "dateOfBirth": "1990-05-20"
    },
    "sender": {
      "type": "INDIVIDUAL",
      "accountName": "John Smith",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "address": "123 Main St",
      "postCode": "10001",
      "phoneNumber": "+12125550123",
      "email": "john.smith@example.com",
      "gender": "MALE",
      "idType": "PASSPORT",
      "idNumber": "US1234567",
      "idIssueDate": "2020-06-01",
      "dateOfBirth": "1985-03-15",
      "countryOfBirth": "US",
      "complianceDocument": {
        "proofOfIdentity": "<document-reference>"
      }
    }
  }
}'

The top-level fields (reference, callbackUrl, customerEmail, country, currency) are the same as for every beneficiary; see Add Beneficiary. country is the destination country of the bank account.

Destination parameters

Beneficiary parameters

beneficiary.type: "INDIVIDUAL"

beneficiary.type: "BUSINESS"

Sender parameters

The sender is the person or company on whose behalf you send the funds. Sender details are bound to the beneficiary once created; to send from a different sender, create a new beneficiary (see Beneficiary basics).

sender.type: "INDIVIDUAL"

sender.type: "BUSINESS"

Compliance document

Every SWIFT sender must carry complianceDocument.proofOfIdentity: the key of a document uploaded with Upload Document.

• The value is the key returned by the upload, e.g. documents/<companyId>/<uuid>.pdf, not the signed url.
• Brails verifies that the key belongs to your business and that the file exists before accepting the beneficiary. An unknown key is rejected with Failed to create beneficiary; a foreign key with Upload does not belong to this company.
• The same key can be reused for every beneficiary created for the same sender. It is forwarded to the payout partner with every transfer.

Country-specific fields

Most countries accept the standard schema above. The countries below add or change destination fields.

Countries on the compact schema (China, Côte d'Ivoire, Gambia, Ghana, Guinea, Kenya, Liberia, Malawi, Nigeria, Rwanda, Senegal, Tanzania, Uganda) and Canada, India, Guyana and El Salvador do not use bankState or intermediaryBank; the fields are ignored if sent.

To discover the exact fields for a country programmatically, call Get Supported Countries with the country code: the destination entry lists one field set per payment method.

Enumerations

Remittance purposes

FAMILY_SUPPORT, EDUCATION, GIFT_AND_DONATION, MEDICAL_TREATMENT, MAINTENANCE_EXPENSES, TRAVEL, SMALL_VALUE_REMITTANCE, LIBERALIZED_REMITTANCE, OTHER, CONSTRUCTION_EXPENSES, HOTEL_ACCOMMODATION, ADVERTISING_EXPENSES, ADVISORY_FEES, BUSINESS_INSURANCE, INSURANCE_CLAIMS, DELIVERY_FEES, EXPORTED_GOODS, SERVICE_CHARGES, LOAN_PAYMENT, OFFICE_EXPENSES, PROPERTY_PURCHASE, PROPERTY_RENTAL, ROYALTY_FEES, SHARES_INVESTMENT, FUND_INVESTMENT, TAX_PAYMENT, TRANSPORTATION_FEES, UTILITY_BILLS, PERSONAL_TRANSFER, SALARY_PAYMENT, OTHER_FEES, COMPUTER_SERVICES, REWARD_PAYMENT, INFLUENCER_PAYMENT

ID types

NATIONAL_ID, PASSPORT, DRIVING_LICENSE, GOVERNMENT_ID, CITIZENSHIP_CARD, SENIOR_CITIZEN_ID, RESIDENCE_PERMIT, RESIDENT_CARD, GCC_ID, EMIRATES_ID, TAX_ID

Business types

AGRICULTURE, AUTOMOTIVE, BANKING, FINTECH, CONSTRUCTION, EDUCATION, INFORMATION_TECHNOLOGY, MANUFACTURING, RETAIL, REAL_ESTATE, TRANSPORTATION_AND_LOGISTICS, PROFESSIONAL_SERVICES, OTHERS

Business registration types

PARTNERSHIP, CORPORATION, SOLE_PROPRIETORSHIP, GOVERNMENT, NGO, PRIVATE_LTD, LLC, BSC

Genders

MALE, FEMALE, OTHERS

Paying a SWIFT beneficiary

1. Create the beneficiary as above and wait for beneficiary.status.changed. SWIFT beneficiaries can be paid while PENDING, PROCESSING or SUCCESS.
2. Call Quote to get the fee and rate.
3. Initiate the payout with beneficiaryId. The amount is in cents. For business transactions pass the invoice key as receiptRef.
4. If you did not pass receiptRef, attach the document before finalizing.
5. Finalize the payout (legacy flow) or wait for the payout webhook.

Settlement, limits and fees

• Settlement: T + 3 business days after the payout is processed. See Transfers for cut-off times.
• Limits: per-country USD limits are listed on Supported Countries. Amounts outside the range are rejected with Amount is below minimum limit or Amount is above maximum limit.
• Fees: SWIFT payouts use a tiered fee that depends on the amount. The Quote response returns the exact fee for a given amount.

Validation errors

Beneficiary creation returns 400 with one of the messages below when the payload does not meet the SWIFT rules.

Example schema failure:

{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "details": [
    {
      "path": "destination.swiftCode",
      "message": "Invalid SWIFT/BIC format. Must be 8 or 11 characters: AAAABBCC or AAAABBCCDDD",
      "code": "invalid_pattern"
    },
    {
      "path": "destination.sender.phoneNumber",
      "message": "Sender phone number must be in the msisdn international format (+15551234567)",
      "code": "invalid_pattern"
    }
  ]
}