Initiate an Internal Transfer Between Accounts

POST /v1/payments/internal — Transfers funds between two accounts at the same bank partner. Requires com.diameterpay.api/payments.write scope.

Transfer funds between two Diameter virtual accounts that are held at the same bank partner. Internal transfers settle immediately within the bank partner’s ledger and do not require external wire routing. Both accounts must belong to the same bank partner — attempting to transfer between accounts held at different bank partners will result in a validation error. Every request must include a unique x-idempotency-key to prevent duplicates on retry.

​

Endpoint

POST /v1/payments/internal

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 transfer. Generate a new UUID for each distinct transfer.

​

Request Body

endToEndId · string · required

Your unique reference for this transfer. Maximum 36 characters.

debtorAccountId · string · required

UUID of the Diameter virtual account to debit (the sending account).

creditorAccountId · string · required

UUID of the Diameter virtual account to credit (the receiving account). Must be at the same bank partner as debtorAccountId.

amount · string · required

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

currency · string · required

The transfer currency. Currently must be USD.

description · string · required

A description for the transfer, visible in transaction records. In the sandbox environment, prefix this value with AUTO_APPROVE to bypass the manual approval step (e.g., "AUTO_APPROVE Sweep to reserve account").

additionalInfo · string

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

​

Response Fields (201 Created)

id · string

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

​

Notes

• Both debtorAccountId and creditorAccountId must belong to the same bank partner (PORTAGE or SLOVAK_SAVINGS_BANK). Cross-bank-partner transfers are not supported via this endpoint — use a wire payment instead.
• Sandbox only: Prefix the description field with AUTO_APPROVE to have the transfer automatically approved without manual review. This flag has no effect in production.

​

Example Request

curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/internal" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: 883b1733-15ce-74a7-d049-779988773333" \
  --data '{
    "endToEndId": "INT-SWEEP-2024-001",
    "debtorAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "creditorAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": "5000.00",
    "currency": "USD",
    "description": "AUTO_APPROVE Daily sweep to reserve account",
    "additionalInfo": "Automated treasury sweep"
  }'

​

Example Response

{
  "id": "f6a7b8c9-d0e1-2345-fabc-de3456789012"
}