Create a payment for your merchant account. Send the request with your merchant API key and redirect the customer to the returned redirect_url.

Trailing slash: include the final / in the base URL. Calling the path without it may trigger an HTTP redirect; some clients then repeat the request as GET and lose your JSON body.

The API returns success: true with an action_required value and a redirect_url. Redirect the customer to this URL.

Create a payment for one of your sub-merchants. Use your reseller API key and add merchant_id in the JSON body.

Trailing slash: include the final / in the base URL so POST requests are not turned into GET by redirect-follow behaviour.

The reseller response is the same as the merchant response. The API returns a redirect_url for the customer checkout flow.

Configure HTTPS endpoints in the StixPay dashboard (Merchant → Webhooks). StixPay delivers each event as an HTTP POST with a JSON body. Delivery is skipped unless your endpoint subscription list includes that event type (see below).

In the dashboard, each webhook URL has its own Signing secret.

Use this value to verify webhook signatures (e.g. HMAC). Anyone signed into this merchant account can view it; protect your login.

Store the secret on your server environment (never in client-side code). If you use Regenerate secret, the old value stops working immediately — deploy the new secret before rotating, or legitimate webhooks will fail verification until your server and StixPay agree on the same key.

StixPay sends a hex-encoded HMAC-SHA256 of the exact raw request body using that endpoint’s signing secret as the key (hash_hmac('sha256', $rawBody, $signingSecret) in PHP).

1. Read the POST body as raw bytes/string before parsing JSON. Do not rebuild the body from a decoded object — encoding, key order, or spaces would break the signature.
2. Compute HMAC-SHA256 with your signing secret and compare the result (hex) to the X-Webhook-Signature header using a timing-safe equality check (e.g. PHP hash_equals).
3. Reject requests with a missing or mismatched signature (respond 401 or 403); then parse the JSON and process the event.

The dashboard checkboxes cover: payment.succeeded, payment.failed, and transaction_payout_success. Other events in this reference are emitted only if your endpoint’s stored subscription includes their type (legacy configuration, migrations, or support-assisted setup).

Sent after successful capture of a payment intent. Typical data fields:

Intent cancel (Payments API) — POST …/payments/intents/{id}/cancel: expects data with payment_intent_id, reason (canceled), timestamp. That flow also emits payment_intent.canceled; subscribe to both types if you need to reconcile every lifecycle signal.

On-ramp failure: data follows the on-ramp notification shape: transaction_id, amount, fees, net_amount, currency, merchant_order_id (nullable), payment_type (onramp), settlement (instant_onramp), provider, transaction_status, gateway_payment_status, gateway_transaction_status, optional payment_intent_id, timestamp, plus merged keys such as provider_callback with the raw provider payload when applicable.

Fires once when NxtGatew IPN confirms the merchant USDC payout. For API on-ramp, prefer this over payment.succeeded to mark end-to-end settlement. data is intentionally minimal (no provider):

If a merchant belongs to a reseller program, subscribed reseller endpoints receive a copy of merchant-bound events they are subscribed to; data is extended with reseller_program: true and merchants_table_id (merchants.id for the sub-merchant).

Failed calls return JSON with success: false, a human-readable message, and often an error field (e.g. api_error). The examples below match the PHP payment stack (api/payment/payments.php) and related helpers.

If the request hits the checkout endpoint as GET (browser tab, health check, or a POST that was converted to GET after a redirect), the API responds with HTTP 200 and success: true only as a discovery hint — no payment is created. Check observed_http_method: when it is GET, send a real POST with Content-Type: application/json and your API key. Using the canonical URL https://stixpay.com/api/payment/ (with trailing slash) avoids many redirects that strip POST bodies.

{
  "success": true,
  "message": "Use POST with a JSON body to create a checkout. Send X-API-Key or api_key.",
  "method_required": "POST",
  "content_type": "application/json",
  "observed_http_method": "GET",
  "post_hint": "If you sent POST but saw method GET here, avoid redirects that strip POST (use URL ending with /api/payment/ or internal rewrite, not 301/302 to add slash)."
}

Note: Any database, network, or unexpected PHP error may appear as message text; treat unknown messages as generic failures and log the response for support.