Embedded Payments

Manage account states

Account states define the current status and permitted actions for each account type. The following are the eligible account states and its definitions.

PENDING_OPEN: Only non-financial requests are allowed.
OPEN: Both financial and non-financial requests are allowed. The account is open and operational.
PENDING_CLOSE: Both request types allowed. The balance should be reduced to zero before closing. The account closure has been initiated. Manual steps are pending for limited accounts.
CLOSED: The account is fully closed. No requests allowed. The balance must be zero and state cannot be changed.

Transaction accounts (TRANSACTION_ACCOUNTS)
Transaction accounts offer flexible management and can progress through several states: PENDING_OPEN, OPEN, PENDING_CLOSE and CLOSED. These accounts are eligible for all state transitions, providing platforms with comprehensive control over the account lifecycle. Transaction accounts may be initiated in either the open or pending open state. Clients can manage the entire lifecycle of Transaction accounts directly through the API.

Note

Once an account is closed, it cannot be modified. Once an account is opened, it cannot revert to the PENDING_OPEN state.

Limited accounts (LIMITED_DDA, LIMITED_DDA_PAYMENTS)
Limited access accounts begin in the OPEN state and can transition to PENDING_CLOSE or CLOSED, only when the account balance is zero. Clients using limited accounts can request account closure via the API. Upon request, the account moves to PENDING_CLOSED state and an operations user completes the closure process once all requirements are met (including zero balance, closure reason provided and no pending transactions). Once closed, the account cannot be modified. Refer to Close your client’s account for detailed account closure process for platform client’s limited accounts.

Limited Accounts
Current State	Possible new states	Eligible account type
PENDING_OPEN	OPEN	TRANSACTION_ACCOUNT
	PENDING_CLOSE
	CLOSED
OPEN (default account creation state)	PENDING_CLOSE	TRANSACTION_ACCOUNT LIMITED_DDA LIMITED_DDA_PAYMENTS
OPEN (default account creation state)	CLOSED (if balance is zero)	TRANSACTION_ACCOUNT
PENDING_CLOSE	OPEN	TRANSACTION_ACCOUNT LIMITED_DDA ( Operations only) LIMITED_DDA_PAYMENTS (Operations only)
PENDING_CLOSE	CLOSED (if balance is zero)	LIMITED_DDA LIMITED_DDA_PAYMENTS
CLOSED	None (Account is permanently closed)	TRANSACTION_ACCOUNT LIMITED_DDA LIMITED_DDA_PAYMENTS

Note

TRANSACTION_ ACCOUNTS can be opened in a PENDING_OPEN state so platforms can pre-stage their accounts until they want to make it available for transaction use. The parent summary account for the TRANSACTION_ACCOUNT cannot be closed via the API.

Account closure impact

Once any account is closed, it cannot be reopened or transitioned to another state. Payment Routing Number (PRN) linked to the account is deactivated when the account is closed by end of day. Payments made to the PRN after account closure are redirected to the default account for a transaction account and for exception handling for limited accounts. Closure reason must be provided for the limited accounts.

Account closure reason
Account type	Account state	Closure reason
TRANSACTION_ACCOUNT	PENDING_CLOSE or CLOSED	Not allowed. Closure reason cannot be provided.
LIMITED_DDA, LIMITED_DDA_PAYMENTS	CLOSED	Must provide a valid closure reason value. See Closure reasons for more details.

Refer to close an account for your client for platform customer’s limited accounts.

PENDING_OPEN state (TRANSACTION_ACCOUNT)

Use PATCH /api/accounts/{id}

Sample request:

Json

{
  "state": "PENDING_OPEN"
}

Sample response:

Json

{
  "id": "40386addf40e4b8a825bc3847d84c260",
  "state": "PENDING_OPEN"
}

CLOSED state (TRANSACTION_ACCOUNT)

Sample request:

Json

{
  "state": "CLOSED",
  "closureReason": "ELECTIVE"
}

Sample response:

Json

{
 "id": "40386addf40e4b8a825bc3847d84c260",  
  "state": "CLOSED",
  "closureReason": "ELECTIVE"
}