Quick Start - ACH Funding in Sandbox
How to fund your Lithic instance in sandbox
For customers using our Accounts product suite, you will need to "fund" your Lithic instance in Sandbox before you can move funds through the Book Transfer endpoints or send ACH credit originations through the Payments API.
You will learn how to simulate:
- uploading and verifying your external bank account through micro deposits
- initiating an ACH debit origination from your program's issuing financial account
- tracking your balances
Step 1 - Add an external bank account
Send a POST
request to Create external bank account with a verification method of MICRO_DEPOSIT
:
curl https://sandbox.lithic.com/v1/external_bank_accounts \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"verification_method": "MICRO_DEPOSIT",
"owner_type": "BUSINESS",
"owner": "John Doe LLC",
"type": "CHECKING",
"routing_number": "021000021",
"account_number": "123456789",
"name": "Funding Account",
"country": "USA",
"currency": "USD"
}
'
Below is a sample response:
{
"token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
"type": "CHECKING",
"verification_method": "MICRO_DEPOSIT",
"owner_type": "BUSINESS",
"owner": "John Doe LLC",
"state": "ENABLED",
"verification_state": "PENDING",
"routing_number": "021000021",
"last_four": "6789",
"name": "John Doe Payables",
"currency": "USD",
"country": "USA",
"account_token": null,
"created": "2023-06-23T20:01:53Z",
"company_id": null,
}
Step 2 - Verify the external bank account
In Sandbox, the verification amounts will always be 19 and 89. Please send those amounts to Lithic to verify the bank account by sending a POST
request to Verify External Bank Account
curl https://sandbox.lithic.com/v1/external_bank_accounts/a036e6b5-fd0f-49b2-b0c0-45d84214b189/micro_deposits \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"micro_deposits": ["19", "89"]
}
'
Below is a sample response. Note that the verification_state
of the external bank account has switched from PENDING
to ENABLED
:
{
"token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
"type": "CHECKING",
"verification_method": "MICRO_DEPOSIT",
"owner_type": "BUSINESS",
"owner": "John Doe LLC",
"state": "ENABLED",
"verification_state": "ENABLED",
"routing_number": "021000021",
"last_four": "6789",
"name": "John Doe Payables",
"currency": "USD",
"country": "USA",
"account_token": null,
"created": "2023-06-23T20:01:53Z",
"company_id": null
}
Step 3 - Simulate ACH
See Step 3 of the Quick Start - ACH Originations Guide for next steps.
Originations
To simulate an origination, use the POST /v1/payments
endpoint to initiate an ACH origination. See Step 3 of the Quick Start - ACH Originations Guide for how to do this.
You will then use the simulate action endpoint detailed below to simulate the various ACH lifecycles.
Receipts
You can simulate an ACH receipt via the POST /v1/simulate/payments/receipt
endpoint. While both debit and credit receipts can be simulated, please note that in your production environment Lithic will bounce all receipt debits automatically.
Simulate Credit Receipt
curl https://sandbox.lithic.com/v1/simulate/payments/receipt \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"financial_account_token": "a722fcdc-f65b-5356-a684-6b0b85b562e5",
"token": "825490dd-d17d-49da-85a1-164425033e46",
"receipt_type": "RECEIPT_CREDIT",
"amount": 123,
"memo": "Testing receipts with Lithic"
}
'
Simulate Debit Receipt
curl https://sandbox.lithic.com/v1/simulate/payments/receipt \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"financial_account_token": "a722fcdc-f65b-5356-a684-6b0b85b562e5",
"token": "825490dd-d17d-49da-85a1-164425033e46",
"receipt_type": "RECEIPT_DEBIT",
"amount": 123,
"memo": "Testing receipts with Lithic"
}
'
Advancing through the ACH Lifecycle
You can simulate any of the supported ACH lifecycles using the POST /v1/simulate/payments/{token}/action
endpoint. Please refer to the ACH Payment Lifecycle guide for supported lifecycles.
The token provided in the path should be the payment token of the payment generated from the simulate receipt or initiate origination call.
Happy-path origination debit
ACH Payment is reviewed and approved
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_REVIEWED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is processed
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_PROCESSED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment settles
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_SETTLED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is released
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_RELEASED",
"decline_reason": null,
"return_reason_code": null
}
'
Happy-path origination credit
ACH Payment is reviewed and approved
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_REVIEWED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is processed
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_PROCESSED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment settles
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_SETTLED",
"decline_reason": null,
"return_reason_code": null
}
'
Returned Origination
ACH Payment is reviewed and approved
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_REVIEWED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is processed
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_PROCESSED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is returned
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_RETURNED",
"decline_reason": null,
"return_reason_code": "R29"
}
'
Settled Receipt
ACH Payment settles
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_RECEIPT_SETTLED",
"decline_reason": null,
"return_reason_code": null
}
'
Returned Receipt
Return for ACH Receipt is initiated
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_RETURN_INITIATED",
"decline_reason": null,
"return_reason_code": null
}
'
Return for ACH Receipt is processed
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_RETURN_PROCESSED",
"decline_reason": null,
"return_reason_code": null
}
'
ACH Payment is reviewed and declined
curl https://sandbox.lithic.com/v1/simulate/payments/{token}/action \
-H 'AUTHORIZATION: YOUR_API_KEY'
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"event_type": "ACH_ORIGINATION_REVIEWED",
"decline_reason": "PROGRAM_DAILY_LIMITS_EXCEEDED",
"return_reason_code": null
}
'
Updated about 2 months ago