Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Instant Payments

Return an instant payment

Initiates an outgoing instant payment return. If there is an outstanding return request, invoking this endpoint is also understood as accepting the active return request.

post/v1/instant_payments/{instant_payment_id}/return

Path parameters

instant_payment_idstring required

ID of the instant payment object you want to return.

Headers

Idempotency-Keystring required

Idempotency key

Request body

reason'honor_return_request' | 'wrong_amount' | 'duplication' | 'initiating_party_unrecognized' | 'fraud_suspected' | 'undue_payment' | 'narrative' | 'customer_requested' required

The reason for initiating an return.

  • honor_return_request - Honoring a return request
  • wrong_amount - Wrong amount
  • duplication - Duplicate payment
  • initiating_party_unrecognized - Unknown sender
  • fraud_suspected - Fraud suspected
  • undue_payment - Unduly paid
  • narrative - Narrative reason, additional_information required
  • customer_requested - Requested by customer
additional_informationstring

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

Example request

{
  "reason": "duplication"
}

Response

The new outgoing return instant payment object.

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"
}