Skip to main content
POST
/
v1
/
instant_payments
/
{instant_payment_id}
/
return
Return an instant payment
curl --request POST \
  --url https://api.sandbox.lead.bank/v1/instant_payments/{instant_payment_id}/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "duplication",
  "additional_information": "<string>"
}
'
{
  "id": "instant_payment_xyz123",
  "account_id": "account_xyz123",
  "account_number_id": "account_number_xyz123",
  "direction": "outgoing",
  "status": "posted",
  "amount": 5000,
  "currency_code": "USD",
  "debtor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "debtor_agent": {
    "routing_number": "111000111"
  },
  "creditor_agent": {
    "routing_number": "111000111"
  },
  "creditor": {
    "name": "Alex Smith",
    "account_number": "1234567890"
  },
  "payment_identifiers": {
    "end_to_end_id": "E2E-20240101-001",
    "uetr": "8dc981d2-e8c2-4a7b-8df0-0781b46328d9",
    "transaction_id": "TXN-20240101-001"
  },
  "related_objects": {
    "original_payment_id": "instant_payment_xyz123",
    "return_payment_ids": [
      "instant_payment_xyz456"
    ]
  },
  "return_requests": [
    {
      "status": "pending",
      "reason": "duplicate",
      "created_at": "2022-06-27T11:22:33Z",
      "details": "<string>",
      "deadline": "2022-07-11T23:30:00-04:00",
      "resolution": {
        "resolved_at": "2022-06-27T11:22:33Z",
        "resolved_by": "counterparty",
        "rejection_reason": "customer_no_response",
        "rejection_details": "<string>"
      }
    }
  ],
  "created_at": "2022-06-27T11:22:33Z",
  "updated_at": "2022-06-27T11:22:40Z",
  "counterparty_status": "posted",
  "description": "Payment for invoice 12345",
  "return": {
    "reason": "duplication",
    "details": "<string>"
  },
  "rejection": {
    "rejected_by": "lead",
    "reason": "non_sufficient_funds",
    "details": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string
required

Idempotency key

Maximum string length: 255

Path Parameters

​
instant_payment_id
string
required

ID of the instant payment object you want to return.

Pattern: ^instant_payment_\w+$

Body

application/json
​
reason
enum<string>
required

The reason for the return.

Available options:
honor_return_request,
wrong_amount,
duplication,
initiating_party_unrecognized,
fraud_suspected,
undue_payment,
narrative,
customer_requested
Example:

"duplication"

​
additional_information
string

Accompanying free text explanation for the reason. Required if reason is "narrative" or "wrong_amount".

Maximum string length: 140

Response

The new outgoing return instant payment object.

​
id
string
required

The unique identifier of the instant payment object.

Pattern: ^instant_payment_\w+$
Example:

"instant_payment_xyz123"

​
account_id
string
required

The ID of the Account object.

Pattern: ^account_\w+$
Example:

"account_xyz123"

​
account_number_id
string
required

The ID of the Lead Bank Account Number object.

Pattern: ^account_number_\w+$
Example:

"account_number_xyz123"

​
direction
enum<string>
required

Who is initiating the transaction.

outgoing: You are sending a transaction to a counterparty. incoming: You are receiving a transaction from a counterparty.

Available options:
outgoing,
incoming
Example:

"outgoing"

​
status
enum<string>
required

The current status of the instant payment object. If outgoing: created, under_review, canceled, rejected, posted. If incoming: under_review, rejected, posted.

Available options:
created,
under_review,
canceled,
rejected,
posted
Example:

"posted"

​
amount
integer<int64>
required

The amount of the instant payment in cents.

Required range: x >= 0
Example:

5000

​
currency_code
enum<string>
required

A three-letter currency code as defined in ISO 4217.

Available options:
USD
Example:

"USD"

​
debtor
object
required

The details of the debtor (payer) sending the funds.

​
debtor_agent
object
required

The details of the financial institution where the debtor (payer) holds their account.

​
creditor_agent
object
required

The details of the financial institution where the creditor (payee) holds their account.

​
creditor
object
required

The details of the creditor (payee) receiving the funds.

​
payment_identifiers
object
required

The instant payment's identifiers.

​
related_objects
object
required

This instant payment's related instant payments or other objects.

​
return_requests
object[]
required

The return requests that reference this instant payment.

​
created_at
string<date-time>
required

The ISO 8601 format timestamp that represents when the instant payment object was created.

Example:

"2022-06-27T11:22:33Z"

​
updated_at
string<date-time>
required

The ISO 8601 format timestamp that represents when the instant payment object was last updated.

Example:

"2022-06-27T11:22:40Z"

​
counterparty_status
enum<string> | null

The current status of the instant payment from the counterparty's perspective. If outgoing: posted, under_review, or rejected. If incoming: posted or null.

Available options:
posted,
under_review,
rejected
Example:

"posted"

​
description
string

Free-form information on the reason for the payment.

Example:

"Payment for invoice 12345"

​
return
object

If this instant payment is a return, this object contains details on the return.

​
rejection
object

If this instant payment was rejected, this object contains details on the rejection.