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.body using your signing secret
  • Name
    X-Wallet-Token
    Type
    string
    Description
    wt_... for wallet calls
  • path is the full path with the query string, for example /api/v1/wallet/transactions?limit=20.
  • walletToken is the X-Wallet-Token value. Use an empty string when you do not send one.
  • body is 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-Timestamp is missing or off by more than 5 minutes
  • Name
    INVALID_SIGNATURE
    Type
    401
    Description
    X-Signature does 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 stepId is 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-After seconds

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.

POST/applications

Start Application

Request

POST
/applications
{
  "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
}

GET/applications/{id}

Find Application

Request

GET
/applications/{id}
{}

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

POST/applications/{id}/mobile

Verify Mobile

Request

POST
/applications/{id}/mobile
{
  "stepId": "stp_DcHqFoACo9MDUUmmsq1ePhBhc0N7KVEMHjQd94sQXzE",
  "code": "123456",
  "firstName": "Ahmed",
  "lastName": "Ali",
  "email": "[email protected]"
}

Response 200

{
  "nextStep": "IDENTITY",
  "nextStepId": "stp_StTgSCoRT8xCtNh7HTqidEhS0ixfOvDPpdMpaVSprmg"
}

POST/applications/{id}/mobile/resend

Resend OTP

Request

POST
/applications/{id}/mobile/resend
{
  "stepId": "stp_DcHqFoACo9MDUUmmsq1ePhBhc0N7KVEMHjQd94sQXzE"
}

Response 200

{
  "otpExpiresIn": 300
}

POST/applications/{id}/identity

Start Identity

Request

POST
/applications/{id}/identity
{
  "stepId": "stp_StTgSCoRT8xCtNh7HTqidEhS0ixfOvDPpdMpaVSprmg",
  "nationalId": "1234567890"
}

Response 200

{
  "status": "WAITING",
  "random": "42",
  "expiresIn": 180
}

GET/applications/{id}/identity

Identity Status

Request

GET
/applications/{id}/identity
{}

Response 200

{
  "status": "COMPLETED",
  "nextStep": "ADDRESS",
  "nextStepId": "stp_LaQ_09OCbTfLUtRDmu5lgumBzuTsq208uB-j5VCPN7Y"
}

Waiting 200

{
  "status": "WAITING",
  "random": "42",
  "remainingTime": 120
}

POST/applications/{id}/address

Find Address

Personal only. Looks up the national address of the verified ID.

Request

POST
/applications/{id}/address
{
  "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"
}

POST/applications/{id}/address/confirm

Confirm Address

Request

POST
/applications/{id}/address/confirm
{
  "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"
}

POST/applications/{id}/business

Verify Business

Business only. Checks the CR with Wathq and that the verified owner is on it.

Request

POST
/applications/{id}/business
{
  "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"
}

POST/applications/{id}/business-address

Find Business Address

Business only. Looks up the CR's national address.

Request

POST
/applications/{id}/business-address
{
  "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"
}

POST/applications/{id}/business-address/confirm

Confirm Business Address

Request

POST
/applications/{id}/business-address/confirm
{
  "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"
}

GET/terms

Find Terms

Request

GET
/terms
{}

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

POST/applications/{id}/terms

Accept Terms

Request

POST
/applications/{id}/terms
{
  "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.