Onboarding API
Open NearPay wallets for your customers from your own backend.
After a wallet opens, use the Wallet API to move money.
How it works
- Your app collects the customer's details, OTP code, and choices.
- Your backend signs each request and calls the API.
- An application opens each wallet, one step at a time.
- Accept Terms returns the wallet token. Store it for the Wallet API.
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();
}
Errors
Every error has the same shape:
{ "code": "STEP_OUT_OF_ORDER", "message": "This application is on the IDENTITY step.", "currentStep": "IDENTITY" }
- 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
APPLICATION_NOT_FOUND- Type
- 404
- Description
- No application with this id
- Name
STEP_OUT_OF_ORDER- Type
- 409
- Description
- Wrong step. Includes
currentStep
- Name
INVALID_STEP_ID- Type
- 409
- Description
- The
stepIdis wrong, used, or older than 30 minutes
- Name
APPLICATION_EXPIRED- Type
- 410
- Description
- The application is older than 24 hours. Start a new one
- Name
RATE_LIMITED- Type
- 429
- Description
- Too many calls. Wait for the
Retry-Afterseconds
Start Application and Resend OTP allow 30 calls per minute per client.
Applications
An application opens one wallet. Each step returns a nextStepId. Send it with the next step. It works once and lasts 30 minutes.
- Name
PERSONAL- Type
- type
- Description
- Mobile, identity, address, terms
- Name
BUSINESS- Type
- type
- Description
- Mobile, owner identity, business CR, business address, terms
- A business wallet is its own wallet, apart from the owner's personal wallet.
- The owner verifies with Nafath. Their ID must be an owner on the CR.
- Lost the
stepId? Find Application shows the current step. Start again when it has expired. - A step that fails keeps the same
stepId, so you can retry. - Accept Terms opens the wallet and returns the wallet token once.
Show the random number from Start Identity in your app. The customer picks the same number in the Nafath app. Check Identity Status, or wait for the application.identity_verified webhook.
Start Application
Request
{
"type": "PERSONAL",
"mobile": "0501234567",
"externalId": "u-42"
}
Response 201
{
"id": "0f3c2b1a-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"type": "PERSONAL",
"status": "IN_PROGRESS",
"externalId": "u-42",
"currentStep": "MOBILE",
"completedSteps": [],
"walletId": null,
"expiresAt": "2026-11-17T08:00:00.000Z",
"nextStep": "MOBILE",
"nextStepId": "stp_DcHqFoACo9MDUUmmsq1ePhBhc0N7KVEMHjQd94sQXzE",
"otpExpiresIn": 300
}
Find Application
Request
{}
Response 200
{
"id": "0f3c2b1a-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"type": "PERSONAL",
"status": "IN_PROGRESS",
"externalId": "u-42",
"currentStep": "ADDRESS",
"completedSteps": ["MOBILE", "IDENTITY"],
"walletId": null,
"expiresAt": "2026-11-17T08:00:00.000Z"
}
Verify Mobile
Request
{
"stepId": "stp_DcHqFoACo9MDUUmmsq1ePhBhc0N7KVEMHjQd94sQXzE",
"code": "123456",
"firstName": "Ahmed",
"lastName": "Ali",
"email": "[email protected]"
}
Response 200
{
"nextStep": "IDENTITY",
"nextStepId": "stp_StTgSCoRT8xCtNh7HTqidEhS0ixfOvDPpdMpaVSprmg"
}
Resend OTP
Request
{
"stepId": "stp_DcHqFoACo9MDUUmmsq1ePhBhc0N7KVEMHjQd94sQXzE"
}
Response 200
{
"otpExpiresIn": 300
}
Start Identity
Request
{
"stepId": "stp_StTgSCoRT8xCtNh7HTqidEhS0ixfOvDPpdMpaVSprmg",
"nationalId": "1234567890"
}
Response 200
{
"status": "WAITING",
"random": "42",
"expiresIn": 180
}
Identity Status
Request
{}
Response 200
{
"status": "COMPLETED",
"nextStep": "ADDRESS",
"nextStepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y"
}
Waiting 200
{
"status": "WAITING",
"random": "42",
"remainingTime": 120
}
Find Address
Personal only. Looks up the national address of the verified ID.
Request
{
"stepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y"
}
Response 200
{
"requiresManualEntry": false,
"address": {
"region": "Riyadh",
"regionAr": "الرياض",
"city": "Riyadh",
"cityAr": "الرياض",
"district": "Al Olaya",
"districtAr": "العليا",
"street": "King Fahd Road",
"streetAr": "طريق الملك فهد",
"buildingNumber": "1234",
"postalCode": "12211",
"additionalNumber": "5678",
"source": "SPL",
"confirmed": false
}
}
Manual entry 200
{
"requiresManualEntry": true,
"reason": "NOT_FOUND"
}
Confirm Address
Request
{
"stepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y",
"manual": {
"region": "Riyadh",
"city": "Riyadh",
"district": "Al Olaya",
"street": "King Fahd Road",
"buildingNumber": "1234",
"postalCode": "12211"
}
}
Response 200
{
"address": {
"region": "Riyadh",
"city": "Riyadh",
"district": "Al Olaya",
"street": "King Fahd Road",
"buildingNumber": "1234",
"postalCode": "12211",
"source": "MANUAL",
"confirmed": true
},
"nextStep": "TERMS",
"nextStepId": "stp_lai_sb6jlwCn4VCWjL57eMn8wYjZ5Rj81-R5r9_ARwk"
}
Verify Business
Business only. Checks the CR with Wathq and that the verified owner is on it.
Request
{
"stepId": "stp_72VkcG9YRJrq_hz4OKpkvT8ELSzu3xV_kF-U5Nyjdso",
"crNumber": "7001234567"
}
Response 200
{
"business": {
"crNumber": "1010123456",
"crNationalNumber": "7001234567",
"name": "شركة المثال التجارية",
"entityType": "Limited Liability Company",
"crStatus": "نشط",
"issueDate": "2020-01-15",
"activities": ["Retail trade"]
},
"nextStep": "BUSINESS_ADDRESS",
"nextStepId": "stp_L9PE1z9NI91h7oaB9WVPxceaRwWE9Hjt5W_geBFA5-k"
}
Find Business Address
Business only. Looks up the CR's national address.
Request
{
"stepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y"
}
Response 200
{
"requiresManualEntry": false,
"address": {
"region": "Riyadh",
"regionAr": "الرياض",
"city": "Riyadh",
"cityAr": "الرياض",
"district": "Al Olaya",
"districtAr": "العليا",
"street": "King Fahd Road",
"streetAr": "طريق الملك فهد",
"buildingNumber": "1234",
"postalCode": "12211",
"additionalNumber": "5678",
"source": "SPL",
"confirmed": false
}
}
Manual entry 200
{
"requiresManualEntry": true,
"reason": "NOT_FOUND"
}
Confirm Business Address
Request
{
"stepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y",
"manual": {
"region": "Riyadh",
"city": "Riyadh",
"district": "Al Olaya",
"street": "King Fahd Road",
"buildingNumber": "1234",
"postalCode": "12211"
}
}
Response 200
{
"address": {
"region": "Riyadh",
"city": "Riyadh",
"district": "Al Olaya",
"street": "King Fahd Road",
"buildingNumber": "1234",
"postalCode": "12211",
"source": "MANUAL",
"confirmed": true
},
"nextStep": "TERMS",
"nextStepId": "stp_lai_sb6jlwCn4VCWjL57eMn8wYjZ5Rj81-R5r9_ARwk"
}
Find Terms
Request
{}
Response 200
{
"id": "3b2f7c1a-0e4d-4f5a-9c8b-1a2b3c4d5e6f",
"version": 3,
"title": "Wallet Terms and Conditions",
"titleAr": "الشروط والأحكام للمحفظة",
"content": "...",
"contentAr": "...",
"publishedAt": "2026-10-01T00:00:00.000Z",
"hasPdf": true,
"pdfName": "wallet-terms-v3.pdf"
}
Accept Terms
Request
{
"stepId": "stp_lai_sb6jlwCn4VCWjL57eMn8wYjZ5Rj81-R5r9_ARwk",
"acceptedTermsId": "3b2f7c1a-0e4d-4f5a-9c8b-1a2b3c4d5e6f",
"customerIp": "203.0.113.10"
}
Response 200
{
"status": "COMPLETED",
"walletToken": "wt_Uv7q60iD96-QTHQaWkc_5PcYwKah5BYIwIvDnD1Xg_w",
"wallet": {
"id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"type": "PERSONAL",
"externalId": "u-42",
"account": {
"accountNumber": "100000000042",
"iban": "SA0380000000608010167519",
"status": "OPEN"
}
}
}
Webhooks
Application events tell you when identity is verified, the wallet opens, or the application expires. See Webhooks for the payload and signature.