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

Omit environment or use "auto" to follow the centrally authorized lifecycle: Test while the site is in preview, and Live only after Go Live. Use "sandbox" or "production" only to require that exact environment. In sandbox, Stripe test cards such as 4242 4242 4242 4242 move no real money.

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" \
  -H "Idempotency-Key: your-order-1042" \
  -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", "Idempotency-Key": "your-order-1042" },
  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", "Idempotency-Key: your-order-1042"],
  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. Persist one unique Idempotency-Key per logical refund. Reuse it only when retrying the same payment, amount, and reason.

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

Response 200: { "id":"...", "status":"succeeded", "amountCents":2500, ... }. A processing response is still being confirmed, so retry with the same key. Errors: 400 invalid_refund_request_id, 400 refund_exceeds_remaining, 404 payment_not_found, 409 idempotency_conflict, 409 refund_in_progress, 422 refund_provider_failed, 502 upstream_error.

Routing status

Whether this API key’s Routing Group has an active Whitesite route with an applied Provider Account binding — use it to show/hide the option at checkout. Returns { "available": true, "whitesiteCount": 3, "routingGroupId": "...", ... }.

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 · refund.failed · 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