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-Token on 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.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();
}

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-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
    INVALID_WALLET_TOKEN
    Type
    401
    Description
    X-Wallet-Token is missing, wrong, or rotated
  • Name
    RATE_LIMITED
    Type
    429
    Description
    Too many calls. Wait for the Retry-After seconds

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.

GET/me

Find Wallet

Request

GET
/me
{}

Response 200

{
  "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "type": "PERSONAL",
  "externalId": "u-42",
  "status": "ACTIVE",
  "firstName": "Ahmed",
  "lastName": "Ali",
  "identityVerified": true
}

POST/me/token/rotate

Rotate Token

Request

POST
/me/token/rotate
{}

Response 200

{
  "walletToken": "wt_QfptQ-s6SAhPOOFDNVHLaGcaff3SIc3sbiBUXdXRGzs"
}

GET/balance

Balance

Request

GET
/balance
{}

Response 200

{
  "total": 125000,
  "available": 120000,
  "hold": 5000,
  "currency": "SAR"
}

GET/account

Account

Request

GET
/account
{}

Response 200

{
  "accountNumber": "100000000042",
  "iban": "SA0380000000608010167519",
  "bankName": "NearPay",
  "currency": "SAR",
  "status": "OPEN",
  "openedAt": "2026-11-16T08:20:00.000Z",
  "holderName": "Ahmed Ali"
}

GET/transactions

List Transactions

Request

GET
/transactions
{}

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.

GET/beneficiaries

List Beneficiaries

Request

GET
/beneficiaries
{}

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

POST/beneficiaries

Add Beneficiary

Request

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

POST/beneficiaries/{id}/verify

Verify Beneficiary

Request

POST
/beneficiaries/{id}/verify
{
  "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"
}

DELETE/beneficiaries/{id}

Remove Beneficiary

Request

DELETE
/beneficiaries/{id}
{}

Response 200

{
  "deleted": true
}

Transfers

Send money to a saved beneficiary. Get a quote first for international beneficiaries.

GET/transfers/options

Transfer Options

Request

GET
/transfers/options
{}

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

GET/transfers/quote

Transfer Quote

Request

GET
/transfers/quote
{}

Response 200

{
  "beneficiaryId": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "amount": 10000,
  "fee": 2500,
  "totalDebit": 12500,
  "rate": "0.9793",
  "receiveAmount": 9793,
  "receiveCurrency": "AED"
}

POST/transfers

Create Transfer

Request

POST
/transfers
{
  "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.

POST/topups

Create Top-up

Request

POST
/topups
{
  "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.

GET/catalog/billers

List Billers

Request

GET
/catalog/billers
{}

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": []
    }
  ]
}

GET/bills

List Bills

Request

GET
/bills
{}

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

POST/bills

Add Bill

Request

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

POST/bills/{billId}/pay

Pay Bill

Request

POST
/bills/{billId}/pay
{}

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.

GET/catalog/categories

List Categories

Request

GET
/catalog/categories
{}

Response 200

[
  { "code": "GAMING", "name": "Gaming", "nameAr": "الألعاب" },
  { "code": "ENTERTAINMENT", "name": "Entertainment", "nameAr": "الترفيه" }
]

GET/catalog/brands

List Brands

Request

GET
/catalog/brands
{}

Response 200

[
  {
    "code": "ITUNES",
    "name": "iTunes",
    "nameAr": "آيتونز",
    "category": "ENTERTAINMENT",
    "color": "#FA2D48",
    "imageUrl": "https://cdn.example.com/brands/itunes.png",
    "fromPrice": 5000,
    "currency": "SAR"
  }
]

GET/catalog/brands/{code}

Find Brand

Request

GET
/catalog/brands/{code}
{}

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

POST/orders

Create Order

Request

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

GET/orders

List Orders

Request

GET
/orders
{}

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
}

GET/orders/{orderId}

Find Order

Request

GET
/orders/{orderId}
{}

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.walletId is 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.

  • walletId is the wallet. It is null for application events before the wallet opens. Those carry data.applicationId.
  • externalId is your own id, or null if you did not send one.
  • Webhooks never carry the wallet token or a stepId.

Request

POST
your webhook URL
{
  "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.body using 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 2xx within 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.