Guides
StatusDashboard

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 4 months ago