#ForexPay OpenAPI

Version 1 · Last updated 2026-10-21

This is the integration guide for ForexPay merchants. Everything is plain JSON over HTTPS, authenticated with an API key and an HMAC-SHA256 signature. There is no SDK to install.

#1. Credentials

When your account is enabled for the API you receive two values:

Keep the secret on your server. It is never transmitted, not even hashed. If it leaks, ask support to rotate it; the old secret stops working immediately.

#2. Signing a request

Every request carries four headers:

X-FX-Key:       fx_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-FX-Timestamp: 1792594663
X-FX-Nonce:     7f3a9c2e5b1d4a80
X-FX-Sign:      <64 lowercase hex characters>
Content-Type:   application/json

The signature is an HMAC-SHA256 over five lines joined with \n:

sign = HMAC-SHA256(secret,
    METHOD + "\n" +
    PATH + "\n" +
    TIMESTAMP + "\n" +
    NONCE + "\n" +
    SHA256(BODY)
)

• METHOD is uppercase, always POST.
• PATH is the path only, e.g. /v1/payin/create — no host, no query string.
• SHA256(BODY) is the lowercase hex digest of the exact bytes you send. Sign the serialized string, then send that same string — do not re-serialize in between. For an empty body, use the digest of the empty string.

#Worked example

secret    = test-secret
method    = POST
path      = /v1/payin/create
timestamp = 1792594663
nonce     = 7f3a9c2e
body      = {"reference":"A1"}

SHA256(body) = 233abea419905ee5886f9637d90858d7f8fa6841eeb5f06ca8639f6f8480a6a4
signing string:
    POST\n/v1/payin/create\n1792594663\n7f3a9c2e\n233abea4…a6a4
sign      = 79b11f7a065d6bec2c5d303eb759c5b76c7b0cf2000b1bae908bd78f80b29a58

Use these values to check your implementation before you send a live request.

#Example code

Node.js

import crypto from 'node:crypto';

const BASE_URL = 'https://openapi.forexpay.app';
const API_KEY = process.env.FX_API_KEY;
const API_SECRET = process.env.FX_API_SECRET;

async function callForexPay(path, payload) {
  const body = JSON.stringify(payload);
  const timestamp = Math.floor(Date.now() / 1000);
  const nonce = crypto.randomBytes(8).toString('hex');
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const sign = crypto
    .createHmac('sha256', API_SECRET)
    .update(['POST', path, timestamp, nonce, bodyHash].join('\n'))
    .digest('hex');

  const response = await fetch(BASE_URL + path, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-fx-key': API_KEY,
      'x-fx-timestamp': String(timestamp),
      'x-fx-nonce': nonce,
      'x-fx-sign': sign,
    },
    body, // the same string that was hashed
  });

  const result = await response.json();
  if (!result.ok) {
    throw new Error(`${result.error.code}: ${result.error.message} (${result.request_id})`);
  }
  return result.data;
}

const order = await callForexPay('/v1/payin/create', {
  reference: 'ORDER-20261021-0001',
  amount: 100.5,
  currency: 'CNY',
  customer: { name: 'Zhang San' },
});
console.log(order.checkout_url);

PHP

<?php
function call_forexpay(string $path, array $payload): array {
    $base   = 'https://openapi.forexpay.app';
    $key    = getenv('FX_API_KEY');
    $secret = getenv('FX_API_SECRET');

    $body      = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $nonce     = bin2hex(random_bytes(8));
    $signing   = implode("\n", ['POST', $path, $timestamp, $nonce, hash('sha256', $body)]);
    $sign      = hash_hmac('sha256', $signing, $secret);

    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-FX-Key: ' . $key,
            'X-FX-Timestamp: ' . $timestamp,
            'X-FX-Nonce: ' . $nonce,
            'X-FX-Sign: ' . $sign,
        ],
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);

    $result = json_decode($raw, true);
    if (empty($result['ok'])) {
        throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
    }
    return $result['data'];
}

Python

import hashlib, hmac, json, os, secrets, time
import requests

BASE_URL = "https://openapi.forexpay.app"

def call_forexpay(path: str, payload: dict) -> dict:
    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(8)
    signing = "\n".join(["POST", path, timestamp, nonce,
                         hashlib.sha256(body.encode()).hexdigest()])
    sign = hmac.new(os.environ["FX_API_SECRET"].encode(), signing.encode(),
                    hashlib.sha256).hexdigest()

    response = requests.post(
        BASE_URL + path,
        data=body.encode(),
        headers={
            "Content-Type": "application/json",
            "X-FX-Key": os.environ["FX_API_KEY"],
            "X-FX-Timestamp": timestamp,
            "X-FX-Nonce": nonce,
            "X-FX-Sign": sign,
        },
        timeout=35,
    )
    result = response.json()
    if not result.get("ok"):
        raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
    return result["data"]

#3. Response format

Success — HTTP 200:

{
  "ok": true,
  "request_id": "req_8f2a1c7d4e5b6a9c0d1e2f3a",
  "data": { }
}

Failure — HTTP 4xx or 5xx:

{
  "ok": false,
  "request_id": "req_8f2a1c7d4e5b6a9c0d1e2f3a",
  "error": { "code": "INVALID_AMOUNT", "message": "amount: at most 2 decimal places" }
}

Always branch on ok, not on the HTTP status. Log request_id on every call — it is the only thing support needs to find your request.

#4. Endpoints

reference is your order number. It must be unique across both collection and payout orders on your account — reusing one is rejected with DUPLICATE_REFERENCE, and the query endpoints look orders up by it. Allowed characters: A-Z a-z 0-9 _ . -, 1–64 characters.

#4.1 POST /v1/payin/create

Creates a collection order and returns a hosted checkout URL to send your customer to.

Request

Response

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "reference": "ORDER-20261021-0001",
    "checkout_url": "https://pay.forexpay.app/#/step1?orderId=…&checkoutToken=…"
  }
}

#4.2 POST /v1/payin/create-raw

Same request as /v1/payin/create, but instead of a checkout URL you get the payment accounts to render yourself. You are then responsible for calling /v1/payin/confirm when the customer tells you they have paid.

Response

#4.3 POST /v1/payin/query

Request: reference (string, required).

Response

#4.4 POST /v1/payin/cancel

Cancels a collection order that is still pending. Anything else returns ORDER_STATE_INVALID.

Request: reference (string, required). Response: reference, status ("cancelled").

#4.5 POST /v1/payin/confirm

Only for self-hosted checkout (/v1/payin/create-raw). Tells us the customer says they paid into a specific account; the order moves to verifying until we confirm the money arrived.

Request

Response: reference, status ("verifying").

#4.6 POST /v1/payin/methods

Request: currency (string, optional — omit for every currency enabled on your account).

Response

Call this before building a payout form: it tells you exactly which payee.* fields a channel requires.

#4.7 POST /v1/payout/create

Request

Which payee.* fields are required depends on the channel; PAYEE_INFO_INVALID tells you the set was wrong. The amount plus fees is held from your balance when the order is accepted; INSUFFICIENT_BALANCE means top up first.

Response: reference, status ("pending").

The order number is not available at creation time. Poll /v1/payout/query with your reference, or wait for the webhook.

#4.8 POST /v1/payout/query

Request: reference (string, required).

Response: same shape as /v1/payin/query minus settled_at, with payout statuses (§6). Collection and payout statuses are different sets — use the endpoint that matches the order you created.

#4.9 POST /v1/account/balance

Request: no fields (send {}).

Response

#4.10 POST /v1/account/statements

Request

Response

There is no pagination: narrow the window instead.

#4.11 POST /v1/rates/payin

Request: currency (string, required). Response: currency, rate (number).

A rate is only quoted when a channel can actually take an order; otherwise RATE_UNAVAILABLE. Rates are indicative — the rate on the order is fixed when the order is created.

#4.12 POST /v1/rates/payout

Request: currency (string, required), expedited (boolean, optional). Response: currency, expedited, rate.

#5. Webhooks

We POST a JSON event to your webhook URL when an order reaches a final state.

POST https://your-server.example.com/webhooks/forexpay
X-FX-Event:     payin.succeeded
X-FX-Timestamp: 1792594663
X-FX-Sign:      <64 lowercase hex characters>
Content-Type:   application/json

{
  "event": "payin.succeeded",
  "sent_at": "2026-10-21T07:05:00.000Z",
  "data": {
    "reference": "ORDER-20261021-0001",
    "order_no": "PI1234567890123456",
    "status": "success",
    "amount": 100.5,
    "settled_usdt": 13.9,
    "paid_at": "2026-10-21T07:04:05.000Z"
  }
}

#Verifying the signature

The webhook signature is not the same formula as the request signature — it has no method or path, so a reverse proxy rewriting your path cannot break it:

X-FX-Sign = HMAC-SHA256(secret, X-FX-Timestamp + "\n" + SHA256(raw_body))

import crypto from 'node:crypto';

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-fx-timestamp'];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}\n${crypto.createHash('sha256').update(rawBody).digest('hex')}`)
    .digest('hex');
  const received = headers['x-fx-sign'] ?? '';
  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  );
}

Verify against the raw request body, before any JSON parsing or re-serialization.

#Responding

Reply HTTP 200 with the body ok. Anything else — another status, another body, a timeout — counts as a failure and we retry.

#Retries

A failed delivery is retried up to 5 times with a growing delay (roughly 3, 9, 27, 81 and 243 minutes). Treat webhooks as at-least-once: the same event can arrive twice, so key your handler on reference and make it idempotent. Always confirm against /v1/payin/query or /v1/payout/query before releasing goods — the query endpoints are the source of truth.

Our requests time out after 10 seconds. Acknowledge first, process afterwards.

#Where events are sent

By default events go to the webhook URL registered on your account — one for collections and, optionally, a separate one for payouts. Ask support to change them.

You may also override it per order with notify_url, subject to the size limit in §7.

#6. Statuses

Collection orders (/v1/payin/query, payin.* events)

Payout orders (/v1/payout/query, payout.* events)

is_final in the query responses is a convenience for exactly these columns. Treat any status you do not recognise as non-final and keep polling.

#7. Field lengths and the request size budget

Each request is re-encrypted before it reaches our core, and that encryption takes a fixed maximum of 501 bytes of JSON. All the per-field limits in §4 fit comfortably inside it, but the total matters. Real measurements:

A per-order notify_url costs about 129 bytes of that budget. So:

• notify_url works for normal collection and payout orders.
• notify_url does not fit an international wire payout with bank and beneficiary addresses. Use the webhook URL registered on your account for those.

If a request does not fit you get a clear error before anything is created:

{
  "ok": false,
  "request_id": "req_…",
  "error": {
    "code": "NOTIFY_URL_TOO_LONG",
    "message": "The request with notify_url needs 509 bytes but only 501 fit. Drop notify_url (the webhook registered on your account is used instead) or shorten the optional fields."
  }
}

REQUEST_TOO_LARGE is the same situation without notify_url: shorten the optional text fields (return_url, addresses, remarks).

#8. Errors

error.code is a stable string — branch on it. error.message is for humans and may be reworded at any time.

#Retrying safely

Reusing the same reference is always safe: a duplicate gets DUPLICATE_REFERENCE rather than a second order. So after a timeout or a 5xx, either retry with the same reference or query it — never create a new one.

#9. Going live checklist

• Reproduce the §2 worked example exactly.
• Sandbox: create a collection order, pay it, receive and verify the webhook.
• Your webhook replies ok and is idempotent (send it the same event twice).
• Your server clock is NTP-synced.
• You store reference, order_no and request_id for every call.
• You poll /v1/payin/query as a backstop instead of trusting webhooks alone.
• You never create a second order for a failed or timed-out request.
• Secrets are in environment variables or a secret manager, not in source control.