Integration Guide

1) Getting Started

Overview

This API allows partner banks to deposit money into NilPay wallets using a two-phase flow:

POST /v1/transactions/custody-bank/deposit/initiate

POST /v1/transactions/custody-bank/deposit/complete

Base URL

https://api.dev.pynil.com

Version Prefix

All routes start with /v1.

2) Authentication and Security

All requests require:

Authorization: Basic <BASE64(username:password)>

X-Signature: <HMAC_SHA256_UPPERCASE_HEX>

X-Timestamp: <UNIX_TIMESTAMP_SECONDS>

Content-Type: application/json

HMAC Payload (Current Implementation)

Use this exact payload format:

HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + UNIX_TIMESTAMP

Example request path:
/v1/transactions/custody-bank/deposit/initiate

Security Rules

Timestamp tolerance: 5 minutes.

Replay protection: request uniqueness is validated using timestamp + signature.

Signature comparison is case-insensitive, but use uppercase hex in clients.

HMAC secret is resolved from authenticated bank user (with optional system fallback).

3) Endpoint: Initiate Deposit

URL

POST /v1/transactions/custody-bank/deposit/initiate

Request Body

{
  "walletNumber": "101000030",
  "amount": 500.0,
  "timestamp": "2025-08-03",
  "notes": "Layla deposits money"
}

Request Notes

walletNumber, amount, timestamp are required.

Success Response (200)

{
  "success": true,
  "message": "Success.",
  "statusCode": 200,
  "data": {
    "account": {
      "branchCode": "MAIN",
      "bban": "12000010000101000030",
      "currencyCode": "SDG",
      "walletName": "Layla ismaeil",
      "status": "Active"
    },
    "charges": [
      {
        "name": "Custody Deposit",
        "amount": 20.0
      }
    ],
    "totalFees": 20.0
  }
}

Error Responses

400 validation response envelope (success/message/statusCode/data)

401 RFC 7807 ProblemDetails (e.g., missing signature, invalid timestamp, invalid signature)

404 envelope error (wallet/depositor/shadow not found)

500 envelope error

4) Endpoint: Complete Deposit

URL

POST /v1/transactions/custody-bank/deposit/complete

Request Body

{
  "walletNumber": "101000030",
  "currency": "SDG",
  "amount": 500.0,
  "depositor": {
    "fullName": "Layla ismaeil",
    "mobile": "0918003874",
    "idNumber": "1001-1090-180",
    "address": "Khartoum - sudan"
  },
  "BankTranID": "41128",
  "timestamp": "2025-08-03",
  "notes": "Layla deposits money"
}

Request Notes

depositor object is optional.

BankTranID is required and used for idempotency.

Idempotency Behavior

If the same BankTranID was already processed successfully, API returns the existing nilpayTranRef.

Success Response (200)

{
  "success": true,
  "message": "Success.",
  "statusCode": 200,
  "data": {
    "nilpayTranRef": 6
  }
}

Error Responses

Same categories as initiate endpoint.

5) ProblemDetails Example (401)

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid signature"
}

6) Error Codes

HTTP Code	Error Type	Description	Action Required
400	Validation Error	Invalid request parameters	Fix request payload and retry
401	Authentication Failed	Basic Auth, signature, timestamp, or replay validation failure	Verify credentials, signature payload, and timestamp
404	Account Not Found	Wallet/depositor/shadow account not found or inactive	Verify wallet and configuration
500	Internal Server Error	Unrecoverable server error	Retry later, contact support if persistent

Integration Guide

1) Getting Started

Overview

Base URL

Version Prefix

2) Authentication and Security

HMAC Payload (Current Implementation)

Security Rules

3) Endpoint: Initiate Deposit

URL

Request Body

Request Notes

Success Response (200)

Error Responses

4) Endpoint: Complete Deposit

URL

Request Body

Request Notes

Idempotency Behavior

Success Response (200)

Error Responses

5) ProblemDetails Example (401)

6) Error Codes

7) cURL Example (Initiate)

8) cURL Example (Complete)

Integration Guide

1) Getting Started#

Overview#

Base URL#

Version Prefix#

2) Authentication and Security#

HMAC Payload (Current Implementation)#

Security Rules#

3) Endpoint: Initiate Deposit#

URL#

Request Body#

Request Notes#

Success Response (200)#

Error Responses#

4) Endpoint: Complete Deposit#

URL#

Request Body#

Request Notes#

Idempotency Behavior#

Success Response (200)#

Error Responses#

5) ProblemDetails Example (401)#

6) Error Codes#

7) cURL Example (Initiate)#

8) cURL Example (Complete)#

1) Getting Started

Overview

Base URL

Version Prefix

2) Authentication and Security

HMAC Payload (Current Implementation)

Security Rules

3) Endpoint: Initiate Deposit

URL

Request Body

Request Notes

Success Response (200)

Error Responses

4) Endpoint: Complete Deposit

URL

Request Body

Request Notes

Idempotency Behavior

Success Response (200)

Error Responses

5) ProblemDetails Example (401)

6) Error Codes

7) cURL Example (Initiate)

8) cURL Example (Complete)