---
title: "Create an instant payment"
method: POST
path: "/v1/instant_payments"
tags: ["Instant Payments"]
---

# Create an instant payment

`POST /v1/instant_payments`

Initiates an outgoing instant payment.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `account_number_id` string, required — The ID of the Lead Bank Account Number object.
  - `amount` integer, required — The amount of the instant payment in cents.
  - `currency_code` 'USD', required — A three-letter currency code as defined in ISO 4217.
  - `description` string — Free-form information on the reason for the payment.
  - `creditor_agent` InstantPaymentAgent, required — Details of a financial institution in an instant payment.
    - `routing_number` string, required — The party's routing number.
  - `creditor` InstantPaymentParty, required — Details of a party in an instant payment.
    - `name` string, required — The party's name.
    - `account_number` string, required — The party's account number.

## Response `200`

The new instant payment object.

- InstantPayment
  - `id` string, required — The unique identifier of the instant payment object.
  - `account_id` string, required — The ID of the Account object.
  - `account_number_id` string, 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.
  - `amount` integer, required — The amount of the instant payment in cents.
  - `currency_code` 'USD', required — A three-letter currency code as defined in ISO 4217.
  - `description` string — Free-form information on the reason for the payment.
  - `debtor` InstantPaymentParty, required — Details of a party in an instant payment.
    - `name` string, required — The party's name.
    - `account_number` string, required — The party's account number.
  - `debtor_agent` InstantPaymentAgent, required — Details of a financial institution in an instant payment.
    - `routing_number` string, required — The party's routing number.
  - `creditor_agent` InstantPaymentAgent, required — Details of a financial institution in an instant payment.
    - `routing_number` string, required — The party's routing number.
  - `creditor` InstantPaymentParty, required — Details of a party in an instant payment.
    - `name` string, required — The party's name.
    - `account_number` string, required — The party's account number.
  - `payment_identifiers` InstantPaymentIdentifiers, required — The instant payment's identifiers.
    - `end_to_end_id` string — The identifier assigned by the party initiating the instant payment to be delivered to the customer unchanged.
    - `uetr` string, uuid — Unique End-to-End Transaction Reference (UETR). Must be an IETF RFC 4122 UUID.
    - `transaction_id` string — The identifier assigned by the initiating party or debtor to uniquely identify the transaction.
  - `return` InstantPaymentReturnDetails — If this instant payment is a return, this object contains details on the return.
    - `reason` 'honor_return_request' | 'wrong_amount' | 'duplication' | 'initiating_party_unrecognized' | 'fraud_suspected' | 'undue_payment' | 'narrative' | 'customer_requested' | 'regulatory_reason' | 'amount_too_low' | 'other', required — The reason for a 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 * `regulatory_reason` - Regulatory reason * `amount_too_low` - Amount too low * `other` - Other
    - `details` string — Details of the reason for the return including the 4-character ISO code when possible.
  - `rejection` InstantPaymentRejection — If this instant payment was rejected, this object contains details on the rejection.
    - `rejected_by` 'lead' | 'network' | 'counterparty', required — The party that rejected the instant payment.
    - `reason` 'account_closed' | 'creditor_account_number_invalid' | 'account_blocked' | 'wrong_amount' | 'creditor_name_mismatch' | 'creditor_address_incorrect' | 'creditor_identification_invalid' | 'duplication' | 'regulatory_reason' | 'narrative' | 'account_number_incorrect' | 'non_sufficient_funds' | 'aggregate_limit_exceeded' | 'participant_not_on_network' | 'routing_number_format_incorrect' | 'participant_signed_off' | 'restricted_by_account_number_controls' | 'other', required — The reason for the rejection. * `account_closed` - Closed creditor account * `creditor_account_number_invalid` - Invalid creditor account number * `account_blocked` - Blocked account * `wrong_amount` - Wrong amount * `creditor_name_mismatch` - Inconsistent end customer * `creditor_address_incorrect` - Missing or incorrect creditor address * `creditor_identification_invalid` - Invalid creditor identification * `duplication` - Duplicate * `regulatory_reason` - Regulatory * `narrative` - Narrative * `account_number_incorrect` - Account number incorrect or not active * `non_sufficient_funds` - Non-sufficient funds * `aggregate_limit_exceeded` - Aggregate limit exceeded * `participant_not_on_network` - Participant is not on an instant payment network * `routing_number_format_incorrect` - Routing number format is incorrect * `participant_signed_off` - Participant signed off * `restricted_by_account_number_controls` - Restricted by account number controls * `other` - Other
    - `details` string — Details of the reason for the rejection including the 4-character ISO code when possible.
  - `related_objects` InstantPaymentRelatedObjects, required — This instant payment's related instant payments or other objects.
    - `original_payment_id` string — If this instant payment is a return, the ID of the original payment this return is in reference to.
    - `return_payment_ids` string[] — If this instant payment was subsequently returned, the IDs of the payment returns.
  - `return_requests` InstantPaymentReturnRequest[], required — The return requests that reference this instant payment.
    - `status` 'pending' | 'response_needed' | 'accepted' | 'rejected', required — The current status of the return request object. For incoming return requests: response_needed, accepted, rejected. For outgoing return requests: pending, accepted, rejected.
    - `reason` 'creditor_account_number_invalid' | 'wrong_amount' | 'customer_requested' | 'duplication' | 'fraud_suspected' | 'narrative' | 'service_not_rendered' | 'technical_problem' | 'undue_payment' | 'per_agent_request' | 'other', required — The reason for the 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 * `per_agent_request` - Requested by agent * `other` - Other
    - `details` string — Details of the reason for the return request including the 4-character ISO code when possible.
    - `deadline` string, date-time — The deadline by which a final response to the return request is expected. For incoming return requests, you must respond by 11:30PM ET on the 10th business day. If you do not respond, we will respond on your behalf with a rejection at midnight. For outgoing return requests, the network deadline for the counterparty is 12:00AM ET on the 10th business day.
    - `resolution` InstantPaymentReturnRequestResolution — The resolution details of the return request.
      - `resolved_at` string, date-time, required — The ISO 8601 format timestamp that represents when the resolution occurred.
      - `resolved_by` 'client' | 'lead' | 'network' | 'counterparty', required — The party that resolved the return request.
      - `rejection_reason` 'account_closed' | 'non_sufficient_funds' | 'customer_requested' | 'legal_decision' | 'customer_no_response' | 'returned_previously' | 'narrative' | 'per_agent_request' | 'other' — The reason for a rejected return request. * `account_closed` - Account closed * `non_sufficient_funds` - Insufficient funds * `customer_requested` - Customer decision * `legal_decision` - Legal decision * `customer_no_response` - No answer from customer * `returned_previously` - Already returned * `narrative` - Narrative reason, additional_information required * `per_agent_request` - Agent decision * `other` - Other
      - `rejection_details` string — If the return request was rejected, details of the rejection reason including the 4-character ISO code when possible.
    - `created_at` string, date-time, required — The ISO 8601 format timestamp that represents when the return request object was created.
  - `created_at` string, date-time, required — The ISO 8601 format timestamp that represents when the instant payment object was created.
  - `updated_at` string, date-time, required — The ISO 8601 format timestamp that represents when the instant payment object was last updated.

## Other responses

- `400` — Your request parameters did not validate.
- `403` — You do not have permission to access this account.
- `422` — We couldn't process your request.
- `500` — Server error. Please try your request again.

---

[API](https://skmtc.net/lead/apis/lead-bank.md) · [All operations](https://skmtc.net/lead/apis/lead-bank/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lead/lead-bank/revisions/25c2a92d55e2/schema)