Skip to main content
POST
Create an instant payment

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

Body

application/json
account_number_id
string
required

The ID of the Lead Bank Account Number object.

Pattern: ^account_number_\w+$
Example:

"account_number_xyz123"

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. Only USD is supported.

Available options:
USD
Example:

"USD"

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.

description
string

Free-form information on the reason for the payment.

Maximum string length: 140
Example:

"Payment for invoice 12345"

Response

The new 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"

payment_rail
enum<string>
required

The payment network the instant payment travelled over.

Available options:
fednow,
rtp
Example:

"rtp"

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.

instructing_agent
object
required

The details of the network participant bank that submitted the payment into the network. For a standard payment this is the same as the debtor agent; where a participant routes on behalf of a non-participant the two differ. This object is always populated.

instructed_agent
object
required

The details of the network participant bank that received the payment from the network. For a standard payment this is the same as the creditor agent. This object is always populated.

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.

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"

ultimate_debtor
object

The party on whose behalf the payment is made, if different from the debtor (payer). Only present on on-behalf-of payments.

initiating_party
object

The party that transmitted the payment instruction. On outgoing payments this is set to your organization's name and cannot be changed. On incoming payments it is populated from the sending institution's message when provided.

ultimate_creditor
object

The party on whose behalf the payment is received, if different from the creditor (payee). Only present on on-behalf-of payments.

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.