Skip to main content
Before you start integrating, it’s important to understand these core concepts.

​
Authentication & Security

Nomad Pay uses an asymmetric Ed25519 key pair model for all API communication to ensure maximum security and non-repudiation.

​
API Requests (You -> Nomad Pay)

  • Signing: You sign the request using your Secret Key (Private Key).
  • Verification: We verify using your Public Key (sent in the x-api-key header).

​
Webhooks (Nomad Pay -> You)

  • Signing: We sign the webhook payload using the Secret Key associated with your account’s latest active API Key.
  • Identification: We include the corresponding Public Key in the x-api-key header of the webhook request.
  • Verification: You use the Public Key provided in the header to verify the signature.

​
Anti-Replay

  • nonce: Every request must include a unique, strictly increasing integer (typically a Unix timestamp in milliseconds) to prevent replay attacks.

​
HTTPS

  • All communication must be over HTTPS. Unencrypted HTTP requests will be rejected.

​
Non-Custodial Settlement

Nomad Pay operates on a non-custodial model. This affects how funds move and how you should track them.
  • Direct Transfer: When a customer pays, the funds (minus the platform fee) are routed directly from the customer’s wallet to your configured Receiving Address.
  • No Platform Balance: We do not hold your funds. You will not see a “Withdraw” button in the dashboard because the money is already in your wallet.
  • Automatic Conversion: If you configured a Default Token (e.g., USDC), incoming payments in other tokens (e.g., ETH) are automatically swapped before reaching your wallet.

​
Payment Lifecycle

Understanding the status of a payment is crucial for your order fulfillment logic.
  • Pending:
    • The payment intent has been created. The customer has not yet paid, or the transaction is broadcasting on the blockchain.
  • Success:
    • The transaction has been confirmed on the blockchain and funds have successfully settled to your wallet. You should ship goods/services only upon receiving this status via Webhook.
  • Failed:
    • The payment failed (e.g., insufficient funds, transaction reverted, or timeout).
  • Expired:
    • The payment link/session has expired (default 1 hour) without a completed payment.

​
Standard Responses

All API responses use a unified JSON structure. Success Response (200 OK): 
{
  "code": 0,
  "message": "success",
  "data": { ... } // Resource data
}
Error Response (4xx/5xx): 
{
  "code": 1001,      // Specific error code
  "message": "Invalid parameter: amount" // Human-readable message
}
Common Error Codes:
  • 1001: Parameter validation failed
  • 1002: Authentication failed
  • 1003: Invalid signature
  • 1004: Nonce replay rejected
  • 2001: Internal server error

​
Pagination

List endpoints (like GET /v1/transactions) support pagination via query parameters.
  • Request Parameters:
    • page: The page number (default: 1).
    • limit: Number of items per page (default: 20, max: 100).
  • Response Structure: 
    {
  "code": 0,
  "data": {
    "list": [ ... ],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 20
    }
  }
}

​
Rate Limiting

To ensure platform stability, API requests are rate-limited.
  • Standard Limit: 100 requests per minute per IP address.
  • Headers: Response headers X-RateLimit-Limit and X-RateLimit-Remaining indicate your current usage.
  • 429 Too Many Requests: If you exceed the limit, you will receive this HTTP status. Please implement a retry logic with exponential backoff.