Create Payment

Create payment requests to accept cryptocurrency payments from your customers. Each payment generates a unique checkout URL where customers complete their transactions.

Payment Flow Overview

sequenceDiagram
    participant M as Merchant Server
    participant API as Payment Gateway API
    participant C as Customer
    participant B as Blockchain

    M->>API: Create Payment Request
    API->>M: Return Checkout URL
    M->>C: Redirect to Checkout
    C->>API: Complete Payment
    API->>B: Monitor Transaction
    B->>API: Confirm Payment
    API->>M: Webhook Notification

Create Payment Endpoint

Request

POST /api/payment/checkout
Authorization: Bearer YOUR_CLIENT_TOKEN
Content-Type: application/json

Authentication: Requires a Client Token with the payments.create scope.

Request Body

{
  "amount": 10000,
  "currencyCode": "USD",
  "reference": "ORDER-123",
  "referenceLabel": "Order #123",
  "clientId": "your_client_id",
  "redirectUrl": "https://yoursite.com/payment/success",
  "expiresAt": "2026-03-15T12:00:00Z"
}

Request Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in cents (e.g., 10000 = $100.00)
`currencyCode`	string	Yes	Invoice currency: fiat (USD, EUR, CHF) or a major coin (USDT, USDC, BTC, ETH). List: `GET /wallet/invoice-currencies`
`reference`	string	Yes	Your internal reference ID
`referenceLabel`	string	Yes	Human-readable reference label
`clientId`	string	Yes	Your application's Client ID
`redirectUrl`	string	No	URL to redirect after successful payment
`expiresAt`	string	No	ISO 8601 expiration datetime (default: 1 year)

You can also use siteId as an alias for clientId.

DuoPay Parameters

Optional. Let the customer cover part of this invoice with a secondary token — see DuoPay. Omit these and the payment is single-currency.

Parameter	Type	Required	Description
`duoPayEnabled`	boolean	No	Offer DuoPay on this payment
`duoPaySecondaries`	array	No	Tokens the customer may apply. Empty array disables DuoPay
`duoPaySecondaries[].currencyCode`	string	Yes*	Token code, e.g. `GLAM`
`duoPaySecondaries[].capType`	string	Yes*	`percent` or `fixed`
`duoPaySecondaries[].capValue`	integer	Yes*	Percentage, or amount in the invoice currency's smallest unit

* Required for each entry in the array — a token you offer must always carry a cap.

{
  "amount": 10000,
  "currencyCode": "USD",
  "reference": "ORDER-123",
  "referenceLabel": "Order #123",
  "clientId": "your_client_id",
  "duoPayEnabled": true,
  "duoPaySecondaries": [
    { "currencyCode": "GLAM", "capType": "percent", "capValue": 5 }
  ]
}

On a 10000 (100.00 USD) invoice this lets the customer put up to 5.00 USD worth of GLAM towards it and pay the rest in the currency they choose.

Validation: every entry needs both capType and capValue. A percent cap may not exceed 100, a fixed cap may not exceed amount, and the combined caps across all tokens may not exceed 80% of amount.

Success Response

{
  "data": {
    "checkoutUrl": "https://yourdomain.com/checkout/550e8400-...?expires=1742044800&signature=abc123..."
  }
}

The checkoutUrl is a signed URL that includes:

The payment ID in the path
An expires timestamp
An HMAC-SHA256 signature to prevent tampering

Redirect your customer to this URL to complete payment.

Code Examples

const axios = require('axios');

async function createPayment(orderData) {
  const response = await axios.post(
    'https://api.yourdomain.com/api/payment/checkout',
    {
      amount: orderData.total * 100, // Convert to cents
      currencyCode: 'USD',
      reference: orderData.id,
      referenceLabel: `Order #${orderData.id}`,
      clientId: process.env.PAYMENT_CLIENT_ID,
      redirectUrl: `https://mystore.com/orders/${orderData.id}/success`
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.PAYMENT_CLIENT_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data.data.checkoutUrl;
}

// Redirect customer to checkout
const checkoutUrl = await createPayment({ id: 'ORDER-123', total: 100.00 });
import requests
import os

def create_payment(order_data):
    response = requests.post(
        'https://api.yourdomain.com/api/payment/checkout',
        json={
            'amount': int(order_data['total'] * 100),
            'currencyCode': 'USD',
            'reference': order_data['id'],
            'referenceLabel': f"Order #{order_data['id']}",
            'clientId': os.environ['PAYMENT_CLIENT_ID'],
            'redirectUrl': f"https://mystore.com/orders/{order_data['id']}/success"
        },
        headers={
            'Authorization': f"Bearer {os.environ['PAYMENT_CLIENT_TOKEN']}",
            'Content-Type': 'application/json'
        }
    )

    response.raise_for_status()
    return response.json()['data']['checkoutUrl']
<?php
function createPayment($orderData) {
    $ch = curl_init('https://api.yourdomain.com/api/payment/checkout');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode([
            'amount' => $orderData['total'] * 100,
            'currencyCode' => 'USD',
            'reference' => $orderData['id'],
            'referenceLabel' => 'Order #' . $orderData['id'],
            'clientId' => $_ENV['PAYMENT_CLIENT_ID'],
            'redirectUrl' => "https://mystore.com/orders/{$orderData['id']}/success"
        ]),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $_ENV['PAYMENT_CLIENT_TOKEN'],
            'Content-Type: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    return $data['data']['checkoutUrl'];
}

// Redirect customer
$checkoutUrl = createPayment(['id' => 'ORDER-123', 'total' => 100.00]);
header('Location: ' . $checkoutUrl);
exit;
curl -X POST https://api.yourdomain.com/api/payment/checkout \
  -H "Authorization: Bearer YOUR_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currencyCode": "USD",
    "reference": "ORDER-123",
    "referenceLabel": "Order #123",
    "clientId": "your_client_id",
    "redirectUrl": "https://yoursite.com/success"
  }'

Payment Expiration

Control how long the checkout link remains valid using the expiresAt parameter:

{
  "expiresAt": "2026-03-15T12:00:00Z"
}

If not specified, the checkout link defaults to a 1-year expiration.

Best Practices

Use unique references — each payment should have a unique reference to prevent duplicates
Amount in cents — always send amounts in the smallest currency unit to avoid decimal issues
Store the checkout URL — save the returned URL in case you need to redirect the customer again
Set up webhooks — always verify payment completion via webhooks rather than relying on redirects
Keep tokens server-side — never expose your Client Token in client-side code