Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Instant Payments

Request return for an instant payment

Send a return request to the counterparty for a previously posted outgoing instant payment. Returns the updated instant payment object with a new entry in the return_requests array.

post/v1/instant_payments/{instant_payment_id}/request_return

Path parameters

instant_payment_idstring required

ID of the instant payment object you want to request a return for.

Headers

Idempotency-Keystring required

Idempotency key

Request body

reason'creditor_account_number_invalid' | 'wrong_amount' | 'customer_requested' | 'duplication' | 'fraud_suspected' | 'narrative' | 'service_not_rendered' | 'technical_problem' | 'undue_payment' required

The reason for initiating a return request.

  • creditor_account_number_invalid - Invalid creditor account number
  • wrong_amount - Wrong amount
  • customer_requested - Requested by customer
  • duplication - Duplicate payment
  • fraud_suspected - Fraud suspected
  • narrative - Narrative reason, additional_information required
  • service_not_rendered - Service not rendered
  • technical_problem - Technical problem
  • undue_payment - Unduly paid
additional_informationstring

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

Example request

{
  "reason": "duplication"
}

Response

The updated instant payment object with a new return request in the return_requests array.

idstring required

The unique identifier of the instant payment object.

account_idstring required

The ID of the Account object.

account_number_idstring required

The ID of the Lead Bank Account Number object.

direction'outgoing' | 'incoming' required

Who is initiating the transaction.

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

status'created' | 'under_review' | 'canceled' | 'rejected' | 'posted' required

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

counterparty_status'posted' | 'under_review' | 'rejected' nullable

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

amountinteger required

The amount of the instant payment in cents.

currency_code'USD' required

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

descriptionstring

Free-form information on the reason for the payment.

created_atstring date-time required

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

updated_atstring date-time required

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

Example response

{
  "id": "instant_payment_xyz123",
  "account_id": "account_xyz123",
  "account_number_id": "account_number_xyz123",
  "direction": "outgoing",
  "status": "posted",
  "counterparty_status": "posted",
  "amount": 5000,
  "currency_code": "USD",
  "description": "Payment for invoice 12345",
  "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": "033me5upSkktRorr3J6TKZ",
    "uetr": "8dc981d2-e8c2-4a7b-8df0-0781b46328d9",
    "transaction_id": "3G0CQxK8gKLpzaaxc7A9spDiifK"
  },
  "return": {
    "reason": "duplication"
  },
  "rejection": {
    "rejected_by": "lead",
    "reason": "non_sufficient_funds"
  },
  "related_objects": {
    "original_payment_id": "instant_payment_xyz123",
    "return_payment_ids": [
      "instant_payment_xyz456"
    ]
  },
  "return_requests": [
    {
      "status": "pending",
      "reason": "duplicate",
      "deadline": "2022-07-11T23:30:00-04:00",
      "resolution": {
        "resolved_at": "2022-06-27T11:22:33Z",
        "resolved_by": "counterparty",
        "rejection_reason": "customer_no_response"
      },
      "created_at": "2022-06-27T11:22:33Z"
    }
  ],
  "created_at": "2022-06-27T11:22:33Z",
  "updated_at": "2022-06-27T11:22:40Z"
}