PApaymentology
Ledger API - Transfers

Create an account-to-account transfer

<ul> <li class="docBullet">Creates an account-to-account transfer.</li> <li class="docBullet">Business-rule rejections (for example, insufficient funds) are returned as 201 with status REJECTED and failure_reason populated, not as a 4xx error.</li> </ul>
post/pty/account/v1/transfers

Request

  • Base URL
    https://api.uat.paymentology.com
  • URL
    https://api.uat.paymentology.com/pty/account/v1/transfers
  • Auth
    HTTP bearer

Request body

source_account_idstring required

Source account identifier

destination_account_idstring required

Destination account identifier

exchange_ratestring

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

transaction_referencestring required

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

transaction_descriptionstring

Human-readable description

Example request

{
  "source_account_id": "479823917",
  "destination_account_id": "583198002",
  "source_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "destination_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "exchange_rate": "17.22000",
  "fee": {
    "amount": "100",
    "currency": "USD",
    "type": "TRANSFER_FEE"
  },
  "transaction_reference": "tfr_t1a_001",
  "transaction_description": "Internal Transfer"
}

Response

Transfer created

transfer_idstring uuid required

Unique transfer identifier.

source_account_idstring required

Source account identifier.

destination_account_idstring required

Destination account identifier.

exchange_ratestring

Exchange rate applied (present for cross-currency transfers).

transaction_referencestring required

Client-provided unique transaction reference.

transaction_descriptionstring

Human-readable description.

status'IN_PROGRESS' | 'COMPLETED' | 'REJECTED' | 'FAILED' required

Transaction processing status (shared across transfers, deposits, and withdrawals).

  • IN_PROGRESS — request persisted, operation in progress (non-terminal).
  • COMPLETED — operation executed successfully (terminal).
  • REJECTED — operation refused by a business rule (terminal). The specific reason is carried in failure_reason.code.
  • FAILED — operation failed due to a transient error (non-terminal). The specific reason is carried in failure_reason.code.
updated_atstring date-time required

Timestamp of the last update.

source_account_balance_afterstring nullable

The source account's net available balance, in minor units, immediately after this transfer. Present only when status is COMPLETED.

destination_account_balance_afterstring nullable

The destination account's net available balance, in minor units, immediately after this transfer. Present only when status is COMPLETED.

Example response

{
  "transfer_id": "7bb83d05-2f62-4689-bc56-f9378a9de566",
  "source_account_id": "479823917",
  "destination_account_id": "583198002",
  "source_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "destination_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "exchange_rate": "17.22000",
  "fee": {
    "amount": "100",
    "currency": "USD",
    "type": "TRANSFER_FEE"
  },
  "transaction_reference": "tfr_t1a_001",
  "transaction_description": "Internal Transfer",
  "failure_reason": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Source account has insufficient funds to complete this operation"
  },
  "updated_at": "2026-01-15T10:35:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.