Payment Method Definition

Payment Method Features

Workflow

1. Create an Intent with useCheckoutForm: true and include BYBIT_PAY in paymentIntent.formDetails.displayedPaymentMethods.
2. Receive the Hosted Checkout URL in paymentIntent.additionalData.url and redirect the payer to it.
3. The checkout form starts a Bybit Pay payment within the Intent. The platform creates the Bybit order and the form displays its QR code.
4. The payer scans the QR with Bybit, reviews the transaction details, and confirms the payment.
5. The platform updates the payment status and sends a webhook to the configured URL. The checkout form displays the result.
6. Fulfil the order only when the platform payment status is CAPTURED.

The diagram shows the successful and expired-payment paths. Other unsuccessful outcomes are described under Payment Statuses.

Create Intent Request

Use the standard platform authentication and settlement-account-id header described in the API reference. The examples below show JSON request and response bodies.

Intent, Payment, and PaymentIntent

Request/Response Description

{
  "clientReferenceId": "order-bybit-checkout-1001",
  "useCheckoutForm": true,
  "paymentIntent": {
    "formDetails": {
      "displayedPaymentMethods": ["BYBIT_PAY"],
      "backToStoreRedirectUrl": "https://merchant.example.com/orders/order-bybit-checkout-1001"
    },
    "submittedAmount": {
      "value": 100.50,
      "currency": "CURRENCY_CODE"
    },
    "description": "Order bybit-checkout-1001",
    "webhookUrl": "https://merchant.example.com/webhooks/payments"
  }
}

{
  "intentId": "344115072451633152",
  "checkoutForm": true,
  "paymentIntent": {
    "intentSessionId": "344115072480993280",
    "backToStoreRedirectUrl": "https://merchant.example.com/orders/order-bybit-checkout-1001",
    "displayedPaymentMethods": ["BYBIT_PAY"],
    "submittedAmount": {
      "value": 100.50,
      "currency": "CURRENCY_CODE"
    },
    "description": "Order bybit-checkout-1001",
    "webhookUrl": "https://merchant.example.com/webhooks/payments",
    "additionalData": {
      "url": "https://checkout.example.com/session/344115072480993280",
      "expirationDateTime": "2026-09-18T15:30:00Z"
    }
  },
  "clientReferenceIntentId": "order-bybit-checkout-1001",
  "description": "Order bybit-checkout-1001",
  "intentStatus": "CREATED"
}

Bybit Pay Checkout Experience

The Hosted Checkout form creates the Bybit payment and displays the QR. The payer scans it with Bybit and confirms the transaction there.

After the platform records the result, the checkout form displays a success or failure screen. The payer can return to your store using the destination configured in paymentIntent.formDetails.backToStoreRedirectUrl, subject to the checkout template's behaviour.

If a payment expires, the form displays the failed attempt and offers the next actions available for that session. A retry creates a new payment attempt when the checkout session permits it.

Payment Statuses

Retrieve Payment Status

If a webhook is delayed or missed, use the saved intentId to recover the payment attempts created by Checkout:

1. Call GET /processing/api/v1/intents/{id} with the intentId returned when you created Checkout.
2. Inspect payments[]. Each payment has its own id and status. Save these IDs and evaluate each attempt separately.
3. To retrieve an individual payment, call GET /processing/api/v1/payments/{id} with that payment's ID. If you already received transactionId in a payment webhook, you can use it directly for this call.

Before Checkout creates a payment, the Intent may contain no payment attempts. An empty list does not establish a payment outcome. If multiple attempts exist, use each attempt's status; a failed attempt does not override a separate successful payment for the order.

Refunds

Bybit Pay payments completed through Hosted Checkout use the platform's standard refund flow.

• Request a refund only after the original payment reaches CAPTURED.
• Use the platform payment ID: transactionId in a payment webhook (transactionType: "PAYMENT"), payments[].id in the Get Intent response, or id in the Get Payment response.
• Submit POST /processing/api/v1/refunds with that value in paymentId. The refund request expects an int64 JSON integer; preserve the exact identifier when converting the response string.
• For a full refund, omit paymentSubmittedAmount and paymentAuthAmount, and omit partial or set it to false. This requests the original payment amounts and must pass the available-amount checks, including any earlier refunds.
• Refund processing is asynchronous. A successful creation response accepts the request for processing; treat the refund as completed only when its status is REFUNDED.
• Configure the refund's webhookUrl or the settlement account default for refund status updates. The refund does not inherit the payment's request-specific webhook URL.
• Retrieve the current refund state through GET /processing/api/v1/refunds/{id} if needed.

Webhooks

Payment status notifications use paymentIntent.webhookUrl when supplied, otherwise the settlement account's default webhook URL. Configure one of these destinations to receive notifications.

• Status notifications can include intermediate states. Fulfil the order only after confirming CAPTURED.
• Process duplicate notifications idempotently so that repeated delivery cannot fulfil the same order twice.
• Correlate each attempt by its payment ID and the overall order by its Intent ID. A failed attempt does not override a separate successful payment for the order.
• If a notification is delayed or missed, retrieve the Intent by its saved ID and inspect payments[]. Once the payment ID is known, you can retrieve that payment directly. See Retrieve Payment Status above.

See Webhooks: Overview and Webhooks: Example for the shared notification contract.