Create an account-to-account transfer

post

https://api.uat.paymentology.com/pty/account/v1/transfers

Creates an account-to-account transfer.
Business-rule rejections (for example, insufficient funds) are returned as 201 with status REJECTED and failure_reason populated, not as a 4xx error.

Body Params

Account-to-account transfer request.

Both source_amount and destination_amount are required objects, each carrying its own
currency. Exactly one must supply amount; the server computes the other using
exchange_rate (rounding the result down to the nearest minor unit).

When source_amount.currency == destination_amount.currency, exchange_rate must be absent
or "1". When currencies differ, exchange_rate is required and follows the convention
destination_amount.amount = source_amount.amount × exchange_rate.

source_account_id

string

required

length between 1 and 50

Source account identifier

destination_account_id

string

required

length between 1 and 50

Destination account identifier

source_amount

object

required

A monetary amount with currency. amount is in minor units (positive integer string).

On a transfer request, both source_amount and destination_amount are present and each
carries its currency. Exactly one must supply amount — the server computes the other
and populates both on the stored record.
On a deposit request (destination_amount) and a withdrawal request (source_amount),
both amount and currency are always required.
On every response (Create or Get), all Money objects are fully populated (amount + currency).

destination_amount

object

required

A monetary amount with currency. amount is in minor units (positive integer string).

On a transfer request, both source_amount and destination_amount are present and each
carries its currency. Exactly one must supply amount — the server computes the other
and populates both on the stored record.
On a deposit request (destination_amount) and a withdrawal request (source_amount),
both amount and currency are always required.
On every response (Create or Get), all Money objects are fully populated (amount + currency).

exchange_rate

string

length ≤ 20

Exchange rate applied when computing the missing amount. Required when
source_amount.currency != destination_amount.currency; absent or "1" otherwise.

fee

object

Fee on an account-to-account transfer. The fee is additive to the principal:

Fee on source: source account is debited source_amount.amount + fee.amount.
Fee on destination: destination account is credited destination_amount.amount - fee.amount.
fee.currency must match the currency of the side the fee is charged to.

transaction_reference

string

required

length between 1 and 100

^\S+$

Client-provided unique transaction reference (idempotency key). Must not
contain whitespace.

transaction_description

string

length between 1 and 255

Human-readable description

Responses

403

Access token rejected by the API gateway (for example, expired).

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Transfer created

401Missing or invalid access token: UNAUTHORIZED, INVALID_CLIENT or INVALID_TENANT.

404ACCOUNT_NOT_FOUND: an account in the request does not exist or does not belong to the client.

409IDEMPOTENCY_CONFLICT: the transaction_reference was already used for a transfer with a different request body. Resending the identical request returns the original transfer with 201.

424DEPENDENCY_FAILURE: the ledger could not process the transfer. It was not completed and can be retried with the same transaction_reference.

500INTERNAL_SERVER_ERROR: unexpected error.

503SERVICE_UNAVAILABLE or INFRASTRUCTURE_ERROR: temporary failure. The transfer was not completed and can be retried with the same transaction_reference.