Lead Bank Instant Payments API
The Instant Payments API from Lead Bank — 7 operation(s) for instant payments.
OpenAPI Specification
openapi: 3.0.1
info:
title: Lead Bank Account Number Instant Payments API
description: Lead Bank's APIs
version: v1.0
servers:
- url: https://api.sandbox.lead.bank
- url: https://api.lead.bank
security:
- bearerAuth: []
tags:
- name: Instant Payments
paths:
/v1/instant_payments:
post:
tags:
- Instant Payments
operationId: create-an-instant-payment
summary: Create an instant payment
description: Initiates an outgoing instant payment.
parameters:
- name: Idempotency-Key
in: header
description: Idempotency key
required: true
schema:
type: string
maxLength: 255
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- account_number_id
- amount
- currency_code
- creditor_agent
- creditor
properties:
account_number_id:
$ref: '#/components/schemas/AccountNumberID'
description: The ID of the Lead Bank Account Number object.
amount:
$ref: '#/components/schemas/InstantPaymentAmount'
description: The amount of the instant payment in cents.
currency_code:
$ref: '#/components/schemas/CurrencyCode'
description: A three-letter currency code as defined in ISO 4217. Only USD is supported.
description:
type: string
maxLength: 140
description: Free-form information on the reason for the payment.
example: Payment for invoice 12345
creditor_agent:
$ref: '#/components/schemas/InstantPaymentAgent'
description: The details of the financial institution where the creditor (payee) holds their account.
creditor:
$ref: '#/components/schemas/InstantPaymentParty'
description: The details of the creditor (payee) receiving the funds.
responses:
'200':
description: The new instant payment object.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'400':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You do not have permission to access this account.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: We couldn't process your request.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
get:
tags:
- Instant Payments
operationId: list-all-instant-payments
summary: List all instant payments
description: List instant payments with optional filtering.
parameters:
- name: account_id
description: Returns instant payments associated with this `account_id`.
in: query
schema:
type: string
pattern: ^account_\w+$
- name: account_number_id
description: Returns instant payments associated with this `account_number_id`.
in: query
schema:
type: string
pattern: ^account_number_\w+$
- name: direction
description: Returns instant payments with the given direction.
in: query
schema:
$ref: '#/components/schemas/Direction'
- name: status
description: Returns instant payments with the given status.
in: query
schema:
$ref: '#/components/schemas/InstantPaymentStatus'
- name: counterparty_status
description: Returns instant payments with the given counterparty status.
in: query
schema:
$ref: '#/components/schemas/InstantPaymentCounterpartyStatus'
- name: return_request_status
description: Returns instant payments that have a return request with the given status.
in: query
schema:
$ref: '#/components/schemas/InstantPaymentReturnRequestStatus'
- name: created_at
description: A set of filters on the list using the object's field `created_at`.
in: query
style: deepObject
explode: true
schema:
type: object
properties:
after:
type: string
format: date-time
description: Returns objects where the `created_at` timestamp is after the entered timestamp.
on_or_after:
type: string
format: date-time
description: Returns objects where the `created_at` timestamp is the same as or after the entered timestamp.
before:
type: string
format: date-time
description: Returns objects where the `created_at` timestamp is before the entered timestamp.
on_or_before:
type: string
format: date-time
description: Returns objects where the `created_at` timestamp is the same as or before the entered timestamp.
- name: limit
description: Maximum number of objects to be returned.
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: starting_after
description: A cursor for use in pagination; this is an ID that defines your place in the list.
in: query
schema:
type: string
pattern: ^instant_payment_\w+$
- name: ending_before
description: A cursor for use in pagination; this is an ID that defines your place in the list.
in: query
schema:
type: string
pattern: ^instant_payment_\w+$
responses:
'200':
description: A list of instant payment objects.
content:
application/json:
schema:
type: object
required:
- objects
- has_more
properties:
objects:
type: array
items:
$ref: '#/components/schemas/InstantPayment'
has_more:
type: boolean
description: Indicates whether more results are available.
'403':
description: You do not have permission to access instant payments.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/{instant_payment_id}:
get:
tags:
- Instant Payments
operationId: retrieve-an-instant-payment
summary: Retrieve an instant payment
description: Retrieve the details of an instant payment.
parameters:
- name: instant_payment_id
description: ID of the instant payment object you want to retrieve.
example: instant_payment_xyz001
in: path
required: true
schema:
type: string
pattern: ^instant_payment_\w+$
responses:
'200':
description: An instant payment object.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'403':
description: You do not have permission to access this instant payment.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'404':
description: Instant payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/{instant_payment_id}/return:
post:
tags:
- Instant Payments
operationId: return-an-instant-payment
summary: Return an instant payment
description: '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.'
parameters:
- name: Idempotency-Key
in: header
description: Idempotency key
required: true
schema:
type: string
maxLength: 255
- name: instant_payment_id
description: ID of the instant payment object you want to return.
example: instant_payment_xyz001
in: path
required: true
schema:
type: string
pattern: ^instant_payment_\w+$
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- reason
properties:
reason:
$ref: '#/components/schemas/OutgoingInstantPaymentReturnReason'
description: The reason for the return.
additional_information:
type: string
maxLength: 140
description: Accompanying free text explanation for the reason. Required if reason is "narrative" or "wrong_amount".
responses:
'200':
description: The new outgoing return instant payment object.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'400':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You do not have permission to access instant payments.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'404':
description: Instant payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: We couldn't process your request.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/{instant_payment_id}/cancel:
post:
tags:
- Instant Payments
operationId: cancel-an-instant-payment
summary: Cancel an instant payment
description: 'Attempt to cancel an outgoing instant payment that is currently in "created" or "under_review"
status.'
parameters:
- name: instant_payment_id
description: ID of the instant payment object you want to cancel.
example: instant_payment_xyz001
in: path
required: true
schema:
type: string
pattern: ^instant_payment_\w+$
responses:
'200':
description: Updated canceled instant payment object.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'400':
description: Operation cannot be done on this object.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'404':
description: Instant payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: The instant payment has already been submitted and cannot be canceled.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/{instant_payment_id}/request_return:
post:
tags:
- Instant Payments
operationId: request-return-for-instant-payment
summary: Request return for an instant payment
description: '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.'
parameters:
- name: Idempotency-Key
in: header
description: Idempotency key
required: true
schema:
type: string
maxLength: 255
- name: instant_payment_id
description: ID of the instant payment object you want to request a return for.
example: instant_payment_xyz001
in: path
required: true
schema:
type: string
pattern: ^instant_payment_\w+$
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- reason
properties:
reason:
$ref: '#/components/schemas/OutgoingInstantPaymentReturnRequestReason'
description: The reason for the return request.
additional_information:
type: string
maxLength: 140
description: 'Accompanying free text explanation for the reason. Required if reason is
"narrative", "wrong_amount", or "service_not_rendered".'
responses:
'200':
description: The updated instant payment object with a new return request in the return_requests array.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'400':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You do not have permission to access instant payments.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'404':
description: Instant payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'409':
description: There is an active return request already associated with this payment.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: We couldn't process your request.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/{instant_payment_id}/reject_return_request:
post:
tags:
- Instant Payments
operationId: reject-return-request-for-instant-payment
summary: Reject return request for an instant payment
description: 'Reject the active return request associated with an incoming instant payment.
Returns the updated instant payment object with the status of the active return request set to "rejected".'
parameters:
- name: instant_payment_id
description: ID of the instant payment object whose return request you want to reject.
example: instant_payment_xyz001
in: path
required: true
schema:
type: string
pattern: ^instant_payment_\w+$
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- reason
properties:
reason:
$ref: '#/components/schemas/OutgoingInstantPaymentReturnRequestRejectionReason'
description: The reason for rejecting the return request.
additional_information:
type: string
maxLength: 140
description: Accompanying free text explanation for the reason. Required if reason is "narrative".
responses:
'200':
description: The updated instant payment object with the return request status set to "rejected".
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPayment'
'400':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'403':
description: You do not have permission to access instant payments.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'404':
description: Instant payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: We couldn't process your request.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
/v1/instant_payments/check_availability:
post:
tags:
- Instant Payments
operationId: check-instant-payment-availability
summary: Check instant payment availability
description: Check if a given routing number is eligible to receive an instant payment.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- routing_number
properties:
routing_number:
type: string
description: The routing number of the financial institution where the creditor (payee) holds their account.
minLength: 9
maxLength: 9
pattern: ^[0-9]+$
example: '111000111'
responses:
'200':
description: Availability check result.
content:
application/json:
schema:
$ref: '#/components/schemas/InstantPaymentAvailability'
'400':
description: Your request parameters did not validate.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'422':
description: The routing number is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
'500':
description: Server error. Please try your request again.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
components:
schemas:
AccountNumberID:
type: string
description: The ID of the Lead Bank Account Number object.
example: account_number_xyz123
pattern: ^account_number_\w+$
IncomingInstantPaymentReturnRequestReason:
type: string
description: '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'
example: duplicate
enum:
- creditor_account_number_invalid
- wrong_amount
- customer_requested
- duplication
- fraud_suspected
- narrative
- service_not_rendered
- technical_problem
- undue_payment
- per_agent_request
- other
InstantPaymentReturnRequestResolution:
type: object
description: The resolution details of the return request.
required:
- resolved_at
- resolved_by
properties:
resolved_at:
type: string
format: date-time
description: The ISO 8601 format timestamp that represents when the resolution occurred.
example: '2022-06-27T11:22:33Z'
resolved_by:
type: string
description: The party that resolved the return request.
enum:
- client
- lead
- network
- counterparty
example: counterparty
rejection_reason:
$ref: '#/components/schemas/IncomingInstantPaymentReturnRequestRejectionReason'
description: If the return request was rejected, the reason for the rejection.
rejection_details:
type: string
description: If the return request was rejected, details of the rejection reason including the 4-character ISO code when possible.
OutgoingInstantPaymentReturnRequestRejectionReason:
type: string
description: 'The reason for rejecting an incoming 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'
example: customer_requested
enum:
- account_closed
- non_sufficient_funds
- customer_requested
- legal_decision
- customer_no_response
- returned_previously
- narrative
InstantPaymentReturnRequestStatus:
type: string
description: 'The current status of the return request object.
For incoming return requests: response_needed, accepted, rejected.
For outgoing return requests: pending, accepted, rejected.'
example: pending
enum:
- pending
- response_needed
- accepted
- rejected
APIError:
type: object
properties:
code:
type: string
description: The error code.
title:
type: string
description: The error title.
detail:
type: string
description: A detailed error description.
status:
type: string
description: The HTTP status code.
invalid_parameters:
type: array
description: Invalid request parameters with reasons, if applicable.
items:
$ref: '#/components/schemas/InvalidParameterDetail'
instance:
type: string
description: The object causing this specific occurrence of the error, if applicable.
InstantPaymentRejectionReason:
type: string
description: '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'
example: non_sufficient_funds
enum:
- 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
InstantPayment:
type: object
required:
- id
- account_id
- account_number_id
- created_at
- updated_at
- direction
- status
- amount
- currency_code
- related_objects
- return_requests
- creditor
- creditor_agent
- debtor
- debtor_agent
- payment_identifiers
properties:
id:
type: string
description: The unique identifier of the instant payment object.
example: instant_payment_xyz123
pattern: ^instant_payment_\w+$
account_id:
$ref: '#/components/schemas/AccountID'
account_number_id:
$ref: '#/components/schemas/AccountNumberID'
direction:
$ref: '#/components/schemas/Direction'
status:
$ref: '#/components/schemas/InstantPaymentStatus'
counterparty_status:
$ref: '#/components/schemas/InstantPaymentCounterpartyStatus'
amount:
$ref: '#/components/schemas/InstantPaymentAmount'
currency_code:
$ref: '#/components/schemas/CurrencyCode'
description:
type: string
description: Free-form information on the reason for the payment.
example: Payment for invoice 12345
debtor:
$ref: '#/components/schemas/InstantPaymentParty'
description: The details of the debtor (payer) sending the funds.
debtor_agent:
$ref: '#/components/schemas/InstantPaymentAgent'
description: The details of the financial institution where the debtor (payer) holds their account.
creditor_agent:
$ref: '#/components/schemas/InstantPaymentAgent'
description: The details of the financial institution where the creditor (payee) holds their account.
creditor:
$ref: '#/components/schemas/InstantPaymentParty'
description: The details of the creditor (payee) receiving the funds.
payment_identifiers:
$ref: '#/components/schemas/InstantPaymentIdentifiers'
return:
$ref: '#/components/schemas/InstantPaymentReturnDetails'
rejection:
$ref: '#/components/schemas/InstantPaymentRejection'
related_objects:
$ref: '#/components/schemas/InstantPaymentRelatedObjects'
return_requests:
type: array
description: The return requests that reference this instant payment.
items:
$ref: '#/components/schemas/InstantPaymentReturnRequest'
created_at:
type: string
format: date-time
description: The ISO 8601 format timestamp that represents when the instant payment object was created.
example: '2022-06-27T11:22:33Z'
updated_at:
type: string
format: date-time
description: The ISO 8601 format timestamp that represents when the instant payment object was last updated.
example: '2022-06-27T11:22:40Z'
InstantPaymentParty:
type: object
description: Details of a party in an instant payment.
required:
- name
- account_number
properties:
name:
type: string
description: The party's name.
minLength: 3
maxLength: 35
example: Alex Smith
account_number:
type: string
description: The party's account number.
minLength: 1
maxLength: 17
example: '1234567890'
IncomingInstantPaymentReturnRequestRejectionReason:
type: string
description: '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'
example: customer_no_response
enum:
- account_closed
- non_sufficient_funds
- customer_requested
- legal_decision
- customer_no_response
- returned_previously
- narrative
- per_agent_request
- other
InstantPaymentRelatedObjects:
type: object
description: This instant payment's related instant payments or other objects.
properties:
original_payment_id:
type: string
description: If this instant payment is a return, the ID of the original payment this return is in reference to.
pattern: ^instant_payment_\w+$
example: instant_payment_xyz123
return_payment_ids:
type: array
description: If this instant payment was subsequently returned, the IDs of the payment returns.
items:
type: string
pattern: ^instant_payment_\w+$
example: instant_payment_xyz456
InstantPaymentRejection:
type: object
description: If this instant payment was rejected, this object contains details on the rejection.
required:
- rejected_by
- reason
properties:
rejected_by:
type: string
description: The party that rejected the instant payment.
enum:
- lead
- network
- counterparty
example: lead
reason:
$ref: '#/components/schemas/InstantPaymentRejectionReason'
details:
type: string
description: Details of the reason for the rejection including the 4-character ISO code when possible.
OutgoingInstantPaymentReturnReason:
type: string
description: '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_
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lead-bank/refs/heads/main/openapi/lead-bank-instant-payments-api-openapi.yml