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

Example

{
    "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"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

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"
}'

Responses

🟢201Created

application/json

Created

Body

Example

{
    "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"
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

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

List wallets

Lookup wallet

Create wallet

Wallet Account Structure#

Request

Request Code Samples

Responses

Wallet Account Structure