Integration Guide

1) Getting Started

Overview

This API allows an authenticated external party system to transfer funds to a NilPay wallet.

Flow:

POST /v1/transactions/external-party/transfer

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/external-party/transfer

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 integration user (with optional system fallback).

3) Endpoint: External Party Transfer To Wallet

URL

POST /v1/transactions/external-party/transfer

Request Body

{
  "receiverWalletNumber": 101000002,
  "amount": 250.00
}

Request Notes

receiverWalletNumber is required and must be greater than 0.

amount is required and must be greater than 0.

Success Response (200)

{
  "success": true,
  "message": "Transfer successful.",
  "statusCode": 200,
  "data": {
    "transactionId": "340-1",
    "reference": 340,
    "date": "2026-04-25T10:00:00Z",
    "direction": "Credit",
    "amount": 250.00,
    "description": "External party transfer"
  }
}

Error Responses

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

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

404 envelope error (wallet not found / account not available).

500 envelope error.

4) ProblemDetails Example (401)

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

5) 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	Receiver wallet not found or inactive	Verify wallet number and account status
500	Internal Server Error	Unrecoverable server error	Retry later, contact support if persistent

6) cURL Example

7) Notes

This endpoint is a single-step transfer flow (no initiate/complete split).

Keep your integration clock synchronized (NTP) to avoid timestamp validation failures.

Log reference and transactionId from successful responses for reconciliation.

Integration Guide

1) Getting Started#

Overview#

Base URL#

Version Prefix#

2) Authentication and Security#

HMAC Payload (Current Implementation)#

Security Rules#

3) Endpoint: External Party Transfer To Wallet#

URL#

Request Body#

Request Notes#

Success Response (200)#

Error Responses#

4) ProblemDetails Example (401)#

5) Error Codes#

6) cURL Example#

7) Notes#