> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

**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.

**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.

**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](https://diameterpay.mintlify.site/api-reference/payments/get-payment.md).

**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

```bash theme={null}
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

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-cd2345678901",
  "creditorId": "c3d4e5f6-a7b8-9012-cdef-a12345678902"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.