> ## 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.

# 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:**

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