API Reference

This is the API reference for integrating Nomad Pay’s “API Order” method.

Base URL

All API requests should be sent to: https://api.nomadpay.io

Create a Payment

This endpoint is used to initiate a payment request and generate a payment URL for the user.

Endpoint: POST /v1/payments
Method: POST
Content-Type: application/json
Signature Algorithm: Ed25519

Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.
`x-api-key`	Yes	Your Public Key obtained from the merchant dashboard.
`x-signature`	Yes	The Ed25519 signature of the request body, Hex encoded.

Request Body

The request body must be a JSON object.

Field	Type	Required	Description
`secret_id`	`string`	Yes	Your unique order ID from your own system.
`nonce`	`int64`	Yes	A unique, increasing number, like a millisecond timestamp.
`amount`	`float64`	Yes	The payment amount.
`currency`	`string`	Yes	The pricing currency code (e.g., `USD`, `EUR`, `HKD`).
`callback_url`	`string`	Yes	The URL the user will be redirected to after a successful payment.
`forward_url`	`string`	Yes	The URL the user is redirected to if they cancel or the payment fails.
`sender`	`string`	No	An identifier for the payer (e.g., your user’s ID).
`reciever`	`string`	No	An identifier for the receiver (e.g., your merchant’s ID).
`meta_data`	`map[string]any`	No	Any additional metadata you want to associate with the order.

Example Request Body:

{
  "secret_id": "your-order-id-123",
  "nonce": 1678886400123,
  "amount": 100.50,
  "currency": "USD",
  "sender": "user_775",
  "reciever": "merchant_A",
  "callback_url": "[https://yourdomain.com/payment-success](https://yourdomain.com/payment-success)",
  "forward_url": "[https://yourdomain.com/payment-failure](https://yourdomain.com/payment-failure)",
  "meta_data": {
    "order_id": "20231101123456",
    "description": "VIP Subscription"
  }
}

Generating the Signature

To create the x-signature, you must sign the raw JSON request body using your Ed25519 Secret Key (Private Key). Process:

Serialize the Body: Convert your JSON request body into a raw string, with no extra spaces or line breaks.
Sign the String: Use your Ed25519 private key (from your hex seed) to sign the byte array of the string from step 1.
Encode the Signature: Convert the resulting signature into a Hex-encoded string.
Set the Header: Place this Hex string into the x-signature header.

Example (Go):

import (
	"crypto/ed25519"
	"encoding/hex"
	"encoding/json"
	"time"
)

// Sign generates an Ed25519 signature for the message.
// seedHex is your 64-character hex-encoded private key seed.
func Sign(seedHex string, message []byte) (string, error) {
	seed, err := hex.DecodeString(seedHex)
	if err != nil {
		return "", err
	}
	privateKey := ed25519.NewKeyFromSeed(seed)
	signature := ed25519.Sign(privateKey, message)
	return hex.EncodeToString(signature), nil
}

func main() {
	// 1. Your Ed25519 private key seed (64 hex characters)
	seed := "your_ed25519_private_key_hex_string_keep_this_secret"
    
	// 2. Construct the exact same JSON body
	message, _ := json.Marshal(map[string]interface{}{
        "secret_id":    "your-order-id-123",
        "nonce":        time.Now().UnixMilli(),
        "amount":       100.50,
        "currency":     "USD",
		"sender":       "user_775",
        "reciever":     "merchant_A",
        "callback_url": "[https://yourdomain.com/payment-success](https://yourdomain.com/payment-success)",
		"forward_url":  "[https://yourdomain.com/payment-failure](https://yourdomain.com/payment-failure)",
		"meta_data": map[string]interface{}{
	     "order_id": "20231101123456",
		 "description": "VIP Subscription",
	    },
	})

	// 3. Sign the message
	signature, err := Sign(seed, message)
	if err != nil {
        panic(err)
	}

	// 4. Use this signature in your x-signature header
	// fmt.Println(signature)
}

Responses

Success Response

Code: HTTP 200 OK
Body:

{
  "code": 0,
  "message": "success",
  "data": {
    "payment_id": "pay_123456789",
    "payment_url": "[https://pay.nomadpay.io/checkout/pay_123456789](https://pay.nomadpay.io/checkout/pay_123456789)"
  }
}

Action: You must redirect your user to the payment_url provided.

Error Response

Code: HTTP 4xx/5xx
Body:

{
  "code": 1002,
  "message": "API key is required"
}

Error Codes:
- 1001: Parameter validation failed
- 1002: API key is required
- 1003: Invalid signature
- 1004: Nonce has already been used
- 2001: Internal server error

Welcome

Merchant User Guide

Developer Documentation

API Reference

Base URL

Create a Payment

Request Headers

Request Body

Generating the Signature

Responses

​Base URL

​Create a Payment

​Request Headers

​Request Body

​Generating the Signature

​Responses

Base URL

Create a Payment

Request Headers

Request Body

Generating the Signature

Responses