Merchant API v1 · OpenAPI 3.1

Build payments that feel native to your product.

Create tenant-isolated card and crypto orders, control network payout wallets, discover payment methods, and reconcile settlement through one server API.

Explore API reference Copy URL & open Postman Download collection

Authenticate

Create a live merchant key and send it in X-API-Key. The key decides the tenant—never an email in the request.

Create an order

POST /v1/orders creates an UNPAID order and returns your Paymegate checkout URL. No transaction exists yet.

Reconcile settlement

A verified payment callback marks the order PAID, creates its transaction, and triggers your merchant webhook.

Your first order

Amounts are exact decimal strings. The checkout URL in the response is the only URL you share with the customer.

Keys stay server-side.

Wallet overrides are opt-in per merchant.

curl --request POST "https://api.paymegate.com/v1/orders" \
  --header "X-API-Key: $PAYMEGATE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "invoice_2026_0042",
    "amount": "20.00",
    "currency": "USD",
    "paymentMethodsKeys": ["*"],
    "customer": {
      "email": "[email protected]",
      "fullName": "Example Customer"
    },
    "metadata": {
      "cartId": "cart_42",
      "workspaceId": "workspace_7"
    }
  }'

Crypto checkout, hosted end to end

You create the same order object and share the same platform-owned checkout URL. Paymegate handles compatible asset selection, fiat conversion, payment-address provisioning, QR rendering, expiry, and settlement verification.

Network-aware payouts

Customers see only assets supported by Paymegate whose payout network you configured.

Address and QR per attempt

Each selected asset receives a dedicated address, exact crypto amount, and scannable payment URI.

30-minute quote

The converted amount and address are locked for 30 minutes, then the customer can create a fresh attempt.

Verified settlement

Checkout checks status every 10 minutes and on demand; a transaction appears only after verification.

1. Enable crypto and configure payout networks

curl --request PUT "https://api.paymegate.com/v1/wallet" \
  --header "X-API-Key: $PAYMEGATE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "includeCrypto": true,
    "cryptoWallets": {
      "evm": "0x2222222222222222222222222222222222222222",
      "btc": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
      "solana": "9kYzptsjoTjNjaTmTWPqWGLcVjsfRcygKGHYwPUzLX36",
      "trc20": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8"
    }
  }'

2. Create an order with paymentMethodsKeys: ["crypto"]

curl --request POST "https://api.paymegate.com/v1/orders" \
  --header "X-API-Key: $PAYMEGATE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": "20.00",
    "currency": "USD",
    "paymentMethodsKeys": ["crypto"],
    "customer": {
      "email": "[email protected]",
      "fullName": "Example Customer"
    },
    "metadata": {
      "cartId": "cart_123"
    }
  }'

The order response returns checkoutUrl. Redirect the customer there—never build provider URLs or expose merchant API keys in browser code.

Settlement correlation

A small event with what matters.

After verified settlement, Paymegate sends one signed order.paid event with the order and transaction IDs, amount, customer email, correlation fields, and payment time.

externalId

Put your invoice, cart, subscription, or workflow ID here. It may be null or duplicated; Paymegate returns it unchanged so you can locate your own record immediately.

metadata

Attach structured JSON context such as workspace IDs, cart IDs, or fulfillment attributes. The same object comes back unchanged in the webhook. Never put secrets or card data in it.

POST to your webhook URL

order.paid payload

{
  "id": "f15068cf-c0ea-4b67-91bb-4c45ec6eac88",
  "type": "order.paid",
  "createdAt": "2026-07-23T12:00:00.000Z",
  "orderUUID": "9cb50d55-9e02-4fc0-a824-277ac39b4144",
  "transactionUUID": "30569045-9e69-41cb-9083-8ac5e3d76a5e",
  "transactionRef": "provider_transaction_reference",
  "status": "PAID",
  "amount": "20.00",
  "currency": "USD",
  "customerEmail": "[email protected]",
  "externalId": "invoice_2026_0042",
  "metadata": {
    "cartId": "cart_42",
    "workspaceId": "workspace_7"
  },
  "paidAt": "2026-07-23T12:00:00.000Z"
}

OpenAPI reference

Merchant API endpoints

Six server-to-server operations. Every request uses your merchant API key—never a JWT.

Raw OpenAPI

POST/v1/orders

Create an order

Creates an UNPAID order and returns the Paymegate checkout URL you share with the customer. externalId is your optional invoice/workflow correlation label; metadata carries structured context. Both return unchanged in the later order.paid webhook. Use ["crypto"] for crypto-only checkout, combine it with provider keys, or use ["all"] to snapshot every available method.

Scope: orders:create

Authentication header

X-API-Key: $PAYMEGATE_API_KEY

Request

curl --request POST "https://api.paymegate.com/v1/orders" \
  --header "X-API-Key: $PAYMEGATE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "invoice_2026_0042",
    "amount": "20.00",
    "currency": "USD",
    "paymentMethodsKeys": ["*"],
    "customer": {
      "email": "[email protected]",
      "fullName": "Example Customer"
    },
    "metadata": {
      "cartId": "cart_42",
      "workspaceId": "workspace_7"
    }
  }'

Example response

{
  "success": true,
  "data": {
    "orderUUID": "9cb50d55-9e02-4fc0-a824-277ac39b4144",
    "externalId": "invoice_2026_0042",
    "status": "UNPAID",
    "amount": "20.00",
    "currency": "USD",
    "metadata": {
      "cartId": "cart_42",
      "workspaceId": "workspace_7"
    },
    "paymentMethodsKeys": ["stripe", "coinbase", "paypal"],
    "checkoutUrl": "https://www.paymegate.com/pay/9cb50d55-9e02-4fc0-a824-277ac39b4144"
  }
}