Initiate an Outbound Domestic Wire Payment

POST /v1/payments/wire/domestic — Send an outbound domestic wire with ABA routing. Requires com.diameterpay.api/payments.write scope.

Initiate an outbound domestic wire transfer from a Diameter virtual account to a US bank account. Counterparty details can be provided either as a reference to an existing saved counterparty (creditorId) or inline as a full creditor object. Domestic wires require an ABA routing number on the receiving bank. Every request must include a unique x-idempotency-key header to ensure safe retries without duplicate payments.

​

Endpoint

POST /v1/payments/wire/domestic

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

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. "100.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. This text is 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.

creditor.wireInformation.routingNumberType · string · required

Must be ABA for domestic wires.

creditor.wireInformation.routingNumber · string · required

The ABA routing number of the receiving bank (9 digits).

creditor.wireInformation.address · object

Postal address of the beneficiary. Recommended for compliance purposes.

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. US).

creditor.wireInformation.address.postalCode · string · required

Postal or ZIP code.

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 (e.g. NY, CA).

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.

​

Example Request — Using a Saved Counterparty

curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/wire/domestic" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "endToEndId": "PAY-2024-001",
    "debtorAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "2500.00",
    "currency": "USD",
    "description": "Invoice #1042 payment",
    "creditorId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "additionalInfo": "Approved by finance team on 2024-06-01"
  }'

​

Example Request — Using an Inline Creditor

curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/wire/domestic" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: 661f9511-f3ac-52e5-b827-557766551111" \
  --data '{
    "endToEndId": "PAY-2024-002",
    "debtorAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "1200.00",
    "currency": "USD",
    "description": "Supplier payment Q2",
    "creditor": {
      "type": "ORGANIZATION",
      "fullName": "Acme Supplies LLC",
      "wireInformation": {
        "bankName": "Chase Bank",
        "accountNumber": "000123456789",
        "routingNumberType": "ABA",
        "routingNumber": "021000021",
        "address": {
          "addressType": "BIZZ",
          "country": "US",
          "postalCode": "10001",
          "townName": "New York",
          "streetName": "Main St",
          "buildingNumber": "123",
          "countrySubdivision": "NY"
        }
      }
    }
  }'

​

Example Response

{
  "id": "d4e5f6a7-b8c9-0123-defa-bc1234567890",
  "creditorId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}