Custom Payment Page

Endpoint

GET https://api.stafiel.com/api/v1/c/pay/{paymentToken}/data

Request Payment Data

1. Create a checkout session from your backend.

2. Store the checkoutSessionUrl returned in the successful API response and read its final path segment as the payment token. For example, the token in https://pay.stafiel.com/pay/ps_live_example is ps_live_example.

3. Replace {paymentToken} in the endpoint and request the payment data from your backend. This endpoint does not require an API key or Merchant ID.

   curl "https://api.stafiel.com/api/v1/c/pay/ps_live_example/data"
   

4. Return only the fields your frontend needs for rendering.

Only extract a token from the checkoutSessionUrl returned by Stafiel's Checkout Sessions API. Do not create, reconstruct, or modify the URL yourself. For Hosted Checkout or Widget integrations, pass the complete URL exactly as returned.

Success Response

{
  "success": true,
  "data": {
    "orderId": "ord_your_order_id",
    "amountUsd": "20.00",
    "totalPaidAmountUsd": "0",
    "tokenSymbol": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "tokenDecimals": 6,
    "orderAddress": "0x372B9150e1b0436f4c295D3D48e197b0aaDFBB5D",
    "paymentRequest": {
      "plainAddress": "0x372B9150e1b0436f4c295D3D48e197b0aaDFBB5D",
      "requestUri": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x372B9150e1b0436f4c295D3D48e197b0aaDFBB5D&uint256=20000000",
      "requestKind": "erc_681",
      "reference": null,
      "chainSupport": "available",
      "unavailableReason": null,
      "solanaAddressContext": null
    },
    "paymentAddressState": "ready",
    "chainId": 8453,
    "chainSlug": "base",
    "chainNetwork": "mainnet",
    "chainCompatibility": "evm",
    "chainName": "base",
    "chainDisplayName": "base",
    "chainExplorerUrl": "https://basescan.org",
    "orderAddressExplorerUrl": "https://basescan.org/address/0x372B9150e1b0436f4c295D3D48e197b0aaDFBB5D",
    "merchantPublicName": "Example Merchant",
    "metadata": {
      "productName": "Membership Plus",
      "quantity": "1",
      "unitLabel": "month"
    },
    "expiresAt": "2026-08-19T12:30:00.000Z",
    "status": "awaiting_payment",
    "createdAt": "2026-08-19T12:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
orderId	string	Stafiel order ID for the checkout session.
amountUsd	string	Expected payment amount.
totalPaidAmountUsd	string	Total payment amount currently recorded for the order.
tokenSymbol	string	Token the customer must send.
tokenAddress	string	Token contract or mint address. Do not use it as the payment recipient.
tokenDecimals	number	Token decimals used for amount representation.
orderAddress	string	Payment recipient address. Prefer paymentRequest.plainAddress when rendering payment controls.
paymentRequest	object	Stafiel-generated plain address and optional wallet payment request. See paymentRequest Object.
paymentAddressState	string	ready means the payment address is available, provisioning means it is still being prepared, and failed means it is unavailable. During provisioning, refresh Payment Data and update the page when the state changes.
chainId	number	Numeric chain ID.
chainSlug, chainName, chainDisplayName	string	Public chain identifiers and display value.
chainNetwork	string	Network associated with the checkout session.
chainCompatibility	string	Chain family, such as evm, solana, or tron.
chainExplorerUrl	string or omitted	Chain explorer base URL when available.
orderAddressExplorerUrl	string or omitted	Explorer URL for the payment recipient when available.
merchantPublicName	string or omitted	Merchant name for customer-facing display.
metadata	object or null	Sanitized checkout metadata.
expiresAt	string	ISO 8601 timestamp when the payment session expires.
status	string	Current order status.
createdAt	string	ISO 8601 checkout creation timestamp.

paymentRequest Object

Field	Type	Description
plainAddress	string	Payment recipient for address-only display, copy, and QR code.
requestUri	string or null	Complete wallet payment request URI for the original checkout amount. Use it exactly as returned. It does not represent a remaining balance after an underpayment.
requestKind	erc_681, solana_pay, or null	Payment request format when available.
reference	string or null	Solana payment reference when present.
chainSupport	available or unavailable	Whether requestUri can be offered.
unavailableReason	string or null	Machine-readable reason that a payment request is unavailable.
solanaAddressContext	object or null	Solana-specific address-role information. Use plainAddress as the displayed recipient.

chainSupport: unavailable means only that a wallet payment request URI is not available. The checkout can still accept an address-only payment when the session is otherwise payable.

Status and Fulfillment

Use Payment Data only to render the customer payment page.

Note: Payment Data is not the source of truth for fulfillment. Determine fulfillment from signed webhooks or the authenticated Orders API. Use the Payments API when payment confirmation details are required.

For status meanings and merchant handling considerations, see Order Lifecycle and Payment Status.

Error Responses

Example 404 response:

{
  "success": false,
  "error": {
    "type": "unavailable",
    "message": "Payment session is unavailable"
  }
}

HTTP Status	Error	Meaning
404	error.type = unavailable	The payment token is invalid, expired, inactive, or otherwise unavailable. The response does not reveal the specific reason.
429	RATE_LIMIT_EXCEEDED	Too many requests. Retry after the indicated time.

Security Notes

• Render metadata values as text, not HTML.
• The checkoutSessionUrl contains the payment token used to access the payment session data. Avoid sending it to logs, analytics, error reporting, or third-party scripts.