Integrations / Developer

Hosted checkout (API)

Live

Your server creates a session with POST /checkout/hosted/{storeId} and redirects the customer to the returned checkoutUrl. Gully Pay verifies the payment on-chain and sends a signed checkout.session.completed webhook.

Install

• Checkout API: reference

Setup

1. Create a key and a webhook (In the Gully Pay dashboard)
   • Run the Connect step: it creates a store API key with the checkout:write scope and a webhook endpoint for checkout.session.completed.
   • Store the key and the signing secret as server secrets.
2. Create a session from your server (On your server)
   • POST https://gullypay.xyz/api/checkout/hosted/{storeId} with Authorization: Bearer rk_... and {amount (cents), currency, successUrl, cancelUrl, clientReferenceId}.
   • Redirect the customer to checkoutUrl.
3. Fulfil on the webhook (On your server)
   • Verify X-GullyPay-Signature (hex HMAC-SHA256 of the raw body with the signing secret).
   • Re-read the session with GET /checkout/{sessionId} and fulfil once status is completed.

What the setup wizard creates

• A store API key (rk_…) pinned to your merchant, with exactly the scope checkout:write.
• A webhook endpoint (optional) for checkout.session.completed, checkout.session.expired, checkout.session.payment_failed, with its own signing secret.
• The key and signing secret are shown once. Running Connect again revokes the old key and disables the old endpoint.

The Test step opens a real hosted checkout (default $1.00) for your store. It completes when the signed checkout.session.completed webhook reaches your endpoint with a 2xx answer, or, without an endpoint, when the payment shows in the dashboard event viewer.

Networks

Scopes and events

• API key scopes: checkout:write
• Webhook events: checkout.session.completed, checkout.session.expired, checkout.session.payment_failed (see Webhooks)
• API base URL: https://gullypay.xyz/api