Bank Account | Xplor Pay Documentation

Retrieves a list of Bank Accounts

get

This endpoint retrieves bank account details associated with a given merchantNumber. It will fetch all types of bank accounts present for the particular merchant.

Path parameters

merchantNumberstringRequired

MerchantNumber used to get bank accounts.

Query parameters

encryptedAccountNumberbooleanOptional

If true, the bank account numbers in the response are encrypted.

Default: false

lastFourAccountNumberbooleanOptional

If true, only the last four digits of the account number are returned.

Default: false

effectiveAccountbooleanOptional

If true, only active/effective accounts are returned.

Default: true

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Responses

200

Returns a list of bank accounts successfully.

application/json

400

Bad Request: Returns when merchantNumber null or empty.

application/json

401

Unauthorized: User does not have the required role or access.

application/json

403

Forbidden: The user does not have the necessary permissions to access this resource.

application/json

404

Not Found: Bank accounts not found.

application/json

500

Internal Server Error: This could be due to system errors. Please contact support for assistance.

application/json

get

GET /api/demographics/v1/BankAccounts/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*

{
  "content": [
    {
      "bankAccountID": 43543634,
      "bankName": "Bank of America",
      "nameOnAccount": "John A. Doe",
      "accountHolderFirstName": "John",
      "accountHolderLastName": "Doe",
      "bankAccountTypeID": 1,
      "bankAccountNameTypeID": 123,
      "aba": "091000019",
      "accountNumber": "123456789",
      "lastFourAccountNumber": "6789",
      "encryptedAccountNumber": "32652752350******",
      "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
      "hasFees": true,
      "hasFunds": true,
      "hasChargebacks": false,
      "isNameSameAsLegalOrDBAName": true,
      "currency": "USD",
      "purpose": "Settlement",
      "lastUpdatedUtc": "2025-01-27T10:30:00Z"
    }
  ]
}

Creates a Bank Account

post

This endpoint creates a bank account for a specified merchant with detailed validations and feature-specific behavior. It validates the MerchantNumber and BankAccount details, performs cross-validation, and checks for merchant lock status.

Path parameters

merchantNumberstringRequired

MerchantNumber used to create a bank account for it.

Query parameters

encryptedAccountNumberbooleanOptional

Select true, if account number should be encrypted.

Default: false

lastFourAccountNumberbooleanOptional

Should return the last 4 digits of the account number or not.

Default: false

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Body

bankAccountIDinteger · int32 | nullableOptional

Unique identifier for the bank account.

Example: 43543634

bankNamestringRequired

Name of the bank associated with the account.

Example: Bank of America

nameOnAccountstring | nullableOptional

The name on the bank account.

Example: John A. Doe

accountHolderFirstNamestring | nullableOptional

The first name of the account holder.

Example: John

accountHolderLastNamestring | nullableOptional

The last name of the account holder.

Example: Doe

bankAccountTypeIDinteger · int32 · min: 1 · max: 3Required

Type of bank account (1- checking, 2- savings, etc.).

Example: 1

bankAccountNameTypeIDinteger · int32 · min: 1 · max: 2147483647Required

Name type ID for the bank account.

Example: 123

abastringRequired

The routing number associated with the bank account. In different regions, this may represent BIC (EU) or Sort Code (UK).
Mandatory for US and UK; optional for EU.

Example: 091000019

accountNumberstringRequired

The account number associated with the bank account.

Example: 123456789

lastFourAccountNumberstring | nullableOptional

The last four digits of the bank account number.

Example: 6789

encryptedAccountNumberstring · byte | nullableOptional

Encrypted version of the bank account number.

Example: 32652752350******

voidedCheckDocumentIDstring · uuidOptional

Document ID for the voided check linked to the bank account.

Example: 123e4567-e89b-12d3-a456-426614174000

hasFeesbooleanRequired

Indicates if the account has fees associated with it.

Example: true

hasFundsbooleanRequired

Indicates if the account has available funds.

Example: true

hasChargebacksbooleanRequired

Indicates if the account has a history of chargebacks.

Example: false

isNameSameAsLegalOrDBANameboolean | nullableOptional

Indicates if the account name is the same as the legal or DBA name.

Example: true

currencystring | nullableOptional

The account currency in ISO 4217 code

Example: USD

purposestring · enumOptionalPossible values:

lastUpdatedUtcstring · date-time | nullableOptional

UTC date and time when the account was last updated.

Example: 2025-01-27T10:30:00Z

Responses

201

Created a new bank account successfully.

application/json

400

Bad Request: Returns when merchantNumber null or empty.

application/json

401

Unauthorized: User does not have the required role or access.

application/json

403

Forbidden: The user does not have the necessary permissions to access this resource.

application/json

404

Not Found: Bank accounts not found.

application/json

500

Internal Server Error: This could be due to system errors. Please contact support for assistance.

application/json

post

POST /api/demographics/v1/BankAccounts/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 550

{
  "bankAccountID": 43543634,
  "bankName": "Bank of America",
  "nameOnAccount": "John A. Doe",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 1,
  "bankAccountNameTypeID": 123,
  "aba": "091000019",
  "accountNumber": "123456789",
  "lastFourAccountNumber": "6789",
  "encryptedAccountNumber": "32652752350******",
  "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": false,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2025-01-27T10:30:00Z"
}

{
  "bankAccountID": 43543634,
  "bankName": "Bank of America",
  "nameOnAccount": "John A. Doe",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 1,
  "bankAccountNameTypeID": 123,
  "aba": "091000019",
  "accountNumber": "123456789",
  "lastFourAccountNumber": "6789",
  "encryptedAccountNumber": "32652752350******",
  "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": false,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2025-01-27T10:30:00Z"
}

Updates Bank Accounts

put

This endpoint updates the bank accounts of the specified merchant identified by the provided merchant number. It provides options to select whether the account number should be encrypted or it should return only last four digits of accountNumber. The bank account update occurs after extensive validations through a secure channel.

Path parameters

merchantNumberstringRequired

MerchantNumber used to update the bank details.

Query parameters

encryptedAccountNumberbooleanOptional

Indicates account number should be masked or not.

Default: false

lastFourAccountNumberbooleanOptional

Indicates only last four digit account number should be returned or not.

Default: false

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Body

Responses

200

Successfully updated a bank account.

application/json

400

Bad Request: Error occurred during save: no merchant number provided or Error occurred during save: no bank account provided or if data is invalid.

application/json

401

Unauthorized: User does not have the required role or access.

application/json

403

Forbidden: The user does not have the necessary permissions to access this resource.

application/json

404

Not Found: Bank accounts not found.

application/json

500

Internal Server Error: This could be due to system errors. Please contact support for assistance.

application/json

put

PUT /api/demographics/v1/BankAccounts/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 564

{
  "content": [
    {
      "bankAccountID": 43543634,
      "bankName": "Bank of America",
      "nameOnAccount": "John A. Doe",
      "accountHolderFirstName": "John",
      "accountHolderLastName": "Doe",
      "bankAccountTypeID": 1,
      "bankAccountNameTypeID": 123,
      "aba": "091000019",
      "accountNumber": "123456789",
      "lastFourAccountNumber": "6789",
      "encryptedAccountNumber": "32652752350******",
      "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
      "hasFees": true,
      "hasFunds": true,
      "hasChargebacks": false,
      "isNameSameAsLegalOrDBAName": true,
      "currency": "USD",
      "purpose": "Settlement",
      "lastUpdatedUtc": "2025-01-27T10:30:00Z"
    }
  ]
}

{
  "content": [
    {
      "bankAccountID": 43543634,
      "bankName": "Bank of America",
      "nameOnAccount": "John A. Doe",
      "accountHolderFirstName": "John",
      "accountHolderLastName": "Doe",
      "bankAccountTypeID": 1,
      "bankAccountNameTypeID": 123,
      "aba": "091000019",
      "accountNumber": "123456789",
      "lastFourAccountNumber": "6789",
      "encryptedAccountNumber": "32652752350******",
      "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
      "hasFees": true,
      "hasFunds": true,
      "hasChargebacks": false,
      "isNameSameAsLegalOrDBAName": true,
      "currency": "USD",
      "purpose": "Settlement",
      "lastUpdatedUtc": "2025-01-27T10:30:00Z"
    }
  ]
}

Deletes a Bank Account

delete

This endpoint deletes a bank account from the specified merchant account using the provided bankAccountId. The merchant account must not be locked; otherwise, the request will be denied. Proper authorization based on the MID policy is required for this request.

Path parameters

merchantNumberstringRequired

MerchantNumber used to delete bank account for a merchant.

bankAccountIdinteger · int32Required

BankAccountId used to delete a particular bank account.

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Responses

200

Successfully deleted a bank account.

400

Bad Request: If merchantNumber is null or empty, or bankAccountId is invalid.

application/json

401

Unauthorized: User does not have the required role or access.

application/json

403

Forbidden: The user does not have the necessary permissions to access this resource.

application/json

404

Not Found: If resource / bank account not found.

application/json

500

Internal Server Error: This could be due to system errors. Please contact support for assistance.

application/json

delete

DELETE /api/demographics/v1/BankAccounts/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*

No content

Update Bank Account

put

Path parameters

merchantNumberstringRequired

Merchant number.

bankAccountIdinteger · int32Required

The id of the bank account to update.

Query parameters

encryptedAccountNumberbooleanOptionalDefault: false

lastFourAccountNumberbooleanOptionalDefault: false

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Body

bankAccountIDinteger · int32 | nullableOptional

Unique identifier for the bank account.

Example: 43543634

bankNamestringRequired

Name of the bank associated with the account.

Example: Bank of America

nameOnAccountstring | nullableOptional

The name on the bank account.

Example: John A. Doe

accountHolderFirstNamestring | nullableOptional

The first name of the account holder.

Example: John

accountHolderLastNamestring | nullableOptional

The last name of the account holder.

Example: Doe

bankAccountTypeIDinteger · int32 · min: 1 · max: 3Required

Type of bank account (1- checking, 2- savings, etc.).

Example: 1

bankAccountNameTypeIDinteger · int32 · min: 1 · max: 2147483647Required

Name type ID for the bank account.

Example: 123

abastringRequired

The routing number associated with the bank account. In different regions, this may represent BIC (EU) or Sort Code (UK).
Mandatory for US and UK; optional for EU.

Example: 091000019

accountNumberstringRequired

The account number associated with the bank account.

Example: 123456789

lastFourAccountNumberstring | nullableOptional

The last four digits of the bank account number.

Example: 6789

encryptedAccountNumberstring · byte | nullableOptional

Encrypted version of the bank account number.

Example: 32652752350******

voidedCheckDocumentIDstring · uuidOptional

Document ID for the voided check linked to the bank account.

Example: 123e4567-e89b-12d3-a456-426614174000

hasFeesbooleanRequired

Indicates if the account has fees associated with it.

Example: true

hasFundsbooleanRequired

Indicates if the account has available funds.

Example: true

hasChargebacksbooleanRequired

Indicates if the account has a history of chargebacks.

Example: false

isNameSameAsLegalOrDBANameboolean | nullableOptional

Indicates if the account name is the same as the legal or DBA name.

Example: true

currencystring | nullableOptional

The account currency in ISO 4217 code

Example: USD

purposestring · enumOptionalPossible values:

lastUpdatedUtcstring · date-time | nullableOptional

UTC date and time when the account was last updated.

Example: 2025-01-27T10:30:00Z

Responses

200

Successfully updated a bank account.

application/json

400

Error occurred during save: no merchant number provided or Error occurred during save: no bank account provided or if data is invalid.

application/json

404

If bank account not found.

application/json

500

Error occurred during update.

application/json

put

PUT /api/demographics/v1/BankAccounts/{merchantNumber}/{bankAccountId} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 550

{
  "bankAccountID": 43543634,
  "bankName": "Bank of America",
  "nameOnAccount": "John A. Doe",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 1,
  "bankAccountNameTypeID": 123,
  "aba": "091000019",
  "accountNumber": "123456789",
  "lastFourAccountNumber": "6789",
  "encryptedAccountNumber": "32652752350******",
  "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": false,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2025-01-27T10:30:00Z"
}

{
  "bankAccountID": 43543634,
  "bankName": "Bank of America",
  "nameOnAccount": "John A. Doe",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 1,
  "bankAccountNameTypeID": 123,
  "aba": "091000019",
  "accountNumber": "123456789",
  "lastFourAccountNumber": "6789",
  "encryptedAccountNumber": "32652752350******",
  "voidedCheckDocumentID": "123e4567-e89b-12d3-a456-426614174000",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": false,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2025-01-27T10:30:00Z"
}

Deletes a Bank Account

delete

This endpoint deletes a bank account from the specified merchant account using the provided bankAccountId. The merchant account must not be locked; otherwise, the request will be denied. Proper authorization based on the MID policy is required for this request.

Path parameters

merchantNumberstringRequired

MerchantNumber used to delete bank account for a merchant.

bankAccountIdinteger · int32Required

BankAccountId used to delete a particular bank account.

Header parameters

exchangeIdstringOptional

Correlation Id for the request

Responses

200

Successfully deleted a bank account.

400

Bad Request: If merchantNumber is null or empty, or bankAccountId is invalid.

application/json

401

Unauthorized: User does not have the required role or access.

application/json

403

Forbidden: The user does not have the necessary permissions to access this resource.

application/json

404

Not Found: If resource / bank account not found.

application/json

500

Internal Server Error: This could be due to system errors. Please contact support for assistance.

application/json

delete

DELETE /api/demographics/v1/BankAccounts/{merchantNumber}/{bankAccountId} HTTP/1.1
Host: localhost:5000
Accept: */*

No content