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.

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

Handling External Transactions

Once funds are received as an external credit or debit, the transaction enters a review and matching workflow before being credited to a customer account.

The PayOps team reviews the incoming transaction and attempts to match it to the appropriate customer account based on the available details.

If a match is identified, the transaction is accepted and amount is credited or debited to the corresponding account.
If a match cannot be established, the transaction is escalated to the Program Manager (PM) for further review and action.

ACH Credit transactions are directly escalated to Program Managers and do not go through the PayOps matching process.

Program Manager Actions

When a transaction is escalated, the Program Manager can review the details and take one of the following actions:

Accept or Reject the Transaction: Based on the review, the Program Manager can either accept the transaction (to credit the account) or reject it.
1. ACH Credit
  1. Accept: POST /v1/externalTransaction/achCredit/id/{id}/accept (trainAutomatching can be passed)
  2. Rejec: POST /v1/externalTransaction/achCredit/id/{id}/reject
2. ACH Debit
  1. Accept: POST /v1/externalTransaction/achDebit/id/{id}/accept (trainAutomatching can be passed)
  2. Reject: POST /v1/externalTransaction/achDebit/id/{id}/reject
3. Wire
  1. Accept: POST /v1/externalTransaction/wire/id/{id}/accept
  Wire transactions can only be accepted. They cannot be rejected or reassigned.
Update Transaction Details: If additional information is required or corrections are needed, the Program Manager can update the details of a WIRE transaction, before taking action:
1. POST /v1/externalTransaction/wire/id/{id}
Updation is supported only for Wire transactions
Reassign for Further Review: If the transaction requires additional validation or should be handled again by the PayOps team, it can be reassigned:
1. POST /v1/externalTransaction/achDebit/id/{id}/reassign
Reassignment is supported only for ACH Debit transactions

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