NattyPay LogoSign Up
DEVELOPERS

Build with NattyPay APIs

DocumentationAPI Reference

Auth

POSTRegister User

Register a new user.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/auth/register-user
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/auth/register-business' \
--header 'x-api-key: 2442555352662653' \
--data-raw '{
  "username": "AbuksLC",
  "fullname": "Abuks Inc",
  "email": "abuksinccc@gmail.com",
  "password": "Caicedo123",
  "dateOfBirth": "8-Mar-1996",
  "countryCode": "NGN",
  "companyRegistrationNumber":"RC-234555",
  "accountType":"BUSINESS",
  "referralCode": ""
}'

Body Parameters

{
  "username": "AbuksLC",
  "fullname": "Abuks Inc",
  "email": "abuksinccc@gmail.com",
  "password": "Caicedo123",
  "dateOfBirth": "8-Mar-1996",
  "countryCode": "NGN",
  "companyRegistrationNumber":"RC-234555",
  "accountType":"BUSINESS",
  "referralCode": ""
}
Sample Response
200 OK
{
  "message": "User created successfully",
  "user": {
    "id": "4c8c3a7e-58a8-4c3c-8915-d73317ae4f43",
    "email": "abuksinccc@gmail.com",
    "username": "AbuksLC",
    "fullname": "Abuks Inc",
    "createdAt": "2025-06-01T20:55:55.374Z",
    "status": "active",
    "accountType": "BUSINESS"
  },
  "statusCode": 200
}

User

POSTVerify Phone Number

Verify user phone number with OTP.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/user/verify-phoneNumber
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/verify-phoneNumber' \
--header 'x-api-key: 2442555352662653' \
--data '{
  "email": "abrahamosazee3@gmail.com",
  "otp": "8773"
}'

Body Parameters

{
  "email": "abrahamosazee3@gmail.com",
  "otp": "8773"
}
Sample Response
200 OK
{
  "message": "Phone number verified successfully",
  "statusCode": 200
}

POSTVerify NIN

Verify user's National Identity Number (NIN).

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/user/verify-nin
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/verify-nin' \
--header 'x-api-key: 2442555352662653' \
--data '{
  "nin": ""
}'

Body Parameters

{
  "nin": ""
}
Sample Response
200 OK
{
  "message": "NIN verified successfully",
  "statusCode": 200
}

POSTReport Scam

Report a scam incident.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/user/report-scam
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/report-scam' \
--header 'x-api-key: 2442555352662653' \
--form 'screenshot=@"path/to/file"' \
--form 'title="title of the report scam"' \
--form 'description="description"'

Body Parameters

{
  "screenshot": "[File]",
  "title": "title of the report scam",
  "description": "description"
}
Sample Response
200 OK
{
  "message": "Information retrieve successfully",
  "statusCode": 200
}

POSTCreate Business Account

Create a business account for a user.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/user/create-business-account
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/create-business-account' \
--header 'x-api-key: 2442555352662653' \
--data '{
  "bvn": "22222222226",
  "companyRegistrationNumber": "RC34564567"
}'

Body Parameters

{
  "bvn": "22222222226",
  "companyRegistrationNumber": "RC34564567"
}
Sample Response
200 OK
{
  "message": "Business wallet created successfully",
  "statusCode": 201,
  "data": {
    "id": "65754e0b-43b8-458a-8ef5-36f6753c38a3",
    "userId": "790aebfd-316b-4bcf-88ee-5a64beea797c",
    "balance": "0",
    "currency": "NGN",
    "accountName": "nattypay/Abuks llc",
    "bankName": "WEMA BANK",
    "bankCode": null,
    "accountNumber": "8548729462",
    "createdAt": "2024-12-27T01:53:45.847Z",
    "updatedAt": "2024-12-27T01:53:45.847Z",
    "accountRef": "URF_1735264416834_7779635"
  }
}

PUTChange Passcode

Change the user's passcode.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

PUT/api/v1/user/change-passcode
cURL
curl --location --request PUT 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/change-passcode' \
--header 'x-api-key: 2442555352662653' \
--data '{
  "oldPasscode": "123456",
  "newPasscode": "123452"
}'

Body Parameters

{
  "oldPasscode": "123456",
  "newPasscode": "123452"
}
Sample Response
200 OK
{
  "message": "Passcode updated successfully",
  "statusCode": 200
}

POSTCreate Foreign Account

Create a foreign currency account.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

POST/api/v1/user/create-foreign-account
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/user/create-foreign-account' \
--header 'x-api-key: 2442555352662653' \
--data '{
  "currency": "USD"
}'

Body Parameters

{
  "currency": "USD"
}
Sample Response
200 OK
{
  "message": "Account must be of USD type",
  "error": "Bad Request",
  "statusCode": 400
}

Bill

GETGet Airtime Variation

Retrieve airtime variation details for a specific operator.

Headers

authorization

Bearer Token

Set value to Bearer <token>

x-api-key

string

Set value to 2442555352662653

cURL Request

GET/api/v1/bill/airtime/get-variation?operatorId=341
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/bill/airtime/get-variation?operatorId=341' --header 'x-api-key: 2442555352662653'

Body Parameters

Sample Response
200 OK
{
  "message": "Variation retrieve successfully",
  "statusCode": 200,
  "data": {
    "id": 341,
    "operatorId": 341,
    "name": "MTN Nigeria",
    "bundle": false,
    "data": false,
    "pin": false,
    "comboProduct": false,
    "supportsLocalAmounts": true,
    "supportsGeographicalRechargePlans": false,
    "denominationType": "RANGE",
    "senderCurrencyCode": "NGN",
    "senderCurrencySymbol": "₦",
    "destinationCurrencyCode": "NGN",
    "destinationCurrencySymbol": "₦",
    "commission": 5,
    "internationalDiscount": 5,
    "localDiscount": 0,
    "mostPopularAmount": null,
    "mostPopularLocalAmount": null,
    "minAmount": 50,
    "maxAmount": 200000,
    "localMinAmount": null,
    "localMaxAmount": null,
    "country": {
      "isoName": "NG",
      "name": "Nigeria"
    },
    "fx": {
      "rate": 1,
      "currencyCode": "NGN"
    }
  }
}
GETGet Airtime Plan
Retrieve available airtime plans for a specific operator.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
GET/api/v1/bill/airtime/get-plans?operatorId=341
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/bill/airtime/get-plans?operatorId=341' --header 'x-api-key: 2442555352662653'
Body Parameters
Sample Response
200 OK
{
  "message": "Plans retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": 1,
      "name": "MTN 1GB Data Plan",
      "amount": 1000,
      "validity": "30 days",
      "description": "1GB data bundle valid for 30 days"
    },
    {
      "id": 2,
      "name": "MTN 2.5GB Data Plan",
      "amount": 2000,
      "validity": "30 days",
      "description": "2.5GB data bundle valid for 30 days"
    }
  ]
}
POSTPay for School Fee
Make a school fee payment.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
POST/api/v1/bill/pay/school-fee
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/bill/pay/school-fee' --header 'x-api-key: 2442555352662653' --data '{
  "schoolId": "12345",
  "studentId": "STU123",
  "amount": 50000,
  "term": "First Term",
  "session": "2023/2024",
  "pin": "1234"
}'
Body Parameters
{
  "schoolId": "12345",
  "studentId": "STU123",
  "amount": 50000,
  "term": "First Term",
  "session": "2023/2024",
  "pin": "1234"
}
Sample Response
200 OK
{
  "message": "School fee payment successful",
  "statusCode": 200,
  "data": {
    "transactionId": "TXN123456789",
    "amount": 50000,
    "fee": 100,
    "totalAmount": 50100,
    "status": "success",
    "date": "2023-06-15T10:30:00.000Z"
  }
}
GETGet Data Plans
Retrieve available data plans for a specific network.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
GET/api/v1/bill/data/plans?network=MTN
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/bill/data/plans?network=MTN' --header 'x-api-key: 2442555352662653'
Body Parameters
Sample Response
200 OK
{
  "message": "Data plans retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "planId": "MTN-1GB",
      "name": "1GB Data Plan",
      "amount": 1000,
      "validity": "30 days",
      "description": "1GB data bundle valid for 30 days"
    },
    {
      "planId": "MTN-2.5GB",
      "name": "2.5GB Data Plan",
      "amount": 2000,
      "validity": "30 days",
      "description": "2.5GB data bundle valid for 30 days"
    }
  ]
}
POSTBuy Data
Purchase a data plan.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
POST/api/v1/bill/data/buy
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/bill/data/buy' --header 'x-api-key: 2442555352662653' --data '{
  "network": "MTN",
  "phoneNumber": "08012345678",
  "planId": "MTN-1GB",
  "amount": 1000,
  "pin": "1234"
}'
Body Parameters
{
  "network": "MTN",
  "phoneNumber": "08012345678",
  "planId": "MTN-1GB",
  "amount": 1000,
  "pin": "1234"
}
Sample Response
200 OK
{
  "message": "Data purchase successful",
  "statusCode": 200,
  "data": {
    "transactionId": "TXN987654321",
    "network": "MTN",
    "phoneNumber": "08012345678",
    "plan": "1GB Data Plan",
    "amount": 1000,
    "validity": "30 days",
    "status": "success",
    "date": "2023-06-15T10:30:00.000Z"
  }
}
Wallet
POSTSet Wallet PIN
Set a new wallet PIN.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
POST/api/v1/wallet/set-pin
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/set-pin' --header 'x-api-key: 2442555352662653' --data '{
  "pin": "1234"
}'
Body Parameters
{
  "pin": "1234"
}
Sample Response
200 OK
No response body (204 No Content)
PUTChange Wallet PIN
Change the user's wallet PIN.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
PUT/api/v1/wallet/change-pin
cURL
curl --location --request PUT 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/change-pin' --header 'x-api-key: 2442555352662653' --data '{
  "oldPin": "1234",
  "newPin": "5678"
}'
Body Parameters
{
  "oldPin": "1234",
  "newPin": "5678"
}
Sample Response
200 OK
No response body (204 No Content)
POSTDecode QR Code
Decode a QR code to get bank details.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
POST/api/v1/wallet/decode-qr
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/decode-qr' --header 'x-api-key: 2442555352662653' --data '{
  "qrCode": "data:image/png;base64,iVBOR..."
}'
Body Parameters
{
  "qrCode": "data:image/png;base64,iVBOR..."
}
Sample Response
200 OK
{
  "message": "QR Code decoded successfully",
  "statusCode": 200,
  "data": {
    "bankCode": "090286",
    "accountNumber": "8024123703",
    "currency": "NGN",
    "amount": "500"
  }
}
GETGenerate QR Code
Generate a QR code for receiving payments.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
GET/api/v1/wallet/generate-qrcode?amount=500
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/generate-qrcode?amount=500' --header 'x-api-key: 2442555352662653'
Body Parameters
Sample Response
200 OK
{
  "message": "Qrcode generated successfully",
  "statusCode": 200,
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAANQAAADUCAYAAADk3g0YAAAAAklEQVR4AewaftIAAAqZSURBVO3BQY7gRpIAQXei/v9l3z7GKQGCWS1pNszsD9ZaVzusta55WGtd87DWuuZhrXXNw1rrmoe11jUPa61rHtZa1zysta55WGtd87DWuuZhrXXNw1rrmoe11jUPa61rfvhI5W+qOFE5qZhUpopJ5aRiUjmpmFTeqJhUpopJ5Y2KSWWqOFGZKk5UpopJ5W+q+OJhrXXNw1rrmoe11jU/XFZxk8obFTdVvFHxRsWkMlWcVJxUnKhMKr9JZap4o+ImlZse1lrXPKy1rnlYa13zwy9TeaPiDZU3Kk5UpopJZaqYVE4qJpWpYlJ5o+KNikllqphU/k1U3qj4TQ9rrWse1lrXPKy1rvnh/7mKNyq+UJkqTiomlaniRGWqeEPlpGJSeUNlqvgve1hrXfOw1rrmYa11zQ//YyomlROVLyq+UPlC5TdVfKHy/8nDWuuah7XWNQ9rrWt++GUVf5PKGxWTyknFGxWTyknFGypTxaRyojJVTCpTxaQyVfxNFf8mD2utax7WWtc8rLWu+eEylX9SxaRyojJVTConKlPFpDJVTConKlPFf4nKVDGpTBUnKv9mD2utax7WWtc8rLWusT/4D1O5qeJE5aTiROWk4g2VqWJSOal4Q2WqeEPlpOK/7GGtdc3DWuuah7XWNfYHH6hMFZPKTRVvqLxRMal8UXGiclPFicobFZPKVDGpTBUnKlPFpHJTxW96WGtd87DWuuZhrXXNDx9VvFFxojJVnKicVEwqX1S8oTJVfFHxhspJxaTyhspU8UbFpDJVTCo3qUwVXzysta55WGtd87DWusb+4CKVqeJE5Y2KL1TeqPhC5aRiUpkqTlTeqJhU3qiYVN6oeENlqphU3qj4TQ9rrWse1lrXPKy1rrE/+ItUTipOVKaKSeWNiknlpOJE5aTiROWNikllqjhReaNiUpkqJpWpYlKZKk5UpopJ5aaHtdY1D2utax7WWtf88C9XMalMFScqU8Wk8kbFpHJTxRsqU8WkMlW8UTGpTBUnKlPFpDJVnKhMFV88rLWueVhrXfOw1rrmh/8xKicVk8pUMalMFZPKScWkMlVMKlPFpDJVnKhMFZPKVHGiMlW8UTGpTBWTylQxqUwVJypTxRcPa61rHtZa1zysta754X+cylRxUjGpTBVvqEwVk8pJxRsqU8WkMlW8UTGpTBUnKlPFpDJVnKhMFV88rLWueVhrXfOw1rrmYa11zcNa65qHtdY1D2utax7WWtc8rLWueVhrXfOw1rrmYa11zcNa65qHtdY1D2utax7WWtc8rLWueVhrXfOw1rrmYa11zf8BfXc8XQmZq8EAAAAASUVORK5CYII="
}
POSTInitiate Transfer
Initiate a transfer to a bank account.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
POST/api/v1/wallet/initiate-transfer
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/initiate-transfer' --header 'x-api-key: 2442555352662653' --data '{
  "bankCode": "035",
  "accountNumber": "8548737465",
  "amount": 500,
  "currency": "NGN",
  "description": ""
}'
Body Parameters
{
  "bankCode": "035",
  "accountNumber": "8548737465",
  "amount": 500,
  "currency": "NGN",
  "description": ""
}
Sample Response
200 OK
{
  "message": "Minimun amount for transfer is 50",
  "error": "Bad Request",
  "statusCode": 400
}
GETGet All Transactions
Get a list of all wallet transactions with pagination and filtering.
Headers
authorization
Bearer Token
Set value to Bearer <token>
x-api-key
string
Set value to 2442555352662653
cURL Request
GET/api/v1/wallet/transaction?page=1&limit=2&type=CREDIT&category=DEPOSIT
cURL
curl --location 'https://backend-api-production-e3f2.up.railway.app/api/v1/wallet/transaction?page=1&limit=2&type=CREDIT&category=DEPOSIT' --header 'x-api-key: 2442555352662653'
Body Parameters
Sample Response
200 OK
{
  "transactions": [
    {
      "id": "1f074049-ec63-40f9-b929-530087e57f82",
      "walletId": "a6991eeb-2132-4b8d-9544-86a9a337c06a",
      "transactionRef": null,
      "type": "CREDIT",
      "category": "DEPOSIT",
      "currency": "NGN",
      "status": "success",
      "description": "Safe-",
      "previousBal": "0.00",
      "currentBal": "0.00",
      "amount": "500.00",
      "createdAt": "2025-03-14T11:23:45.000Z",
      "updatedAt": "2025-03-14T11:23:45.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 2,
    "totalPages": 1
  }
}