🚀 VaultsPay API v1 is live. See what's new →

API Reference

Create users, manage KYC, addresses, and identification documents.Read docs

Digital Wallets

Create accounts and browse transaction ledger.Read docs

Direct Transfers

Validate IBANs, create payment contacts, and initiate transfers.Read docs

List and retrieve transaction details.Read docs

Issue, manage, control, and report payment cards.Read docs

Card security settings and transaction limits.Read docs

Real-time card status event delivery.Read docs

Error codes, response shapes, and HTTP status mappings.Read docs

Global Conventions

Item	Details
Protocol	HTTPS only (TLS 1.2+). Plain HTTP is refused.
Request body format	`application/json` (UTF-8).
Response body format	`application/json` (UTF-8).
Authentication	`Authorization: Bearer <accessToken>` — obtain via Authentication.
Encryption	Hybrid AES + RSA encryption required in production. See Encryption & Security.
Required headers	`x-session-nonce`, `x-auth-signature`, `x-device-os`, `x-device-id` — see Encryption & Security.
Success response	All successful responses wrap data in `{ "data": { ... } }`.
Error response	`{ "code", "message", "type", "errors[]" }` — see Errors.
Pagination	Page-based — `?page=1&perPage=20`. Response includes `pagination` object.

Endpoint Index

Authentication — `/as/api/v1`

Method	Endpoint	Description
`POST`	`/as/api/v1/saas-login`	Obtain access token and refresh token.
`POST`	`/as/api/v1/saas-refresh-token`	Refresh an expired access token.

Users — `/as/api/v1` · `/us/api/v1`

Method	Endpoint	Description
`POST`	`/as/api/v1/users`	Create a user.
`GET`	`/us/api/v1/countries`	List all countries.
`GET`	`/us/api/v1/states/{countryId}`	List states by country.
`GET`	`/us/api/v1/cities/{stateId}`	List cities by state.

KYC — `/us/api/v1/kyc`

Method	Endpoint	Description
`POST`	`/us/api/v1/kyc/personal`	Create personal info for a user.
`PATCH`	`/us/api/v1/kyc/personal`	Update personal info (only when status is PENDING).
`POST`	`/us/api/v1/kyc/addresses`	Create a KYC address.
`PATCH`	`/us/api/v1/kyc/addresses`	Update a KYC address.
`POST`	`/us/api/v1/kyc/identification`	Upload identification documents.
`PATCH`	`/us/api/v1/kyc/identification`	Update identification documents.
`GET`	`/us/api/v1/kyc/{userId}`	Get full KYC details for a user.

Digital Wallets — `/be/api/v1/accounts`

Method	Endpoint	Description
`POST`	`/be/api/v1/accounts`	Create an account.
`GET`	`/be/api/v1/accounts`	List accounts (supports filters).
`GET`	`/be/api/v1/accounts/{id}`	Get account by ID.
`GET`	`/be/api/v1/account-ledger/{id}`	Get account ledger/transaction history.

Direct Transfers — `/be/api/v1` · `/tc/api/v1`

Method	Endpoint	Description
`POST`	`/be/api/v1/validate-iban`	Validate an IBAN and retrieve account title.
`POST`	`/be/api/v1/direct-payment-contact`	Create a payment contact from a validated IBAN.
`POST`	`/tc/api/v1/direct-transfer`	Initiate a direct transfer to a payment contact.

Transactions — `/tme/api/v1`

Method	Endpoint	Description
`GET`	`/tme/api/v1/transactions`	List transactions (supports filters).
`GET`	`/tme/api/v1/transactions/{id}`	Get transaction detail by ID.

Payment Cards — `/pcs/api/v1`

Issuance

Method	Endpoint	Description
`GET`	`/pcs/api/v1/card-tiers`	List configured card tiers/products.
`GET`	`/pcs/api/v1/embossing-names/{userId}`	Get allowed embossing name options for a user.
`POST`	`/pcs/api/v1/cards`	Create a card (virtual or physical).
`POST`	`/pcs/api/v1/process-card-request`	Move a card into `ISSUANCE_IN_PROGRESS`.
`POST`	`/pcs/api/v1/update-card-manufacturing`	Update manufacturing status.
`POST`	`/pcs/api/v1/update-delivery-status`	Update delivery status.
`POST`	`/pcs/api/v1/activate-card`	Activate a physical card using PAN and expiry.
`POST`	`/pcs/api/v1/set-pin`	Set or update card PIN (physical cards only).

Card Details

Method	Endpoint	Description
`POST`	`/pcs/api/v1/cards/details`	Get full card details by card ID or token.
`POST`	`/pcs/api/v1/get-card-pan`	Retrieve 16-digit PAN.
`POST`	`/pcs/api/v1/get-card-cvv`	Retrieve card CVV.
`POST`	`/pcs/api/v1/get-card-expiry`	Retrieve card expiry date.

Card Controls

Method	Endpoint	Description
`POST`	`/pcs/api/v1/enroll-card-three-ds`	Enroll card in 3DS.
`POST`	`/pcs/api/v1/remove-card-three-ds`	Remove card from 3DS.
`POST`	`/pcs/api/v1/update-card-status`	Set card status to `ACTIVE` or `BLOCK`.
`POST`	`/pcs/api/v1/toggle-freeze-card`	Toggle card between `FREEZE` and `ACTIVE`.
`POST`	`/pcs/api/v1/update-card-account`	Update the linked funding account of a card.

Reported Cards

Method	Endpoint	Description
`POST`	`/pcs/api/v1/report-card-issue`	Report a card as lost, stolen, damaged, etc.
`POST`	`/pcs/api/v1/review-report-card-issue`	Review a reported card issue.
`POST`	`/pcs/api/v1/replace-card`	Replace a reported card (triggers new issuance).
`POST`	`/pcs/api/v1/renew-card`	Renew a reported card (triggers new issuance).
`POST`	`/pcs/api/v1/decline-card`	Decline a reported card issue.
`GET`	`/pcs/api/v1/card-reported-issues`	List reported card issues.

Conversion

Method	Endpoint	Description
`POST`	`/pcs/api/v1/virtual-to-physical`	Request conversion of a virtual card to physical.
`POST`	`/pcs/api/v1/virtual-to-physical-process`	Approve or reject a physical conversion request.

Rules Engine — `/re/api/v1`

Method	Endpoint	Description
`GET`	`/re/api/v1/card-security`	Get card security settings.
`PUT`	`/re/api/v1/card-security`	Update a card security setting.
`PATCH`	`/re/api/v1/card-security/reset`	Reset all card security settings to default.
`GET`	`/re/api/v1/transaction-limits`	Get transaction limits.
`PUT`	`/re/api/v1/transaction-limits`	Update a transaction limit.

System

Method	Endpoint	Description
`GET`	`/v1/ping`	Health check — returns `"Service is up and running!"`.

Errors Changelog