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

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

> [card] Domestic Wire
>
> US domestic wire transfers using an ABA routing number. Use `routingNumberType: ABA`.
>
> `POST /v1/payments/wire/domestic`

> [card] International Wire
>
> Cross-border wire transfers using a BIC/SWIFT code. Use `routingNumberType: BIC`.
>
> `POST /v1/payments/wire/international`

> [card] 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](https://diameterpay.mintlify.site/concepts/counterparties.md) |
| `amount` | Payment amount as a string (e.g. `"100.00"`) |
| `currency` | Always `USD` |
| `description` | Payment description or reference |

> [!NOTE]
>
> Instead of `creditorId`, you can supply an inline `creditor` object with the recipient's full details directly in the payment request. See [Inline Creditor](#inline-creditor) below.

## Idempotency

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

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

> [!WARNING]
>
> 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:

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

> [!NOTE]
>
> 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:

```http theme={null}
POST /v1/payments/search
```

```json theme={null}
{
  "paymentId": "pmt_01abc123"
}
```

or:

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

> [!TIP]
>
> 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.


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