Payments API

Connect your organization

1. Choose the correct organization in your merchant dashboard.
2. On Payment Accounts, request Stripe, Square or Elavon and choose a Test or Live website. Use the assigned domain for your provider setup, then connect the provider credentials. A website alone is not a ready payment account.
3. Set your merchant site URL and wait for payment readiness. One ready account is used directly; multiple eligible accounts follow the organization’s saved routing policy (round robin by default, custom shares or primary/backup priority).
4. In API Keys, create a named organization key with optional expiry (default: no expiry), to obtain your npk_… key. Store it in your server's secret configuration. Refreshing the key replaces it: update every integration using the old key.
5. Set up Webhooks for payment results, disputes and account alerts, then run a sandbox checkout before going live.

Your organization's API key, your Stripe/Square/Elavon credentials, and each endpoint's whsec_… webhook signing secret have different purposes. Send only the organization key to the public Payments API. Never paste a provider secret into your storefront code.

Automatic connection checks

Saving provider credentials automatically applies the connection and starts the website checks. Payment Accounts shows each step, the connected Test/Live account, its verification time and any action needed. For Live Stripe, setup refreshes the account's restrictions and requirements and updates website details where Stripe permits API edits. Standalone accounts require their owner to edit the profile in Stripe; use Open Stripe account when that action is shown. Stripe restrictions must also be resolved there before rechecking. Provider-specific steps that do not apply are marked accordingly.

If setup needs attention, follow the reason shown and use Retry setup to check the saved connection again without entering the keys again. Recheck connection refreshes completed checks. Live activation still requires its saved consent and current billing eligibility; a changed website price must be reviewed again. Setup continues independently of automatic reserve generation.

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

GET /v1/integration returns {organization:{id,name,merchantSiteUrl},readiness:{available,environment,eligibleAccountCount,reason?},liveEnabled,legacyIntegrationIds}. Every key manages all payments for its organization. One organization represents one merchant storefront and may have multiple payment accounts. New attempts use the organization’s saved routing policy: round robin by default, custom weighted request shares or primary/backup priority. Only eligible included accounts participate. Administrators configure these rules in Merchant settings → Routing. Excluding an account affects new API requests, not direct website checkout. A backup is selected before dispatch; provider errors do not automatically create another payment. Save the original checkout website and idempotency key for retries; subscriptions retain their original provider. Treat subscription handles as opaque. 503 merchant_webhook_sync_pending means the selected website is still applying configured callbacks; retry with the same idempotency key.

Routing across websites and providers: the same merchant can distribute new payment links across Stripe, Square and Elavon accounts and their assigned whitesites, including several accounts with the same provider. Each selection chooses an account together with its checkout website and provider. Currency, amount, capacity and readiness checks still apply. Subscriptions currently use Stripe only. Direct purchases on a whitesite stay with that website’s own connection.

Returning customers: an administrator can enable a preference for the account used on the customer's most recent successful API payment. Matching uses your supplied customer.email, ignoring surrounding whitespace and case, within your organization and Live/Test environment. Plus-addresses and dots are preserved. This requires synchronized charge evidence and a verified original account selection; pending or failed checkouts, direct website purchases, and older history without that evidence do not establish a preference. New customers use the normal strategy. Eligible returning requests override rotation or weighted shares. The previous account's current website and all payment safeguards still apply.

If the previous account is unavailable, the admin can allow normal routing or require 503 returning_customer_account_unavailable. That error is returned before a new provider payment is created; retry the same idempotency key after the account or policy is corrected. There is no per-request account selector or customer-policy bypass. Existing payment retries and subscription renewals keep their original provider. Email matching is a routing hint, not customer authentication.

Environments & testing

Omit environment or use "auto" to follow the centrally authorized lifecycle: Test before the first Live activation; then Live permanently, with no fallback to Test if Live becomes unavailable. 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.

Test and Live use the same base URL and organization key. Explicit sandbox prevents accidentally using a live route; a test website does not accept a live request. Provider sandbox credentials are required. Stripe test card numbers do not apply to Square or Elavon.

Quickstart

1. Create a payment link  →  2. redirect only if paymentUrl is present (otherwise reconcile the retry)  →  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"
  }'

Copy// Run on your server. Persist this checkout key with your own order first.
const 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();
if (!res.ok) throw new Error(link.error ?? "checkout_failed");
function checkoutNextStep(link) {
  // Persist orderId, statusToken and routedVia.whitesiteId before branching.
  // Merge optional paymentId into your saved record; never erase an earlier ID.
  if (link.settled === true) {
    // No new checkout. Verify signed order.paid or GET /v1/orders before fulfilment.
    return { action: "reconcile", orderId: link.orderId };
  }
  if (link.expired === true) {
    // Reconcile the original order first. Only an intentional new purchase gets
    // a new key; never automatically replace the key on an ambiguous response.
    return { action: "expired", orderId: link.orderId };
  }
  if (typeof link.paymentUrl === "string" && link.paymentUrl.length > 0) {
    return { action: "redirect", paymentUrl: link.paymentUrl };
  }
  // Unexpected success shape: keep the same key and reconcile; do not recharge.
  throw new Error("checkout_response_requires_reconciliation");
}
const nextStep = checkoutNextStep(link);
// Redirect only when nextStep.action === "redirect".
// Otherwise reconcile the saved order or show that this checkout expired.

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",
  ]),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) throw new RuntimeException("Retry with the SAME saved key");
$link = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status < 200 || $status >= 300) throw new RuntimeException($link["error"] ?? "checkout_failed");
// Save orderId, statusToken and routedVia.whitesiteId; merge paymentId if present.
if (($link["settled"] ?? false) === true) {
  // Reconcile signed order.paid or GET /v1/orders before fulfilment. No redirect.
} elseif (($link["expired"] ?? false) === true) {
  // Reconcile first; ask the buyer to start an intentional new purchase.
} elseif (is_string($link["paymentUrl"] ?? null) && $link["paymentUrl"] !== "") {
  header("Location: " . $link["paymentUrl"]);
  exit;
} else {
  throw new RuntimeException("Reconcile the saved checkout; do not create a new key");
}

Store orderId, paymentId, statusToken and routedVia.whitesiteId with your own order. Poll with the order ID, token and site ID; refund with the payment ID and site ID.

Provider capabilities

Public payments support USD and CAD. Stripe supports both checkout currencies; Square requires a matching verified location currency and Elavon a matching verified terminal currency. Re-verify Square or Elavon credentials if their currency is unknown. Checkout readiness is checked independently for each provider and environment. Subscription requests require an eligible Stripe route. An account alert reports an observed provider change; it is not an instruction to change your own customer balance or retry a payment.

Currencies & merchant billing

Customer checkout currency and NxtPay merchant billing are separate. Your customer pays in the currency your integration requests. NxtPay bills your organization for its processing, website and domain fees.

CAD checkout requires platform enablement and a compatible verified provider. Configure CAD routing limits independently of USD limits; they are not converted. Missing required CAD limits return 503 currency_limits_not_configured, and disabled CAD checkout returns 503 currency_not_enabled. Keep the currency unchanged when retrying with an existing idempotency key; a changed payload returns 409 idempotency_conflict.

How CAD fee conversion works

The percentage fee is calculated in the original payment currency first. USD fee lines are converted using a saved Bank of Canada daily USD-to-CAD rate, with no NxtPay FX markup. The rate is CAD per USD, from the latest available observation on or before the quote date, at most seven calendar days old. Each USD line is rounded separately to CAD cents (half cents away from zero), then added to the total; CAD lines keep their original cents.

Converted invoice details and PDFs show the original amounts, saved rate and date, and CAD total. Pending retries preserve the saved quote rather than fetching a new rate. If no usable rate is available for USD fees, collection waits; NxtPay does not guess a rate. Existing invoices are never repriced because the exchange rate changes. Dashboard summaries automatically show CAD reference-rate equivalents; individual transaction rows retain their original currencies. Missing rate coverage makes affected CAD totals unavailable. These estimates never replace a saved invoice total.

Card billing and monthly EMT

Card billing collects eligible fees through scheduled billing runs. EMT is enabled only by a NxtPay administrator for your organization. Fees continue to accrue, and after each calendar month ends an invoice is issued for eligible fees through that completed UTC month. Current-month fees remain unbilled; late prior-period fees may appear on a later invoice.

For EMT, follow your invoice or the payment instructions arranged with NxtPay. An administrator marks the invoice paid after confirming receipt. EMT is a payment method for the same CAD fees, not an extra fee. Neither EMT enrollment nor marking an invoice paid is available through the public Payments API. View your fees and invoices in Billing.

Before you go live

1. For each currency you intend to accept, complete a sandbox checkout, cancel a checkout, and confirm order lookup and your paid-event handler.
2. Repeat a create request with the same saved idempotency key and confirm you reuse the original checkout. Test a sandbox refund with its own saved key.
3. Verify signatures on raw bytes, reject invalid signatures, and ensure duplicate deliveries cannot fulfil or refund twice. Trigger an event with a sandbox checkout, then inspect its delivery status in the dashboard.
4. Save a subscription handle and test cancellation if you sell recurring plans. Do not treat a subscription checkout response as an active subscription.
5. Complete Live activation and provider readiness in Payment Accounts; ensure the live account is assigned and eligible. Send environment: "production" when switching your integration to Live.

GET /v1/routing-status is a live availability hint, not a reservation or an environment-specific guarantee. A subsequent checkout can still be unavailable. The public API does not expose dispute evidence submission or account-remediation endpoints; use Disputes and Account Status in the merchant dashboard.

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://shop.example/api/storefront/checkout/start?token=...",
  "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.

Checkout URLs are opaque navigation URLs on the selected whitesite. Use them as returned; do not require a provider hostname or reconstruct the destination.

A successful retry can have no checkout URL. HTTP 200 with replayed: true, settled: true means the original order is already settled; replayed: true, expired: true means its checkout reached its deadline; poll the order and treat the checkout as closed only when its payment shows providerExpiredAt. Both include orderId, orderNo, status, statusToken, and routedVia, but omit paymentId, paymentUrl, expiresAt, and provider. Keep previously saved payment IDs; obtain payment IDs from order lookup if the original response was lost. Never redirect to a missing URL or automatically issue a new key. Reconcile settled orders before fulfilment; reconcile expired orders before an intentional new purchase. Subscription retries follow the same rule and still return subscriptionHandle.

Copy{ "orderId": "8b0e4f1a-2c3d-4e5f-9a1b-2c3d4e5f6a7b", "orderNo": "ORD-202606-DW9PGM", "status": "paid", "statusToken": "eyJ...", "replayed": true, "settled": true, "routedVia": { "whitesiteId": "32db38b1-..." } }

Copy{ "orderId": "8b0e4f1a-2c3d-4e5f-9a1b-2c3d4e5f6a7b", "orderNo": "ORD-202606-DW9PGM", "status": "expired", "statusToken": "eyJ...", "replayed": true, "expired": true, "routedVia": { "whitesiteId": "32db38b1-..." } }

Closing or replacing a payment account stops new checkouts on its previous website. Historical order lookup, refunds and subscription management continue against their original website and provider attempt. Keep the original runtime and provider connection available. Revoked or expired keys and terminated organizations block access.

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://shop.example/api/storefront/checkout/start?token=...",
  "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,
                  "providerExpiredAt": null } ]
}

A payment can show expired once its checkout deadline passes, before the provider confirms the outcome. providerExpiredAt is set only when NxtPay has confirmed with the provider that the checkout closed unpaid, and the payment.expired webhook is sent then (a backlog check of a checkout whose deadline passed more than three days earlier records it silently; the provider's own expiry event still sends the webhook). Until it is set, a late payment can still succeed.

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.

amountCents is in the original payment currency. The refund request has no currency override and performs no currency conversion; it must not exceed the remaining unrefunded balance.

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 the organization has an eligible current payment account — use it to show/hide the option at checkout. Returns { "available": true, "whitesiteCount": 3, "organizationId": "...", ... }.

Manage custom merchant webhooks

Configure the same endpoints shown in Dashboard → Webhooks and the admin merchant page using your organization's server-side npk_… key. These are callbacks to your merchant website. Stripe's incoming provider webhooks and the organization routing-rejection callback are separate.

1. List the website's endpoints and inspect supportedEvents and capabilities.idempotentCreate/capabilities.testDelivery. Older tenant runtimes must be upgraded before these operations work; they fail closed with webhook_runtime_update_required.
2. Create with { name, url, events, active? }, a public HTTPS URL and a persisted Idempotency-Key (1–128 visible ASCII characters). First creation returns 201 and its one-time signing secret. Store the secret securely. Identical retries return 200 with replayed:true, without the secret, and never rotate it. Changed settings with the same key return 409 idempotency_conflict. If the first response was lost, list the endpoint and explicitly rotate. Do not automatically create a new endpoint. Deleting the row ends creation replay guarantees.
3. Use PUT to change its name, URL, events or active state. Use active:false to pause and keep history; deleting removes history. No signing secret appears in lists, updates or delivery history.
4. Send a test with an optional persisted UUID { requestId }. 202 means queued. Reusing requestId deduplicates only while endpoint configuration is unchanged. Changing the URL, secret, events or active state creates a different test configuration even with the same ID. Verify its normal raw-body signature, acknowledge webhook.test with 2xx, and do not fulfil an order. Poll endpoint verification and delivery history. States are not_tested, pending, retrying, succeeded, failed, stale. Only succeeded confirms delivery. A test does not charge, refund or create a dispute. Successful delivery does not verify business processing or Stripe account readiness. URL or secret changes invalidate older verification. OpenAPI defines webhook.test separately from selectable subscription events.
5. Only intentionally call rotate-secret: every call creates a new secret. Never blindly retry an ambiguous response. Update your receiver, keep the previous secret for in-flight requests, then test again.

Management is limited to 60 calls/minute per organization; tests and rotations also allow five/minute per endpoint. Current key revocation, expiry and ownership are checked on every call. Shared runtimes and previous assignments do not grant access. This setup never enables payment routing. See the full API reference for a copyable creation example.

Register a plugin webhook URL

Register the plugin-managed HTTPS endpoint for assigned payment-account websites. The WooCommerce plugin uses this route, and a custom integration can use its fixed event set too. NxtPay returns a durable whsec_... signing secret for this organization and endpoint. For custom event selections and separate endpoints, use the dashboard Webhooks page instead.

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", "siteUrl": "https://your-site.com/shop" }'

Response 200:

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

siteUrl explicitly enrolls the external merchant storefront; it is separate from the webhook callback. URL paths identify distinct installs. A local HTTP store may use a public HTTPS webhook tunnel. A different previously bound merchant URL returns merchant_site_mismatch; an authorized dashboard merchant-site edit is required to rebind it. Test connection only reads GET /v1/integration. Enrollment does not restrict checkout return URLs.

The plugin-managed event set is order.paid, payment.succeeded, order.refunded, refund.succeeded, order.failed, payment.failed, payment.expired, order.disputed, dispute.created, subscription.renewed, subscription.canceled, subscription.payment_failed. Add a custom dashboard endpoint for dispute.updated, account.issue and account.updated.

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

In the merchant dashboard, open Webhooks, choose a connected website, add a public HTTPS endpoint, and select the events you need. Save its signing secret on your server. Repeat for each website that needs delivery. You can also register the plugin-managed endpoint with POST /v1/webhook-endpoint. NxtPay POSTs signed JSON to your URL. Always verify the signature before trusting an event.

Events

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": "..." } }

Disputes and account alerts

observedAt is when NxtPay received the provider notification. A healthy account.updated snapshot does not automatically clear a payment pause or prove checkout readiness; check Payment Accounts. Future requirements and payout-only problems can appear in account.updated without an account.issue event.

Subscribe to both dispute events and both account events. Event selection can be edited on an existing endpoint without replacing its URL or signing secret. These notifications depend on the connected provider and site runtime; older sites need the platform runtime update before they can send newly supported events. Previously failed or historical events are not automatically replayed when you subscribe.

Subscription event payloads

Verify the signature (HMAC-SHA256)

Use the endpoint's signing secret, not your organization API key. Keep the exact raw bytes before JSON parsing. Malformed, stale or future-dated signatures must fail closed.

Copyimport crypto from "node:crypto";
function verify(rawBody, header, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string" || !secret) return false;
  const match = /^t=([0-9]{1,12}),v1=([a-fA-F0-9]{64})$/.exec(header);
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(match[1] + ".").update(rawBody).digest();
  const supplied = Buffer.from(match[2], "hex");
  return supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
}
// Express: mount express.raw({ type: "application/json" }) on this webhook route
// BEFORE express.json(). Pass req.body (the Buffer) directly to verify().
// Parse JSON only after verification; durably save body.id before returning 2xx.

Copyfunction nxtpay_verify($raw, $header, $secret) {
  if (!is_string($raw) || !is_string($header) || !$secret) return false;
  if (!preg_match('/^t=([0-9]{1,12}),v1=([a-fA-F0-9]{64})$/D', $header, $parts)) return false;
  if (abs(time() - (int) $parts[1]) > 300) return false;
  $expected = hash_hmac('sha256', $parts[1] . '.' . $raw, $secret);
  return hash_equals($expected, strtolower($parts[2]));
}
// $raw = file_get_contents('php://input'); verify before json_decode().

Receive reliably

1. Verify the signature, parse JSON, and durably store body.id with a unique constraint before acknowledging. The delivery header carries the same ID; do not trust unsigned headers alone.
2. Return a 2xx promptly (including for an already-recorded delivery), then process from your own queue. If storage fails, return non-2xx so NxtPay retries.
3. Deliveries can repeat or arrive out of order. Also guard fulfilment by order ID and renewal processing by subscription/order IDs when multiple endpoints receive the same event.
4. Reconcile uncertain payment and subscription state with the lookup endpoints. Do not infer financial state from a missing webhook.

The same delivery ID is reused on retries. created_at and the signature timestamp are generated for the delivery attempt; they are not a stable business-event timestamp. Use the event's own fields such as paidAt, occurredAt or canceledAt when available. Your receiver should tolerate additional fields and acknowledge unknown event types without applying a financial action.

Transaction amount limits

Ask your platform administrator to set independent minimum and maximum USD and CAD payments through the organization payment-policy controls. Bounds are inclusive; leaving a bound blank means unlimited. These limits apply to new public payment and subscription requests in Test and Live. Accounts and routes can impose stricter limits. Daily caps are checked during fresh selection and by runtime authorization.

For subscriptions, both the recurring price and a nonzero first invoice must fit. The first invoice is (trialDays > 0 ? 0 : amountCents) + signupFeeCents. A zero-dollar trial start is exempt from this routing minimum; provider/account requirements still apply. Previously accepted idempotency keys and provider-managed renewals are not rechecked against later limit changes.

An out-of-range request returns 422 payment_limit_exceeded before creating a checkout:

Copy{
  "error": "payment_limit_exceeded",
  "rejection": {
    "id": "f4e331fe-2070-4e2b-a886-8b1e16663e16",
    "reason": "above_maximum",
    "scope": "organization",
    "operation": "payment_link",
    "amountCents": 25000,
    "currency": "USD",
    "amountMinCents": 100,
    "amountMaxCents": 20000,
    "requestedEnvironment": "sandbox",
    "partnerReference": "your-order-1042",
    "correlationId": "request-reference"
  }
}

Reasons: below_minimum, above_maximum, or no_matching_amount_range. Scope: organization or routes. Route ranges can have gaps, so the displayed bounds do not promise that every amount between them is accepted. For subscription below/above rejections, the returned amount identifies the rejected recurring or initial invoice. If each amount fits a different route but no single route accepts both, no_matching_amount_range returns the recurring amount as a reference and null bounds. Fields without a value are null.

Store rejection.id and your reference; there is no checkout/order ID. Exact same-key retries return the saved decision even after a settings change. Correct the amount or limits, then intentionally start a new attempt with a new key. Changing a payload with the old key returns 409 idempotency_conflict.

To receive payment.routing_rejected, configure the separate organization callback through the admin organization payment-limit controls. It is not a per-website event subscription and POST /v1/webhook-endpoint does not enable it. The signed event's data contains the rejection; use the raw-body HMAC verification above. Delivery is durable with seven total attempts. Deduplicate the signed delivery ID and match the rejection ID/reference. A callback failure never permits a rejected payment.

Pending deliveries retain the callback URL and signing secret saved at rejection time, even after changing or disabling the callback. Keep the old endpoint and secret valid until those deliveries finish. Rotation affects new rejections.

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 organization 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