ACH Payments
Originate ACH transactions to verified external bank accounts
The Payments API enables you to move funds between a Lithic-assigned general purpose account (see Financial Accounts) and an external bank account (see External Bank Accounts). Funds are currently moved via ACH but additional payment rails will be added in the future.
This page gives an overview of the API objects and endpoints you will work with for ACH payments. See the ACH Payments Lifecycle for more detailed information about possible lifecycle permutations.
Payments Schema
{
"category": "String",
"created": "String",
"currency": "String",
"descriptor": "String",
"events": [ Event ],
"pending_amount": "Integer",
"result": "String",
"settled_amount": "Integer",
"status": "String",
"token": "String",
"updated": "String",
"method_attributes": { Method_Attribute
},
"external_bank_account_token": "String",
"direction": "String",
"source": "String",
"method": "String",
"user_defined_id": "String",
}
category | Type of payment. Currently, only ACH is supported |
created | Date and time of when this payment was first created |
currency | Currency of payment transaction in 3-digit alphabetic ISO 4217 code |
descriptor | Customer-provided description for the payment. May appear in bank statements |
events | A list of events that have modified this payment |
pending_amount | Pending amount of the transaction in the currency’s smallest unit (e.g., cents for USD). Positive amount indicates the payment, once completed, will increase your balance while a negative amount indicates it will decrease your balance. The value of this field will go to zero over time once the payment is settled. |
settled_amount | Completed amount of the payment in the currency’s smallest unit (e.g., cents for USD). Positive amount indicates the payment increases your balance while a negative amount indicates it decreases your balance. The value of this field will grow over time once the payment is settled |
result | APPROVED , DECLINED |
status | DECLINED , EXPIRED , PENDING , SETTLED , VOIDED ,RETURNED |
token | Globally unique identifier for this payment |
updated | Date and time of when this payment was last updated |
method_attributes | Additional fields unique to the payment type |
external_bank_account_token | Globally unique identifier of a record of an external bank account. This is the bank account that Lithic will either send funds to or collect funds from |
direction | DEBIT indicates funds are moving from an external bank account to a Lithic-assigned virtual bank account number. CREDIT indicates funds are moving from a Lithic-assigned virtual bank account number to an external bank account |
source | LITHIC which indicates a manual payment initiated by Lithic, CUSTOMER which indicates a payment initiated by customers |
method | ACH_NEXT_DAY , ACH_SAME_DAY |
user_defined_id | Additional metadata provided by customers that may help with reconciliation against other systems |
Event Schema
{
"amount": Integer,
"type": String,
"result": String,
"detailed_results": List,
"created": String,
"token": String
}
amount | Amount of the transaction event in the currency’s smallest unit (e.g., cents for USD) |
type | ACH_ORIGINATION_INITIATED , ACH_ORIGINATION_REVIEWED , ACH_ORIGINATION_PROCESSED , ACH_ORIGINATION_SETTLED ,ACH_ORIGINATION_RELEASED , ACH_RETURN_INITIATED ACH_RETURN_PROCESSED , ACH_RECEIPT_PROCESSED , ACH_RECEIPT_SETTLED . See ACH Payments Lifecycle for more details on each. |
result | APPROVED , DECLINED |
detailed_results | APPROVED , FUNDS_INSUFFICIENT , ACCOUNT_INVALID , PROGRAM_TRANSACTION_LIMIT_EXCEEDED , PROGRAM_DAILY_LIMIT_EXCEEDED , PROGRAM_MONTHLY_LIMIT_EXCEEDED . See ACH Payments Lifecycle for more details on each. |
created | Date and time for when the transaction event occurred |
token | Globally unique identifier for the transaction event |
Method Attribute Schema
This object contains attributes that are specific to the payment method. Lithic currently only displays attributes for ACH
{
"sec_code": "String",
"retries": Integer,
"return_reason_code": "String",
"company_id": "String",
"receipt_routing_number": "String",
}
sec_code | Code used by ACH network to indicate nature of ACH transaction. Lithic currently supports ACH originations for the following SEC codes: - CCD : Corporate Credit or Debit - PPD : Pre-arranged Payment or Deposit - WEB: Internet-Initiated/Mobile Entries See full list of SEC Codes NACHA supports here. |
retries | Number of retries for an ACH origination that was returned due to insufficient funds |
return_reason_code | Reason for ACH return provided by the recipient bank |
company_id | For ACH receipts, a 10-digit unique identifier of the entity that sent the ACH transaction |
receipt_routing_number | For ACH receipts, the routing number that the receipt was sent from |
Create payment
POST https://api.lithic.com/v1/payments
Use this endpoint to create a payment between a Lithic-assigned virtual bank account and an External Bank Account verified with Lithic.
Sample Request
curl https://api.lithic.com/v1/payments \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"type": "COLLECTION",
"method_attributes": {
"sec_code": "CCD"
},
"method": "ACH_NEXT_DAY",
"financial_account_token": "f817bc6a-e9d5-49bf-8caa-b4bf442c9408",
"external_bank_account_token": "6548116f-6a34-41d9-a9d4-0b93f000e32e",
"amount": 500,
"memo": "Test"
}
'
Sample Response
{
"category": "ACH",
"created": "2023-06-03T23:30:23.087Z",
"currency": "USD",
"descriptor": "Test",
"events": [
{
"amount": 500,
"created": "2023-06-03T23:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PENDING"
}
],
"pending_amount": 500,
"result": "APPROVED",
"settled_amount": 0,
"status": "PENDING",
"token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"updated": "2023-06-03T23:30:23.087Z",
"method_attributes": {
"sec_code": "CCD"
},
"external_bank_account_token": "6548116f-6a34-41d9-a9d4-0b93f000e32e",
"direction": "DEBIT",
"source": "CUSTOMER",
"method": "ACH_NEXT_DAY",
"user_defined_id": null,
"balance": {
"available_amount": 0,
"created": "2023-06-03T23:30:23.087Z",
"currency": "string",
"last_transaction_event_token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"last_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pending_amount": 500,
"token": "f817bc6a-e9d5-49bf-8caa-b4bf442c9408",
"total_amount": 0,
"type": "ISSUING",
"updated": "2023-06-03T23:30:23.087Z"
}
}
financial_account_token (required) | Globally unique identifier for the financial account that is sending or receiving funds String. Permitted values: 36-digit version 4 UUID (including hyphens). |
external_bank_account_token (required) | Globally unique identifier for the external bank account record that is the counterparty to this payment transaction String. Permitted values: 36-digit version 4 UUID (including hyphens). |
type (required) | Indicates the direction of the payment transaction where PAYMENT indicates financialaccount => external_bank_account and COLLECTION indicates financial_account <= external_bank_account _String. Permitted values: PAYMENT ,COLLECTION |
amount (required) | Amount to be transferred in the currency’s smallest unit (e.g., cents for USD). This should always be a positive value. Integer. Permitted values: 0 or greater. |
memo (optional) | Optional descriptor for the payment. String. Permitted values: 1-512 characters |
method (required) | Indicates the payment rails used for this payment transaction String. Permitted values: ACH_NEXT_DAY ,ACH_SAME_DAY |
method_attributes (required) | Additional fields required per payment type. For ACH , customers need to indicate the sec_code of the ACH payment; Lithic currently supports CCD , PPD , WEB . String. Permitted values: varies by method |
token (optional) | Customer-provided transaction token that will serve as an idempotency token. String. Permitted values: 36-digit UUID (including hyphens). |
user_defined_id (optional) | Additional metadata provided by customers that may help with reconciliation against other systems String. Permitted values: 1-512 characters |
Retry ACH Return
For ACH originations that were returned with reason code R01 or R09 (insufficient funds), users can resubmit the origination after verifying that the recipient has sufficient balance to complete the ACH transaction. Users can retry up to 2 times per origination.
POST https://api.lithic.com/v1/payments/{payment_token}/retry
Sample Request
curl https://api.lithic.com/v1/payments/3fa85f64-5717-4562-b3fc-2c963f66afa6/retry
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
List payments
GET https://api.lithic.com/v1/payments
Sample Request
curl https://api.lithic.com/v1/payments\
-H 'AUTHORIZATION: YOUR_API_KEY'
Sample Response
{
"data":[
{
"category": "ACH",
"created": "2023-06-03T23:30:23.087Z",
"currency": "USD",
"descriptor": "Test",
"events": [
{
"amount": 500,
"created": "2023-06-03T23:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PENDING"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PROCESSED"
}
],
"pending_amount": 500,
"result": "APPROVED",
"settled_amount": 0,
"status": "PENDING",
"token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"updated": "2023-06-03T23:30:23.087Z",
"method_attributes": {
"sec_code": "CCD"
},
"external_bank_account_token": "6548116f-6a34-41d9-a9d4-0b93f000e32e",
"direction": "DEBIT",
"source": "CUSTOMER",
"method": "ACH_NEXT_DAY",
"user_defined_id": null
}
],
"has_more": true
}
financial_bank_account_token (optional) | Globally unique identifier for the financial account that is sending or receiving funds String. Permitted values: 36-digit version 4 UUID (including hyphens). |
status (optional) | Query by payment status String. Permitted values: APPROVED , DECLINED |
result (optional) | Query by payment result String. Permitted values: DECLINED , EXPIRED , PENDING , SETTLED , VOIDED |
page_size (optional, query parameter) | For cursor-based pagination - specifies the number of entries to be included on each page in the response. Default value is 100. Integer. Permitted values: 1-100. |
starting_after (optional, query parameter) | For cursor-based pagination - specifies the next object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Financial Transaction objects where the first entry is UUID abcd and last entry is UUID wxyz . A request of starting_after = abcd and page_size = 100 will return 99 results (abcd is excluded from the response)String. Permitted values: 36-digit version 4 UUID (including hyphens). |
ending_before (optional, query parameter) | For cursor-based pagination - specifies the last object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Financial Transaction objects where the first entry is UUID abcd and last entry is UUID wxyz . A request of ending_before = wxyz and page_size = 100 will return the full list of 100String. Permitted values: 36-digit version 4 UUID (including hyphens) |
Get payment by token
GET https://api.lithic.com/v1/payments/{payment_token}
Sample Request
curl https://api.lithic.com/v1/payments/3fa85f64-5717-4562-b3fc-2c963f66afa6\
-H 'AUTHORIZATION: YOUR_API_KEY'
Sample Response
{
"category": "ACH",
"created": "2023-06-03T23:30:23.087Z",
"currency": "USD",
"descriptor": "Test",
"events": [
{
"amount": 500,
"created": "2023-06-03T23:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PENDING"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PROCESSED"
}
],
"pending_amount": 500,
"result": "APPROVED",
"settled_amount": 0,
"status": "PENDING",
"token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"updated": "2023-06-03T23:30:23.087Z",
"method_attributes": {
"sec_code": "CCD"
},
"external_bank_account_token": "6548116f-6a34-41d9-a9d4-0b93f000e32e",
"direction": "DEBIT",
"source": "CUSTOMER",
"method": "ACH_NEXT_DAY",
"user_defined_id": null
}
payment_token (required, path parameter) | Globally unique identifier for the payment String. Permitted values: 36-digit version 4 UUID (including hyphens). |
Simulate payment release
POST https://api.lithic.com/v1/simulate/payments/release
Use this endpoint to release a simulated payment in Sandbox
Sample Request
curl https://sandbox.lithic.com/v1/simulate/payments/release\
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"payment_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'
Sample Response
{
"debugging_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"result": "APPROVED",
"transaction_event_token": "cd20af3e-4979-402e-8fc6-3195f32802e6"
}
At this point, if you queried the GET Payment endpoint for this payment, you would see the below response where the payment status
has been updated to SETTLED
and an additional ACH_ORIGINATION_RELEASED
event has been posted:
{
"category": "ACH",
"created": "2023-06-03T23:30:23.087Z",
"currency": "USD",
"descriptor": "Test",
"events": [
{
"amount": 500,
"created": "2023-06-03T23:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_INITIATED"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_REVIEWED"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_PROCESSED"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_SETTLED"
},
{
"amount": 500,
"created": "2023-06-04T00:30:23.087Z",
"result": "APPROVED",
"detailed_results": ["APPROVED"],
"token": "595ded29-bd6a-4ed6-bf67-9aa693a70522",
"type": "ACH_ORIGINATION_RELEASED"
}
],
"pending_amount": 0,
"result": "APPROVED",
"settled_amount": 500,
"status": "SETTLED",
"token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"updated": "2023-06-03T23:30:23.087Z",
"method_attributes": {
"sec_code": "CCD"
},
"external_bank_account_token": "6548116f-6a34-41d9-a9d4-0b93f000e32e",
"direction": "DEBIT",
"source": "CUSTOMER",
"method": "ACH_NEXT_DAY",
"user_defined_id": null
}
Updated about 2 months ago