Initiate an Outbound International Wire Payment

POST /v1/payments/wire/international — Send an outbound international wire with BIC/SWIFT routing. Requires com.diameterpay.api/payments.write scope.

Initiate an outbound international wire transfer from a Diameter virtual account to a foreign bank account. The structure is identical to a domestic wire, but the beneficiary’s bank must be identified by a BIC/SWIFT code rather than an ABA routing number. Since v0.10.0, Diameter automatically resolves any required intermediary routing — you do not need to supply intermediaryRoutingNumber. Every request must include a unique x-idempotency-key header to prevent duplicate payments on retry.

​

Endpoint

POST /v1/payments/wire/international

Required scope: com.diameterpay.api/payments.write

​

Headers

Authorization · string · required

Bearer {access_token}

x-idempotency-key · string · required

A unique UUID v4 for this request. Re-submitting the same key returns the original response without creating a duplicate payment. Generate a new UUID for each logically distinct payment.

​

Request Body

endToEndId · string · required

Your unique reference for this payment. Maximum 36 characters. This value travels with the wire and appears in downstream bank records.

debtorAccountId · string · required

UUID of the Diameter virtual account that funds will be debited from.

amount · string · required

The payment amount as a decimal string, e.g. "500.00". Must be a positive value with up to two decimal places.

currency · string · required

The payment currency. Currently must be USD.

description · string · required

The Originator-to-Beneficiary Information (OBI) field. Maximum 255 characters. Forwarded to the receiving bank and appears on the beneficiary’s statement.

creditorId · string

UUID of a previously saved counterparty. Provide either creditorId or creditor — not both.

creditor · object

Inline counterparty details. Provide either creditor or creditorId — not both.

Show creditor fields

creditor.type · string · required

The counterparty type. One of ORGANIZATION or INDIVIDUAL.

creditor.fullName · string

Full legal name of the counterparty. Required when type is ORGANIZATION.

creditor.firstName · string

First name of the counterparty. Required when type is INDIVIDUAL.

creditor.lastName · string

Last name of the counterparty. Required when type is INDIVIDUAL.

creditor.wireInformation · object · required

Bank details for the receiving account.

Show wireInformation fields

creditor.wireInformation.bankName · string · required

Name of the receiving bank.

creditor.wireInformation.accountNumber · string · required

The beneficiary’s bank account number or IBAN.

creditor.wireInformation.routingNumberType · string · required

Must be BIC for international wires.

creditor.wireInformation.routingNumber · string · required

The BIC/SWIFT code of the receiving bank (8 or 11 characters).

creditor.wireInformation.address · object

Postal address of the beneficiary. Required by many correspondent banks for international wires.

Show address fields

creditor.wireInformation.address.addressType · string · required

Standardized address type code. One of ADDR, PBOX, HOME, BIZZ, MLTO, or DLVY.

creditor.wireInformation.address.country · string · required

ISO 3166-1 alpha-2 country code (e.g. DE, GB).

creditor.wireInformation.address.postalCode · string · required

Postal code for the address.

creditor.wireInformation.address.townName · string · required

City or town name.

creditor.wireInformation.address.streetName · string · required

Street name (excluding building number).

creditor.wireInformation.address.buildingNumber · string

Building or house number. Optional.

creditor.wireInformation.address.countrySubdivision · string

State or province code. Optional.

additionalInfo · string

Optional free-text field for supplementary payment notes. Maximum 255 characters.

​

Response Fields (201 Created)

id · string

The Diameter-issued UUID for the created payment. Use this to track status via Get Payment.

creditorId · string

UUID of the counterparty record. If you provided an inline creditor object, Diameter creates or matches a counterparty and returns its UUID here for future reuse.

​

Notes

• Set routingNumberType to BIC and supply the BIC/SWIFT code as routingNumber. Providing an ABA number will result in a validation error.
• Diameter automatically resolves and appends any required intermediary (correspondent) routing numbers since v0.10.0. You do not need to supply these.
• Beneficiary address is strongly recommended for regulatory compliance across most destination countries.

​

Example Request

curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/wire/international" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: 772a0622-04bd-63f6-c938-668877662222" \
  --data '{
    "endToEndId": "INTL-2024-005",
    "debtorAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "8000.00",
    "currency": "USD",
    "description": "Service contract payment Q3",
    "creditor": {
      "type": "ORGANIZATION",
      "fullName": "Global Tech GmbH",
      "wireInformation": {
        "bankName": "Deutsche Bank AG",
        "accountNumber": "DE89370400440532013000",
        "routingNumberType": "BIC",
        "routingNumber": "DEUTDEDB",
        "address": {
          "addressType": "BIZZ",
          "country": "DE",
          "postalCode": "60325",
          "townName": "Frankfurt",
          "streetName": "Taunusanlage",
          "buildingNumber": "12"
        }
      }
    },
    "additionalInfo": "Pre-approved by compliance 2024-06-10"
  }'

​

Example Response

{
  "id": "e5f6a7b8-c9d0-1234-efab-cd2345678901",
  "creditorId": "c3d4e5f6-a7b8-9012-cdef-a12345678902"
}