Integration Guide
1) Getting Started
Overview
1.
POST /v1/transactions/bank-cashout/inquiry2.
POST /v1/transactions/bank-cashout/initiate3.
POST /v1/transactions/bank-cashout/completeBase URL
https://api.dev.pynil.comVersion Prefix
/v1.2) Authentication and Security
Authorization: Basic <BASE64(username:password)>X-Signature: <HMAC_SHA256_UPPERCASE_HEX>X-Timestamp: <UNIX_TIMESTAMP_SECONDS>Content-Type: application/jsonHMAC Payload (Current Implementation)
HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + UNIX_TIMESTAMP/v1/transactions/bank-cashout/inquirySecurity Rules
3) Endpoint: Inquiry
URL
POST /v1/transactions/bank-cashout/inquiryPurpose
Request Body
{
"walletNumber": "101000001",
"amount": 100,
"timestamp": "2026-01-08",
"notes": "Test request"
}Request Notes
walletNumber, amounttimestamp, notesSuccess Response (200)
{
"success": true,
"message": "Success.",
"statusCode": 200,
"data": {
"wallet": {
"branchCode": "MAIN",
"currencyCode": "SDG",
"walletName": "Marwa Omar",
"status": "Active"
},
"charges": [
{
"name": "Custody Cashout",
"amount": 20.0
}
],
"totalFees": 20.0
}
}Common Errors
400: validation error or Insufficient funds404: Wallet account not found4) Endpoint: Initiate
URL
POST /v1/transactions/bank-cashout/initiatePurpose
Request Body
{
"walletNumber": "101000001",
"amount": 100,
"timestamp": "2026-01-08",
"notes": "Test request"
}Request Notes
walletNumber, amounttimestamp, notesSuccess Response (200)
{
"success": true,
"message": "OTP sent successfully",
"statusCode": 200,
"data": {
"nilpayTranRef": "333"
}
}Common Errors
400/404/500) plus OTP delivery failures.5) Endpoint: Complete
URL
POST /v1/transactions/bank-cashout/completePurpose
Request Body
{
"transactionRef": "333",
"otp": "1632",
"bankReference": "BANK-41128"
}Request Notes
transactionRef, otp, bankReferenceotp must be exactly 4 digits.bankReference max length is 100 chars.Success Response (200)
{
"success": true,
"message": "Transaction was Completed successfully.",
"statusCode": 200,
"data": {
"transactionId": "333-1",
"reference": 333,
"date": "2026-02-03",
"direction": "Debit",
"amount": 100.0,
"description": "Bank Cashout - Marwa Omar"
}
}Common Errors
{
"success": false,
"message": "The transaction has already been completed",
"statusCode": 400,
"data": null
}{
"success": false,
"message": "Invalid or Wrong OTP",
"statusCode": 400,
"data": null
}{
"success": false,
"message": "OTP has expired, please request a new one",
"statusCode": 400,
"data": null
}{
"success": false,
"message": "The transaction was not found",
"statusCode": 404,
"data": null
}6) Authentication Error Example (401)
401 from HMAC/auth filters returns ProblemDetails style:{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid signature"
}7) Error Codes
| HTTP Code | Error Type | Description | Action Required |
|---|---|---|---|
| 400 | Validation / Business Rule Error | Invalid request, insufficient funds, OTP or state errors | Fix request/OTP/state and retry |
| 401 | Authentication Failed | Invalid Basic Auth, signature, timestamp, or replay validation | Verify credentials, signature payload, and timestamp |
| 404 | Not Found | Wallet, bank wallet, or transaction not found | Verify identifiers |
| 500 | Internal Server Error | Unrecoverable server error | Retry later and contact support if persistent |
8) cURL Example (Inquiry)
9) cURL Example (Initiate)
10) cURL Example (Complete)