Creating an account allows a customer to hold and transact funds on the platform. Accounts can be Deposit Accounts (customer-owned) or FBO Accounts (platform-controlled).

Before You Begin

Before opening an account, make sure you have:

Created the customer using the Customer API.
Stored the customer id or externalId. You must pass one of these identifiers in the account creation request.
Collected the required customer information for KYC/CIP checks.
Collected the applicable account agreement and acceptance details, if the account is customer-owned.
Confirmed the account purpose values configured for your program.

For account status definitions and lifecycle behavior, see Account Lifecycle.

Creating an Account

Opening an Account involves sending the following details to our API:

Step 1: Make a POST request to /v1/customer/id/{id}/account or /v1/customer/externalId/{external-id}/account API endpoint with the following recommended parameters.

Parameter	Required	Description
`type`	✓	Specify the type of account to be created. Allowed value: `CHECKING` (default) `CASH_BUILDER_PLUS` (coming soon)
`isCustomerOwned`	✓	Indicates the ownership model of the account. Allowed values: `true`: for customer-owned deposit accounts `false` (default): for clearing (FBO) accounts managed by the Platform/ISV
`nickName`		Assign a nick name to the account to easily recognise it
`isPrimary`		Sets one of the customer’s accounts as the primary account. By default, the customer’s first account is set as primary. The customer can later change their primary account using this setting. Possible values: `true` or `false`.
`externalId`		Provide an external reference ID to identify the account within your system. Once assigned, the `externalId` cannot be updated and must remain unique across all accounts.
`purpose`		Defines the intended purpose of the account. Examples: `OPERATING` `PAYROLL` `SETTLEMENT` `RESERVE` `FEE` Purpose values are configured during program setup. If you pass a value that is not configured for your program, the request may be rejected with a validation error. Contact the Account Management team to confirm the purpose values enabled for your program.
`linkedDocument`	Conditional	Required when `isCustomerOwned` is set to `true` . Use this object to provide the agreement accepted by the customer.
`linkedDocument.purpose`	Conditional	Required when `linkedDocument` is provided. Specifies the purpose of the linked document. Allowed value: `AUTHORIZATION`
`linkedDocument.document` `type` `base64encodedContent`	Conditional	Required when `linkedDocument` is provided. `type`: specifies the agreement type. This should be`SPAA` for deposit account and FBO account. `base64encodedContent`: represented the encoded file of the signed document incase of `WETSIGN` or the agreement signed via `ESIGN` or `CLICKWRAP`
`acceptanceMode`	Recommended	Use `acceptanceMode` to indicate how the customer accepted the required account agreement. Possible Values: `CLICKWRAP`: Customer accepts the agreement by clicking an acceptance control in your application. \| Capture acceptance details such as IP address, accepted date, and accepting entity. `ESIGN`: Customer accepts the agreement using an electronic signature flow. \| Store and pass acceptance evidence, including device/user acceptance details when available. `WETSIGN`: Customer signs the agreement outside the digital flow and the signed document is uploaded. \| Upload the signed agreement using `linkedDocument.document.base64encodedContent`. For `CLICKWRAP` and `ESIGN`, passing `acceptanceDetails` is recommended to support faster review and approval. For `WETSIGN`, make sure the signed document is uploaded and linked to the account.
`acceptanceDetails`	Recommended	If `ESIGN` or `CLICKWRAP`, share device and user details regarding acceptance of agreement for quicker account approvals
`acceptanceDetails.ipAddress`	Recommended	IP Address of the device accepting the agreement.
`acceptanceDetails.acceptedOn`	Recommended	Date on which the agreement is accepted.
`acceptanceDetails.acceptedBy` `entity` `id` `externalId`	Recommended	`entity` by whom the agreement is accepted. Possible Values: For Individual customer: `CUSTOMER` For Business customer: `BENEFICIAL_OWNER` (to depict which beneficial owner accepted) `id`: identifier of entity `externalId` : Reference id assigned by the program manager.

Step 2: After submitting the account creation request, the system checks that all required customer information is present. This ensures that the account can be legally opened and activated for transactions. If any validation fails, the request is rejected immediately, and an error response is returned. You must correct the issue and resubmit the request. For a complete list of validation errors and how to resolve them, refer to the HTTP Response Codes.

When isCustomerOwned is set to true, certain customer-level details must be available. If any required information is missing, the account creation request will throw error.

Customer level Validation

For Individual: firstName,lastName, ssn, dob, mailingAddress with isPrimary = true, mobilePhone, email details

For Business:legalName, ein, stateOfIncorporation,dateOfIncorporation,doingBusinessAs,phone,email,businessCategory,beneficialOwner details (based on validations defined in the Customer entity)

Use the POST request to /v1/customer/id/{id} or /v1/customer/externalId/{external-id} to update customer information.

Once the request is submitted, the system verifies all account-level requirements. This includes KYC/CIP checks, linked document verification, and compliance reviews.

If all system-level validations pass, our system processes the request and returns a response indicating the outcome.

For every account, it is critical to store the unique account idwhich can be used later, for retrieving or updating the account details. You can either use system generated account id (shared in response header of your request) or your system assigned externalId passed as part of account create request.

In certain cases, account activation may require manual verification and can take additional time. While the review is in progress, the account may remain in PENDING status with status reasons as PENDING_VERIFICATION. Please note that the account is ready to transact until its status is ACTIVE.

Step 3: You can learn the outcome of the request via GET /v1/customer/id/{id}/account API endpoint. You can also subscribe to "account.create" webhook event to track account creation and status changes.

Compliance Mandates

To open a customer-owned Deposit Account, the account owner must accept the Passport Account Agreement before the account can be used for transactions.

Identity & Compliance Verification: Customers must complete required KYC (Know Your Customer) and CIP (Customer Identification Program) checks before the account can become active. These checks may include:

OFAC screening
CIP verification
Review of customer information
Review of linked agreement documents

Sandbox Testing

Use the sandbox environment to test account activation outcomes before going live. Account status updates may be asynchronous, so retrieve the account after the recommended wait time to confirm the final status.

Use the GET /v1/customer/id/{id}/account/id/{accountId} API to check the account status and statusReason.

Scenario	Customer Test Data	Account Test Data	Expected Result	Wait Time
OFAC failure	Business customer: `business.legalName = block`	Create account for the customer	`status: BLOCKED`, `statusReason: Customer OFAC rejected`	~5 minutes
Successful activation	Business customer: `business.legalName = William`	`isCustomerOwned: true`	`status: ACTIVE`, `statusReason: VERIFIED`	~30 minutes

For individual customers:

To test OFAC failure, create the customer with firstName = block and lastName = block.
To test successful activation, use any first and last name except block.

Sandbox status transitions may take several minutes. Do not assume the account is ready to transact until the retrieved account status is ACTIVE.

Direct Transfers using Routable Account Details

Once an account is successfully created and active, it can be used to receive funds directly from external bank accounts using supported payment rails such as ACH and WIRE.

Each account is assigned routable account details, which are available in the response of the GET v1/customer/id/{id}/account/id/{id} API, under the routableAccount object:

Field	Description
`accountNumber`	Account number used for ACH credits
`routingNumber`	Routing number used for ACH transfers
`wireAccountNumber`	Account number used for WIRE transfers
`wireRoutingNumber`	Routing number used for WIRE transfers
`memo`	Optional reference included in ACH transfers to help identify the transaction
`wireMemo`	Optional reference included in WIRE transfers for reconciliation

How it Works

Retrieve the account details using the GET Account API
Share the appropriate ACH or WIRE details with the sender
The sender initiates a transfer via ACH or WIRE
Funds are received as an external credit in the account once processed

These transactions originate outside the platform and are processed once received via banking rails.

Important Notes

Use ACH fields (accountNumber, routingNumber) for ACH transfers
Use WIRE fields (wireAccountNumber, wireRoutingNumber) for wire transfers
Include memo fields where possible to simplify reconciliation
Ensure the account is in an ACTIVE state before sharing details

Handling External Transactions

All incoming or outgoing transfers via ACH/WIRE are processed as External Transactions within the system.

Refer to the External Transactions page for detailed information on PayOps and Program Manager workflows for handling these transactions.