Payments API

Authentication

Send your secret API key on every /v1 request — as a bearer token or in the X-API-Key header. Keep it server-side; never ship it in client code.

CopyAuthorization: Bearer npk_YOUR_KEY
# or
X-API-Key: npk_YOUR_KEY

Environments & testing

Set environment on the create-link call. Use "sandbox" to route to a test processor — pay with Stripe test cards like 4242 4242 4242 4242 (any future expiry, any CVC); no real money moves. Use "production" (default) for live charges.

Quickstart

1. Create a payment link  →  2. redirect the customer to paymentUrl  →  3. confirm via polling or a webhook  →  4. refund if needed.

Copycurl -X POST https://payments.nxtpay.cc/v1/payment-links \
  -H "Authorization: Bearer npk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 2500,
    "currency": "USD",
    "description": "Pro plan",
    "successUrl": "https://your-site.com/thanks",
    "cancelUrl": "https://your-site.com/cart",
    "customer": { "email": "[email protected]", "fullName": "Avery Chen" },
    "partnerReference": "your-order-1042",
    "environment": "sandbox"
  }'

Copyconst res = await fetch("https://payments.nxtpay.cc/v1/payment-links", {
  method: "POST",
  headers: { Authorization: "Bearer npk_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    amountCents: 2500, currency: "USD", description: "Pro plan",
    successUrl: "https://your-site.com/thanks",
    cancelUrl: "https://your-site.com/cart",
    customer: { email: "[email protected]", fullName: "Avery Chen" },
    partnerReference: "your-order-1042", environment: "sandbox",
  }),
});
const link = await res.json();
// window.location = link.paymentUrl;

Copy$ch = curl_init("https://payments.nxtpay.cc/v1/payment-links");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer npk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "amountCents" => 2500, "currency" => "USD", "description" => "Pro plan",
    "successUrl" => "https://your-site.com/thanks",
    "cancelUrl" => "https://your-site.com/cart",
    "customer" => ["email" => "[email protected]", "fullName" => "Avery Chen"],
    "partnerReference" => "your-order-1042", "environment" => "sandbox",
  ]),
]);
$link = json_decode(curl_exec($ch), true);
// header("Location: " . $link["paymentUrl"]);

The response gives you orderId, statusToken, and routedVia.whitesiteId — store all three; you need them to poll or refund.

Create a payment link

Creates an order + hosted checkout session.

Response 200:

Copy{
  "orderId": "8b0e4f1a-2c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "orderNo": "ORD-202606-DW9PGM",
  "paymentId": "73571f33-e959-4705-9ab2-04c8ba2712a9",
  "paymentUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
  "expiresAt": "2026-06-17T11:38:14.000Z",
  "provider": "stripe",
  "statusToken": "eyJ...",
  "routedVia": { "whitesiteId": "32db38b1-...", "whitesiteName": "Acme Store",
                 "routeId": "...", "attemptNumber": 1, "capOverride": false }
}

expiresAt may be null — some providers' hosted links have no fixed server-side expiry.

Create a subscription

Same flow as a payment link, but the customer's card is vaulted and billed every interval. Redirect them to paymentUrl; renewals arrive as subscription.renewed webhooks. Send an Idempotency-Key header so a retry replays instead of creating a second subscription.

Copycurl -X POST https://payments.nxtpay.cc/v1/subscriptions \
  -H "Authorization: Bearer npk_YOUR_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-2026-06-24-abc" \
  -d '{ "amountCents": 2500, "interval": "month", "successUrl": "https://you/welcome",
        "cancelUrl": "https://you/cancel", "customer": { "email": "[email protected]" } }'

Response 200:

Copy{
  "orderId": "8b0e4f1a-...", "orderNo": "ORD-202606-DW9PGM",
  "paymentId": "73571f33-...", "paymentUrl": "https://checkout.stripe.com/c/pay/cs_...",
  "expiresAt": "2026-06-24T11:38:14.000Z", "provider": "stripe", "statusToken": "eyJ...",
  "mode": "subscription", "interval": "month",
  "subscriptionHandle": "OWIwZTRmMWEuLi4=",
  "routedVia": { "whitesiteId": "32db38b1-...", "attemptNumber": 1 }
}

Cancel a subscription

Stops future cycles. Cancellation is immediate — billing stops the moment the cancel succeeds; there is no cancel-at-period-end option. Already-settled charges are not refunded. Idempotent — replaying the cancel returns alreadyCanceled: true with the original canceledAt.

Copycurl -X POST https://payments.nxtpay.cc/v1/subscriptions/cancel \
  -H "Authorization: Bearer npk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "subscriptionHandle": "OWIwZTRmMWEuLi4=" }'

Response 200: { "ok": true, "subscriptionId": "sub_...", "canceledAt": "2026-07-08T09:14:02.000Z" }. Errors: 400 invalid_subscription_handle, 400 not_a_subscription, 404 subscription_not_found, 409 subscription_not_active_yet, 502 subscription_cancel_failed (transient — safe to retry).

Get a subscription

Current state of a subscription by its handle — the pull-based fallback if a subscription.canceled webhook is missed.

Copycurl "https://payments.nxtpay.cc/v1/subscriptions/OWIwZTRmMWEuLi4=" \
  -H "Authorization: Bearer npk_YOUR_KEY"

Response 200:

Copy{
  "orderId": "8b0e4f1a-...", "orderNo": "ORD-202606-DW9PGM",
  "subscriptionId": "sub_...", "status": "active",
  "canceledAt": null, "cancelReason": null,
  "interval": "month", "intervalCount": 1,
  "amountCents": 2500, "currency": "USD",
  "trialDays": null, "signupFeeCents": null,
  "createdAt": "2026-06-24T11:08:14.000Z", "startedAt": "2026-06-24T11:15:32.000Z",
  "lastRenewalAt": "2026-07-24T11:15:40.000Z", "renewalCount": 1,
  "nextBillingEstimate": "2026-08-24T11:15:40.000Z",
  "subscriptionHandle": "OWIwZTRmMWEuLi4="
}

Errors: 400 invalid_subscription_handle, 400 not_a_subscription, 404 subscription_not_found, 429 rate_limited (60/min per IP), 502 subscription_lookup_failed (transient — safe to retry).

Get order status

Poll after the customer returns, or as a fallback to webhooks.

Copycurl "https://payments.nxtpay.cc/v1/orders/8b0e4f1a-...?token=eyJ...&whitesiteId=32db38b1-..." \
  -H "Authorization: Bearer npk_YOUR_KEY"

Copy{
  "id": "8b0e4f1a-...", "orderNo": "ORD-202606-DW9PGM",
  "status": "paid", "currency": "USD", "totalCents": 2500, "refundedTotalCents": 0,
  "paidAt": "2026-06-17T11:15:32.000Z",
  "payments": [ { "id": "73571f33-...", "status": "succeeded", "attemptNo": 1,
                  "amountCents": 2500, "failureCode": null, "failureMessage": null } ]
}

Refund a payment

Refund a succeeded payment, fully or partially. Idempotent per (paymentId, amountCents).

Copycurl -X POST https://payments.nxtpay.cc/v1/refunds \
  -H "Authorization: Bearer npk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "whitesiteId": "32db38b1-...", "paymentId": "73571f33-...", "amountCents": 2500, "reason": "customer_request" }'

Response 201: { "id":"...", "status":"succeeded", "amountCents":2500, ... }. Errors: 400 whitesiteId_required / paymentId_required, 400 refund_exceeds_remaining, 404 payment_not_found, 502 upstream_error.

Routing status

Whether NxtPay can route a payment right now — use it to show/hide the option at checkout. Returns { "available": true, "whitesiteCount": 3, ... }.

Register a webhook URL

Self-register (or re-point) the HTTPS endpoint NxtPay delivers signed webhooks to — the WooCommerce plugin calls this on every settings save, and any integration can use it. NxtPay mints one fresh whsec_... signing secret, wires your URL across every processor in your routing pool, and returns the secret.

Copycurl -X POST https://payments.nxtpay.cc/v1/webhook-endpoint \
  -H "Authorization: Bearer npk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://your-site.com/nxtpay/webhook" }'

Response 200:

Copy{
  "ok": true,
  "secret": "whsec_...",
  "webhookUrl": "https://your-site.com/nxtpay/webhook",
  "connected": [ { "whitesiteId": "32db38b1-...", "name": "Acme Store" } ],
  "failed": []
}

Heartbeat

Best-effort periodic check-in (the WooCommerce plugin sends one on a schedule). All body fields — pluginVersion, wpVersion, siteUrl — are optional metadata. Always answers 200 with { "ok": true, "routingAvailable": true }; routingAvailable says whether any processor is currently active.

Status reference

Order status

pending · awaiting_payment · paid · partially_refunded · refunded · disputed · canceled · fulfilled · completed · failed

Payment status

pending · succeeded · failed · expired · canceled

Webhooks

Configure a webhook endpoint + event subscriptions in your NxtPay dashboard, or self-register one with POST /v1/webhook-endpoint. NxtPay POSTs signed JSON to your URL. Always verify the signature before trusting an event.

Events

order.created · order.paid · order.failed · order.refunded · order.disputed · payment.succeeded · payment.failed · payment.expired · refund.succeeded · dispute.created · dispute.updated · subscription.renewed · subscription.payment_failed · subscription.canceled

Payload & headers

CopyPOST your-endpoint
X-Nxtpay-Signature: t=1719236132,v1=<hmac_hex>
X-Nxtpay-Event: order.paid
X-Nxtpay-Delivery-Id: delivery_...

{ "id": "delivery_...", "type": "order.paid", "created_at": "2026-06-17T11:15:32.000Z",
  "data": { "orderId": "...", "orderNo": "ORD-...", "totalCents": 2500, "currency": "USD", "paidAt": "..." } }

Subscription event payloads

Verify the signature (HMAC-SHA256)

Copyimport crypto from "node:crypto";
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(",").map(kv => kv.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(p.t + "." + rawBody).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
  const fresh = Math.abs(Date.now()/1000 - Number(p.t)) < 300; // reject old (replay)
  return ok && fresh;
}

Errors

Errors are JSON with a machine-readable error code:

Copy{ "error": "positive_amountCents_required", "message": "optional", "detail": "optional" }

Rate limits

Per-minute sliding windows, per API key and per client IP. Over a limit returns 429 {"error":"rate_limited","retryAfter":N} with a Retry-After header — back off for that many seconds.

WordPress / WooCommerce plugin

Prefer a drop-in? Install the NxtPay plugin and paste your API key — no code.

• Download: /plugin/download (zip)
• Version metadata: /plugin/version