Wallet API
Run an open NearPay wallet from your own backend. Build your own app and screens.
No wallet yet? Open one with the Onboarding API. Using the mobile SDK instead? See the Wallet SDK guide.
How it works
- Your backend signs each request and calls the API.
- A wallet token from Accept Terms picks the wallet. Send it in
X-Wallet-Tokenon every wallet call.
Authentication
NearPay uses an API key and a request signature to authenticate.
Credentials
- Name
API key- Type
- wk_...
- Description
- Sent as a bearer token on every request
- Name
Signing secret- Type
- wss_...
- Description
- Signs every request. Never send it
- Name
Webhook secret- Type
- whsec_...
- Description
- Verifies webhooks sent to you
- Name
Wallet token- Type
- wt_...
- Description
- One per wallet. Returned once by Accept Terms
Wallet token
Each wallet gets its own token when its application is approved. Send it in X-Wallet-Token on every wallet call, like Balance or Create Transfer.
- Store it encrypted on your server, next to your user. Never send it to your app.
- NearPay keeps only a hash. A lost token cannot be shown again.
- Rotate it with Rotate Token. The old token stops working at once.
- A missing or wrong token returns
401 INVALID_WALLET_TOKEN.
Sign requests
Send these headers on every request:
- Name
Authorization *- Type
- string
- Description
Bearer wk_...
- Name
X-Timestamp *- Type
- string
- Description
- Current Unix time in seconds. Must be within 5 minutes
- Name
X-Signature *- Type
- string
- Description
- Hex HMAC-SHA256 of
timestamp.METHOD.path.walletToken.bodyusing your signing secret
- Name
X-Wallet-Token- Type
- string
- Description
wt_...for wallet calls
pathis the full path with the query string, for example/api/v1/wallet/transactions?limit=20.walletTokenis theX-Wallet-Tokenvalue. Use an empty string when you do not send one.bodyis the exact JSON you send. Use an empty string when there is no body.
import { createHmac } from "crypto";
async function call(method, path, body, walletToken = "") {
const payload = body ? JSON.stringify(body) : "";
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.WALLET_SIGNING_SECRET)
.update(`${timestamp}.${method}.${path}.${walletToken}.${payload}`)
.digest("hex");
const response = await fetch(`https://${process.env.WALLET_HOST}${path}`, {
method,
headers: {
Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
"Content-Type": "application/json",
"X-Timestamp": timestamp,
"X-Signature": signature,
...(walletToken ? { "X-Wallet-Token": walletToken } : {}),
},
body: payload || undefined,
});
return response.json();
}
Amounts
All amounts are whole numbers in halalas. 1050 means 10.50 SAR. The currency is always SAR.
Idempotency
Top-ups, transfers, bill payments, and orders need an Idempotency-Key header. Use 8 to 128 letters, digits, _, or -.
- Same key and same body: you get the first response again. No second charge.
- Same key and a different body:
422 IDEMPOTENCY_KEY_REUSED. - First request still running:
409 IDEMPOTENCY_IN_PROGRESS. Retry shortly. - Failed requests release the key, so you can retry with it.
Keys last 24 hours. Use a new key for each new payment.
Pagination
List endpoints return data, has_more, and next_cursor. Pass next_cursor as cursor to get the next page.
Errors
Every error has the same shape:
{ "code": "INVALID_WALLET_TOKEN", "message": "Send the wallet token from the approved application in the X-Wallet-Token header." }
- Name
INVALID_API_KEY- Type
- 401
- Description
- Missing, revoked, or expired key
- Name
STALE_TIMESTAMP- Type
- 401
- Description
X-Timestampis missing or off by more than 5 minutes
- Name
INVALID_SIGNATURE- Type
- 401
- Description
X-Signaturedoes not match the request
- Name
CLIENT_SUSPENDED- Type
- 403
- Description
- NearPay suspended your client
- Name
IP_NOT_ALLOWED- Type
- 403
- Description
- The calling IP is not on your list
- Name
INVALID_WALLET_TOKEN- Type
- 401
- Description
X-Wallet-Tokenis missing, wrong, or rotated
- Name
RATE_LIMITED- Type
- 429
- Description
- Too many calls. Wait for the
Retry-Afterseconds
300 calls per minute per client.
Wallet
Every call from here on needs X-Wallet-Token. Read the wallet, its balance, account, and transaction history.
Find Wallet
Request
{}
Response 200
{
"id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"type": "PERSONAL",
"externalId": "u-42",
"status": "ACTIVE",
"firstName": "Ahmed",
"lastName": "Ali",
"identityVerified": true
}
Rotate Token
Request
{}
Response 200
{
"walletToken": "wt_QfptQ-s6SAhPOOFDNVHLaGcaff3SIc3sbiBUXdXRGzs"
}
Balance
Request
{}
Response 200
{
"total": 125000,
"available": 120000,
"hold": 5000,
"currency": "SAR"
}
Account
Request
{}
Response 200
{
"accountNumber": "100000000042",
"iban": "SA0380000000608010167519",
"bankName": "NearPay",
"currency": "SAR",
"status": "OPEN",
"openedAt": "2026-11-16T08:20:00.000Z",
"holderName": "Ahmed Ali"
}
List Transactions
Request
{}
Response 200
{
"data": [
{
"id": "9f0e2b1c-4d5a-4e6f-8a7b-0c1d2e3f4a5b",
"reference": "TRF-20261116-0001",
"type": "TRANSFER",
"amount": 5000,
"currency": "SAR",
"direction": "Debit",
"channel": "WALLET",
"description": "Transfer to Sara",
"card": null,
"beneficiary": {
"id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"name": "Sara",
"bankName": "NearPay",
"accountLast4": "0042"
},
"createdAt": "2026-11-16T08:10:00.000Z"
}
],
"has_more": true,
"next_cursor": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9"
}
Beneficiaries
Save the people and accounts a customer sends money to. Some types need a code check before use.
List Beneficiaries
Request
{}
Response 200
[
{
"id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"category": "BANK",
"displayName": "Sara Ahmed",
"nickname": "Sara",
"relation": "Sister",
"mobile": null,
"accountNumber": null,
"iban": "SA4420000001234567891234",
"bankName": "Al Rajhi Bank",
"swiftCode": null,
"country": "SA",
"currency": "SAR",
"verified": true,
"createdAt": "2026-11-16T08:05:00.000Z"
}
]
Add Beneficiary
Request
{
"type": "IBAN",
"iban": "SA4420000001234567891234",
"nickname": "Sara",
"relation": "Sister"
}
Response 201
{
"id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"category": "BANK",
"displayName": "Sara Ahmed",
"nickname": "Sara",
"relation": "Sister",
"mobile": null,
"accountNumber": null,
"iban": "SA4420000001234567891234",
"bankName": "Al Rajhi Bank",
"swiftCode": null,
"country": "SA",
"currency": "SAR",
"verified": false,
"createdAt": "2026-11-16T08:05:00.000Z",
"verificationRequired": true,
"verificationExpiresIn": 300
}
Verify Beneficiary
Request
{
"code": "1234"
}
Response 200
{
"id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"category": "BANK",
"displayName": "Sara Ahmed",
"nickname": "Sara",
"relation": "Sister",
"mobile": null,
"accountNumber": null,
"iban": "SA4420000001234567891234",
"bankName": "Al Rajhi Bank",
"swiftCode": null,
"country": "SA",
"currency": "SAR",
"verified": true,
"createdAt": "2026-11-16T08:05:00.000Z"
}
Remove Beneficiary
Request
{}
Response 200
{
"deleted": true
}
Transfers
Send money to a saved beneficiary. Get a quote first for international beneficiaries.
Transfer Options
Request
{}
Response 200
{
"purposes": [
{ "code": "FAMILY_SUPPORT", "label": "Family support", "labelAr": "إعالة الأسرة" },
{ "code": "PERSONAL", "label": "Personal transfer", "labelAr": "تحويل شخصي" }
],
"internationalFee": 2500,
"countries": [
{
"code": "AE",
"name": "United Arab Emirates",
"nameAr": "الإمارات العربية المتحدة",
"currency": "AED",
"rate": "0.9793"
}
]
}
Transfer Quote
Request
{}
Response 200
{
"beneficiaryId": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"amount": 10000,
"fee": 2500,
"totalDebit": 12500,
"rate": "0.9793",
"receiveAmount": 9793,
"receiveCurrency": "AED"
}
Create Transfer
Request
{
"beneficiaryId": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"amount": 10000,
"purpose": "FAMILY_SUPPORT",
"note": "Rent"
}
Response 201
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"status": "POSTED",
"category": "BANK",
"amount": 10000,
"fee": 0,
"totalDebit": 10000,
"currency": "SAR",
"reference": "TRF-20261116-0002",
"exchange": null,
"beneficiaryId": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"balance": {
"total": 115000,
"available": 110000,
"hold": 5000,
"currency": "SAR"
}
}
Top-ups
Add money with Apple Pay, Google Pay, or bank transfer. Card numbers are not accepted. A pending top-up sends topup.succeeded once it settles.
Create Top-up
Request
{
"amount": 20000,
"method": "APPLE_PAY",
"applePayToken": "eyJkYXRhIjoi..."
}
Response 201
{
"id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
"status": "POSTED",
"charged": 20000,
"credited": 20000,
"fee": 0,
"vat": 0,
"currency": "SAR",
"balance": {
"total": 135000,
"available": 130000,
"hold": 5000,
"currency": "SAR"
}
}
Bills
Pay SADAD bills from the wallet.
List Billers
Request
{}
Response 200
{
"categories": [
{
"code": "PUBLIC_SERVICES",
"name": "Public Services",
"nameAr": "الخدمات العامة",
"billers": [
{ "code": "002", "name": "Saudi Electricity Company", "nameAr": "الشركة السعودية للكهرباء" }
]
},
{
"code": "SADAD_INTERMEDIARIES",
"name": "SADAD Intermediaries",
"nameAr": "وسطاء سداد",
"billers": []
}
]
}
List Bills
Request
{}
Response 200
[
{
"id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"category": "PUBLIC_SERVICES",
"biller": { "code": "002", "name": "Saudi Electricity Company" },
"sadadNumber": "1234567890",
"amount": 35000,
"currency": "SAR",
"status": "UNPAID",
"paidAt": null,
"createdAt": "2026-11-15T12:00:00.000Z"
}
]
Add Bill
Request
{
"billerCode": "002",
"sadadNumber": "1234567890"
}
Response 201
{
"id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"category": "PUBLIC_SERVICES",
"biller": { "code": "002", "name": "Saudi Electricity Company" },
"sadadNumber": "1234567890",
"amount": 35000,
"currency": "SAR",
"status": "UNPAID",
"paidAt": null,
"createdAt": "2026-11-16T09:00:00.000Z"
}
Pay Bill
Request
{}
Response 200
{
"bill": {
"id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"category": "PUBLIC_SERVICES",
"biller": { "code": "002", "name": "Saudi Electricity Company" },
"sadadNumber": "1234567890",
"amount": 35000,
"currency": "SAR",
"status": "PAID",
"paidAt": "2026-11-16T09:05:00.000Z",
"createdAt": "2026-11-16T09:00:00.000Z"
},
"transactionId": "f6a7b8c9-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
"reference": "BIL-20261116-0001",
"balance": {
"total": 100000,
"available": 95000,
"hold": 5000,
"currency": "SAR"
}
}
Marketplace
Sell digital vouchers and gift cards. Voucher codes are secrets. Show them only to the customer. Never log them.
List Categories
Request
{}
Response 200
[
{ "code": "GAMING", "name": "Gaming", "nameAr": "الألعاب" },
{ "code": "ENTERTAINMENT", "name": "Entertainment", "nameAr": "الترفيه" }
]
List Brands
Request
{}
Response 200
[
{
"code": "ITUNES",
"name": "iTunes",
"nameAr": "آيتونز",
"category": "ENTERTAINMENT",
"color": "#FA2D48",
"imageUrl": "https://cdn.example.com/brands/itunes.png",
"fromPrice": 5000,
"currency": "SAR"
}
]
Find Brand
Request
{}
Response 200
{
"brand": {
"code": "ITUNES",
"name": "iTunes",
"nameAr": "آيتونز",
"category": "ENTERTAINMENT",
"color": "#FA2D48",
"imageUrl": "https://cdn.example.com/brands/itunes.png",
"description": "Apple gift card",
"descriptionAr": "بطاقة هدايا أبل"
},
"regions": ["SA"],
"products": [
{
"id": "ITUNES-SA-100",
"name": "iTunes 100 SAR",
"nameAr": "آيتونز ١٠٠ ريال",
"region": "SA",
"price": 10000,
"currency": "SAR",
"inStock": true
}
]
}
Create Order
Request
{
"items": [
{ "productId": "ITUNES-SA-100", "quantity": 1 }
]
}
Response 201
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "COMPLETED",
"total": 10000,
"currency": "SAR",
"createdAt": "2026-11-16T09:30:00.000Z",
"items": [
{
"productId": "ITUNES-SA-100",
"name": "iTunes 100 SAR",
"brandCode": "ITUNES",
"unitPrice": 10000,
"quantity": 1,
"codes": [
{ "code": "XXXX-XXXX-XXXX", "pin": null, "serial": "123456", "expiresAt": null }
]
}
],
"balance": {
"total": 90000,
"available": 85000,
"hold": 5000,
"currency": "SAR"
}
}
List Orders
Request
{}
Response 200
{
"data": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "COMPLETED",
"total": 10000,
"currency": "SAR",
"createdAt": "2026-11-16T09:30:00.000Z",
"items": [
{
"productId": "ITUNES-SA-100",
"name": "iTunes 100 SAR",
"brandCode": "ITUNES",
"unitPrice": 10000,
"quantity": 1,
"codes": []
}
]
}
],
"has_more": false,
"next_cursor": null
}
Find Order
Request
{}
Response 200
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "COMPLETED",
"total": 10000,
"currency": "SAR",
"createdAt": "2026-11-16T09:30:00.000Z",
"items": [
{
"productId": "ITUNES-SA-100",
"name": "iTunes 100 SAR",
"brandCode": "ITUNES",
"unitPrice": 10000,
"quantity": 1,
"codes": [
{ "code": "XXXX-XXXX-XXXX", "pin": null, "serial": "123456", "expiresAt": null }
]
}
]
}
Webhooks
NearPay posts events to your webhook URL. Use them instead of polling.
Available events
- Name
application.identity_verified- Type
- event
- Description
- Nafath confirmed the identity. Call Identity Status for the next
stepId
- Name
application.identity_failed- Type
- event
- Description
- The Nafath request was rejected or timed out
- Name
application.completed- Type
- event
- Description
- The wallet opened.
data.walletIdis the new wallet
- Name
application.expired- Type
- event
- Description
- The application ended before it finished
- Name
customer.created- Type
- event
- Description
- A wallet was opened for your client
- Name
kyc.approved- Type
- event
- Description
- Nafath confirmed the identity of an open wallet
- Name
kyc.rejected- Type
- event
- Description
- The customer rejected the Nafath request
- Name
kyc.expired- Type
- event
- Description
- The Nafath request timed out
- Name
transfer.completed- Type
- event
- Description
- A transfer posted
- Name
transfer.failed- Type
- event
- Description
- A transfer was reversed
- Name
topup.succeeded- Type
- event
- Description
- A top-up posted
- Name
bill.paid- Type
- event
- Description
- A bill was paid
- Name
order.completed- Type
- event
- Description
- An order completed
Payload
data.id is the id of the changed item. data holds only the changed fields.
walletIdis the wallet. It isnullfor application events before the wallet opens. Those carrydata.applicationId.externalIdis your own id, ornullif you did not send one.- Webhooks never carry the wallet token or a
stepId.
Request
{
"id": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"event": "transfer.completed",
"walletId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"externalId": "u-42",
"data": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"status": "POSTED",
"amount": 10000,
"reference": "TRF-20261116-0002"
},
"createdAt": "2026-11-16T08:10:00.000Z"
}
Headers
- Name
X-Webhook-Id- Type
- string
- Description
- Same as
id. Use it to skip duplicates
- Name
X-Webhook-Event- Type
- string
- Description
- The event name
- Name
X-Webhook-Timestamp- Type
- string
- Description
- Unix time in seconds
- Name
X-Webhook-Signature- Type
- string
- Description
- Hex HMAC-SHA256 of
timestamp.bodyusing your webhook secret
Verify the signature
Use the raw body exactly as received. Reject old timestamps.
import { createHmac, timingSafeEqual } from "crypto";
function verify(rawBody, headers) {
const timestamp = headers["x-webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = createHmac("sha256", process.env.WALLET_WEBHOOK_SECRET)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const received = String(headers["x-webhook-signature"] ?? "");
return received.length === expected.length && timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
Delivery and retries
- Reply with any
2xxwithin 10 seconds. Do slow work after you reply. - Other replies and timeouts retry with growing waits, from 30 seconds up to 6 hours.
- After 8 failed tries, the event stops. NearPay can resend it for you.
- The same event can arrive more than once. Skip ids you already handled.
- Redirects are not followed.