Payments: Wire Transfers and Internal Transactions

Diameter supports domestic wire, international wire, and internal transfers. Learn about payment types, statuses, and the full payment lifecycle.

Diameter lets you initiate wire payments and internal transfers on behalf of your end users. Every payment passes through compliance screening before being forwarded to a partner bank, and you receive webhook notifications at each step of the process.

​

Payment Types

Diameter supports three payment types:

Domestic Wire

US domestic wire transfers using an ABA routing number. Use routingNumberType: ABA.

POST /v1/payments/wire/domestic

International Wire

Cross-border wire transfers using a BIC/SWIFT code. Use routingNumberType: BIC.

POST /v1/payments/wire/international

Internal Transfer

Transfers between two accounts held at the same partner bank.

POST /v1/payments/internal

​

Payment Lifecycle

Every payment moves through the following statuses in order:

1. SCREENING_REQUESTED

   The payment has been submitted and is under compliance review by Diameter.

2. SCREENING_PASSED

   Compliance screening approved the payment. Diameter is preparing to route it.

3. ROUTED

   The payment has been forwarded to the partner bank for processing.

4. RECEIVED_BY_PARTNER

   The partner bank has acknowledged receipt of the payment instruction.

5. COMPLETED

   The payment was successfully executed and funds have been transferred.

If anything goes wrong at any step, the payment moves to FAILED instead.

Terminal Status	Meaning
COMPLETED	Payment executed successfully
FAILED	Payment could not be completed

​

Required Fields for Wire Payments

Every wire payment request requires the following fields:

Field	Description
endToEndId	Your unique reference for this payment (max 36 characters)
debtorAccountId	The Diameter account ID to send funds from
creditorId	ID of a pre-registered counterparty
amount	Payment amount as a string (e.g. "100.00")
currency	Always USD
description	Payment description or reference

Instead of creditorId, you can supply an inline creditor object with the recipient’s full details directly in the payment request. See Inline Creditor below.

​

Idempotency

All write requests (POST, PATCH) require an idempotency key to prevent duplicate payments:

x-idempotency-key: <UUID>

Generate a new UUID for each unique payment attempt. If you retry a request with the same key, Diameter returns the original response without creating a duplicate payment.

Always set x-idempotency-key on every write request. Omitting it will result in a 400 validation error.

​

Inline Creditor

You can specify a counterparty inline in the payment request instead of pre-registering them. Provide the full counterparty details in the creditor field of your payment request body:

{
  "creditor": {
    "type": "INDIVIDUAL",
    "firstName": "Jane",
    "lastName": "Smith",
    "wireInformation": {
      "bankName": "Example Bank",
      "accountNumber": "123456789",
      "routingNumberType": "ABA",
      "routingNumber": "021000021",
      "address": { ... }
    }
  }
}

Inline creditors are available from API v0.11.0 onwards. Pre-registering counterparties in advance is still recommended for frequently used recipients to avoid compliance delays.

​

Tracking Payments

Each payment receives:

Identifier	Description
id	Unique Diameter payment ID
idAssignedByBank	Reference number assigned by the partner bank (once routed)
wire.initialImad	Initial IMAD assigned at wire submission
wire.finalImad	Final IMAD confirming Federal Reserve receipt (domestic wires)

​

Searching Payments

Retrieve payment details by payment ID or your end-to-end reference:

POST /v1/payments/search

{
  "paymentId": "pmt_01abc123"
}

or:

{
  "endToEndId": "your-reference-id"
}

​

Webhooks

Diameter fires a webhook event every time a payment changes status. Subscribe to these events to drive real-time updates in your application:

Event	Trigger
PAYMENT_WIRE_OUTBOUND_COMPLETED	Payment reached COMPLETED status
PAYMENT_WIRE_OUTBOUND_FAILED	Payment reached FAILED status

Additional events fire for each intermediate status change. Configure your webhook endpoint in the Diameter dashboard.

​

Sandbox Testing

In the sandbox environment, use the simulation endpoint to move a payment through its lifecycle without waiting for live bank processing. Post to POST /v1/simulation/payments with the payment ID and the WIRE_INBOUND scenario to simulate an inbound wire completing. This endpoint is available in sandbox only and is the recommended way to test end-to-end payment flows.