Simulate payment lifecycle event

Payment Token Schema

Fields

payment_token

Type: uuid
Requirement: required

event_type

Type: string
Requirement: required
Enum Values:
- ACH_ORIGINATION_REVIEWED
- ACH_ORIGINATION_RELEASED
- ACH_ORIGINATION_PROCESSED
- ACH_ORIGINATION_SETTLED
- ACH_RECEIPT_SETTLED
- ACH_RECEIPT_RELEASED
- ACH_RECEIPT_RELEASED_EARLY
- ACH_RETURN_INITIATED
- ACH_RETURN_PROCESSED
- ACH_RETURN_SETTLED

return_reason_code

Type: string
Description: Return Reason Code

decline_reason

Type: string
Enum Values:
- PROGRAM_TRANSACTION_LIMIT_EXCEEDED
- PROGRAM_DAILY_LIMIT_EXCEEDED
- PROGRAM_MONTHLY_LIMIT_EXCEEDED
Allowed Values:
- PROGRAM_TRANSACTION_LIMIT_EXCEEDED
- PROGRAM_DAILY_LIMIT_EXCEEDED
- PROGRAM_MONTHLY_LIMIT_EXCEEDED

return_addenda

Type: string
Description: Return Addenda

date_of_death

Type: date
Description: Date of Death for ACH Return

Response Codes

200 Created

Response:

{
  "result": "APPROVED",
  "transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "debugging_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400 Bad Request

Description: A parameter in the query given in the request does not match the valid queries for the endpoint.

401 Unauthorized

Description
User has not been authenticated	Invalid or missing API key
API key is not active	The API key used is no longer active
Could not find API key	The API key provided is not associated with any user
Please provide API key in Authorization header	The Authorization header is not in the request
Please provide API key in the form Authorization: [api-key]	The Authorization header is not formatted properly
Insufficient privileges. Issuing API key required	Write access requires an Issuing API key. Reach out at lithic.com/contact
Insufficient privileges to create virtual cards.	Creating virtual cards requires an additional privilege

404 Not Found

Description: The specified resource was not found.

429 Too Many Requests

Description
Rate limited, too many requests per second	User has exceeded their per second rate limit
Rate limited, reached daily limit	User has exceeded their daily rate limit
Rate limited, too many keys tried	One IP has queried too many different API keys

Example Request

curl --request POST \
     --url https://sandbox.lithic.com/v1/simulate/payments/payment_token/action \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "event_type": "ACH_ORIGINATION_REVIEWED",
       "return_reason_code": "string",
       "decline_reason": "PROGRAM_TRANSACTION_LIMIT_EXCEEDED",
       "return_addenda": "string",
       "date_of_death": "2026-07-18"
     }'

Example Successful Response

{
  "result": "APPROVED",
  "transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "debugging_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}