Open an Account

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).

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)
`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`		Set one of your passport accounts as a primary account. Primary accounts are used to received money through PPI (passport payment ID) within Passport ecosystem. By default, the customer’s first passport account will be set as primary. The customer can later change their primary account using this setting. Possible Values: `true` or `fasle`
`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. Example: Operating, Payroll, Settlement etc. Purpose values are configurable and can be defined during Program setup by coordinating with the Account Management team
`linkedDocument`	✓	Required when `isCustomerOwned` is set to `true` to share the agreement signed by the customer.
`linkedDocument.purpose`	✓	Specifies the purpose of the linked document. Allowed value: `AUTHORIZATION`
`linkedDocument.document` `type` `base64encodedContent`	✓	`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	The mode of acceptance of documents. Possible Values: CLICKWRAP ESIGN WETSIGN
`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: Individual customer - CUSTOMER 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.

Step 3: You can learn the outcome of the request via GET /v1/customer/id/{id}/account or wait for the Account webhook.

Compliance Mandates

To open an Deposit account, account owner must accept the Passport Account Agreement to authorize account operations. To open a Clearing (FBO) account, account owner must accept Payment Services Terms & Conditions agreement.