Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nomadpay.io/llms.txt

Use this file to discover all available pages before exploring further.

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

HeaderRequiredDescription
Content-TypeYesMust be application/json.
x-api-keyYesYour Public Key obtained from the merchant dashboard.
x-signatureYesThe Ed25519 signature of the request body, Hex encoded.

​
Request Body

The request body must be a JSON object.
FieldTypeRequiredDescription
secret_idstringYesYour unique order ID from your own system.
nonceint64YesA unique, increasing number, like a millisecond timestamp.
amountfloat64YesThe payment amount.
currencystringYesThe pricing currency code (e.g., USD, EUR, HKD).
callback_urlstringYesThe URL the user will be redirected to after a successful payment.
forward_urlstringYesThe URL the user is redirected to if they cancel or the payment fails.
senderstringNoAn identifier for the payer (e.g., your user’s ID).
recieverstringNoAn identifier for the receiver (e.g., your merchant’s ID).
meta_datamap[string]anyNoAny 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:
  1. Serialize the Body: Convert your JSON request body into a raw string, with no extra spaces or line breaks.
  2. Sign the String: Use your Ed25519 private key (from your hex seed) to sign the byte array of the string from step 1.
  3. Encode the Signature: Convert the resulting signature into a Hex-encoded string.
  4. 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