Returns & Rejections

Returns

A return occurs when money leaves an account number but cannot reach its final destination. Lead models a return as a separate linked object: the original payment transitions to posted, and the linked return object carries the reversal. On a foreign exchange (FX) payout where currency conversion has already happened, Lead converts the funds back to USD at the new spot rate. The amount returned may not equal the amount you sent.

Return Life Cycle

Status Diagram For Docs (blockchain Payments) Page 1

Sample Object

{
    "id": "blockchain_payment_1234",
    "debtor": { ... },
    "creditor": { ... },
    // ...
    "return": {
        "code": "account_closed",
        "reason": "The destination account has been closed."
    },
    "related_blockchain_payments": {
        // present only on the return payment
        "original_blockchain_payment_id": "blockchain_payment_5678",
        // present only on the original payment
        "return_blockchain_payment_ids": ["blockchain_payment_9012"]
    }
}

Return Reasons

Code	Description	Client action
`account_closed`	The receiving account is closed and cannot accept the payment.	Send a new payment to a different destination account.
`payment_returned`	The receiving institution returned the payment for a reason with no more specific code.	Confirm the destination account details with the creditor before sending a new payment.

Every return code is terminal: the returned payment settles at posted with the funds back in the debtor account, so resubmitting the same payment unchanged returns it again.

Rejections

A rejection occurs when a payment never leaves the debtor account. Lead models a rejection as a terminal state in the blockchain_payment lifecycle.

Rejection Reasons

Each reason is either terminal — resubmitting the same payment cannot succeed — or retryable, meaning you can resubmit the same payment once the transient condition clears.

Code	Description	Client action
`payment_could_not_be_processed`	The payment could not be processed.	Terminal — Take no action. The cause is usually a compliance flag or a rejection by the receiving agent.
`name_mismatch`	The name in the request does not match the name on the account.	Terminal — Send a new payment with the corrected beneficiary name.
`name_not_validated`	Validation of the receiving account’s name did not finish in time.	Retryable — Submit the same payment again; it succeeds once verification of the beneficiary name completes.
`account_closed`	The receiving account is closed.	Terminal — Send a new payment to a different destination account.

Exceptions

An account can close in the narrow window after Lead validates it but before the payment posts. If the account closes before validation, Lead rejects the payment. If it closes after validation but before the payment posts, the payment results in a return.

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Returns

Return Life Cycle

Sample Object

Return Reasons

Rejections

Rejection Reasons

Exceptions

​Returns

​Return Life Cycle

​Sample Object

​Return Reasons

​Rejections

​Rejection Reasons

​Exceptions

Returns

Return Life Cycle

Sample Object

Return Reasons

Rejections

Rejection Reasons

Exceptions