Create wallet

POST

https://api.staging.vrtx.sa/cl/v1/wallets

Last modified:2025-12-03 07:59:44

Create a new wallet under a closed-loop business account.
This endpoint generates both the wallet record and its associated account number, automatically linked to the specified business based on the account prefix convention.

Wallets can be used for a variety of purposes and are identified by their name and label.

Wallet Account Structure

On success, the system creates an account number for the wallet:

Prefixed according to its type and purpose (9 = individual wallet).

Account numbers are unique and internally linked to the business’s operational ledger.

Wallets start with balance = 0 and status = ACTIVE.

Each wallet is automatically linked to the business through its prefix rule and businessId.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Created

Body

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.staging.vrtx.sa/cl/v1/wallets' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "business_id": "01df2b9e-e17b-4372-a589-a627fc2c6929",
    "name": " 2 1111محفظة رئيسية",
    "label_id": "da28e8f5-f675-477c-81e6-de174f766be1",
    "external_reference": "WALLET-RIYADH-00122111444331",
    "can_overdraft": false,
    "status": "ACTIVE",
    "currency": "SAR"
}'

Response Example

201 - WalletCreated

{
    "id": "d8a7f71f-cabd-4720-b7cc-b6745a10cbe2",
    "business_id": "2bb58ca6-1b9a-47b4-ab4d-b2996f0498f3",
    "name": "محفظة رئيسية",
    "label_id": "5a36c74a-e479-43cd-a420-fb72a591d3e6",
    "external_reference": "WALLET-RIYADH-00122",
    "can_overdraft": false,
    "status": "ACTIVE",
    "account_number": "054200007018",
    "currency": "SAR",
    "balance": "0.00",
    "created_at": "2025-10-25T14:10:15.151Z",
    "updated_at": "2025-10-25T14:10:15.151Z"
}

Modified at 2025-12-03 07:59:44

List wallets

Lookup wallet

Create wallet

Wallet Account Structure#

Request

Responses

Wallet Account Structure