docs

Create a checkout session

Creates a new checkout session for hosted or embedded checkout. Returns a session with a URL to redirect customers for payment.

POST
/checkout/sessions

Creates a new checkout session for hosted or embedded checkout. Returns a session with a URL to redirect customers for payment.

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/checkout/sessions" \  -H "Content-Type: application/json" \  -d '{    "afterCompletion": {      "type": "redirect",      "redirect": {        "url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}"      }    }  }'
{
  "id": "string",
  "object": "checkout.session",
  "createdAt": "string",
  "updatedAt": "string",
  "mode": "payment",
  "uiMode": "hosted",
  "submitType": "PAY",
  "customerCreation": "always",
  "status": "open",
  "paymentStatus": "unpaid",
  "currency": "EGP",
  "amountSubtotal": 0,
  "amountTotal": 0,
  "totalDetails": {
    "amountDiscount": 0,
    "amountShipping": 0,
    "amountTax": 0,
    "amountPlatformFee": 0,
    "amountCollectedVat": 0
  },
  "presentmentDetails": {
    "amount": 80000,
    "currency": "KWD",
    "exchangeRate": 168.21,
    "exchangeRateId": "exr_3gQWCqaDsihr09Fi5MfwXL",
    "amountSubtotal": 100000,
    "amountTotal": 80000,
    "amountDiscount": 20000,
    "amountCollectedVat": 11200,
    "amountPlatformFee": 0,
    "amountTax": 0
  },
  "afterCompletion": {},
  "cancelUrl": "string",
  "url": "string",
  "clientSecret": "string",
  "expiresAt": "string",
  "isExpired": false,
  "customerId": "string",
  "customer": {
    "id": "string",
    "type": "guest",
    "name": "string",
    "email": "string",
    "phone": "string",
    "address": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string"
    },
    "shipping": {
      "name": "string",
      "phone": "string",
      "address": {}
    },
    "metadata": {}
  },
  "customerDetails": {
    "name": "string",
    "email": "string",
    "phone": "string",
    "billingDetails": {
      "name": "string",
      "email": "string",
      "phone": "string",
      "address": {}
    },
    "shipping": {
      "name": "string",
      "phone": "string",
      "address": {}
    }
  },
  "paymentIntentId": "string",
  "paymentIntent": {
    "id": "pi_3MqAaCB4Otk1z2A30vXyz9aB",
    "object": "payment_intent",
    "checkoutSessionId": "cs_test_a1b2c3d4",
    "amount": 10000,
    "amountCapturable": 0,
    "amountReceived": 10000,
    "currency": "EGP",
    "status": "SUCCEEDED",
    "createdAt": "2025-03-25T12:00:00.000Z",
    "updatedAt": "2025-03-25T12:00:00.000Z",
    "clientSecret": "pi_3MqAaCB4Otk1z2A30vXyz9aB_secret_xyz",
    "captureMethod": "automatic",
    "confirmationMethod": "automatic",
    "description": "Order #1234",
    "receiptEmail": "customer@example.com",
    "canceledAt": "2025-03-25T12:00:00.000Z",
    "shipping": {
      "address": {},
      "name": "Mohamed Ali",
      "phone": "+20 100 123 4567"
    },
    "amountDetails": {
      "productAmount": 10000,
      "tax": {},
      "platformFees": {},
      "tip": 1000,
      "discount": 500
    },
    "presentmentDetails": {
      "amount": 80000,
      "currency": "KWD",
      "exchangeRate": 168.21,
      "exchangeRateId": "exr_3gQWCqaDsihr09Fi5MfwXL"
    },
    "latestCharge": {
      "id": "string",
      "object": "charge",
      "amount": 0,
      "amountCaptured": 0,
      "amountRefunded": 0,
      "currency": "EGP",
      "createdAt": "2025-03-25T12:00:00.000Z",
      "status": "string",
      "paid": true,
      "refunded": true,
      "captured": true,
      "capturedAt": "2025-03-25T12:00:00.000Z",
      "failureCode": "string",
      "failureMessage": "string",
      "receiptUrl": "string",
      "receiptEmail": "string",
      "billingDetails": {
        "address": {}
      },
      "paymentMethodDetails": {
        "card": {},
        "valu": {},
        "fawry": {}
      },
      "outcome": {},
      "balanceTransaction": {
        "feeDetails": [],
        "payoutBatch": {}
      },
      "presentmentDetails": {},
      "refunds": [
        {}
      ],
      "paymentIntentId": "string",
      "paymentMethodId": "string",
      "calculatedStatementDescriptor": "string",
      "disputed": true,
      "externalChargeId": "string",
      "config": {},
      "geocoding": {
        "location": {}
      },
      "session": {},
      "merchantOrigin": "https://shop.merchant.com",
      "merchantDomain": "merchant.com",
      "processorCapabilities": {},
      "activeHoldId": "hld_xxx",
      "settlementModel": "aggregated"
    },
    "charges": [
      {
        "billingDetails": {},
        "paymentMethodDetails": {},
        "outcome": {},
        "balanceTransaction": {},
        "refunds": [],
        "config": {},
        "geocoding": {},
        "session": {},
        "processorCapabilities": {}
      }
    ],
    "paymentMethod": {
      "id": "string",
      "object": "string",
      "card": {
        "networks": {},
        "threeDSecureUsage": {},
        "wallet": {}
      },
      "valu": {},
      "fawry": {},
      "billingDetails": {
        "address": {}
      },
      "type": "card",
      "createdAt": "2025-03-25T12:00:00.000Z"
    },
    "customer": {
      "id": "cus_abc123",
      "name": "Mohamed Ali",
      "email": "customer@example.com",
      "phone": "+20 100 123 4567"
    },
    "nextAction": {
      "type": "redirect_to_url",
      "redirectToUrl": {},
      "displayVoucherDetails": {}
    },
    "metadata": {
      "orderId": "1234",
      "channel": "web"
    },
    "lastPaymentError": {
      "code": "card_declined",
      "declineCode": "insufficient_funds",
      "networkDeclineCode": "string",
      "docUrl": "https://docs.xpay.app/integrate/errors/decline-codes#insufficient_funds",
      "message": "Your card has insufficient funds. Please try a different card.",
      "merchantMessage": "string",
      "adviceCode": "confirm_card_data",
      "param": "string",
      "chargeId": "ch_3MqAaCB4Ot...",
      "paymentMethod": {},
      "paymentMethodType": "card",
      "type": "card_error",
      "processorCode": "string",
      "processorMessage": "string"
    }
  },
  "lineItems": [
    {
      "id": "li_abc123",
      "quantity": 1,
      "price": {},
      "adjustableQuantity": {},
      "amountSubtotal": 200000,
      "amountTotal": 200000,
      "amountDiscount": 0,
      "amountTax": 0,
      "currency": "EGP",
      "description": "Premium Plan - Monthly",
      "presentmentDetails": {}
    }
  ],
  "customFields": [
    {
      "key": "string",
      "label": "string",
      "type": "TEXT",
      "isOptional": true,
      "hasLimits": true,
      "limitType": "AT_MOST",
      "minCharacters": 0,
      "maxCharacters": 0,
      "dropdownOptions": [
        {}
      ],
      "text": {},
      "numeric": {},
      "dropdown": {}
    }
  ],
  "discounts": [
    {
      "id": "string",
      "object": "discount",
      "coupon": {
        "appliesToProductIds": [],
        "metadata": {}
      },
      "promotionCodeId": "string",
      "promotionCodeCode": "string",
      "checkoutSessionId": "string",
      "customerId": "string",
      "start": "string",
      "end": "string"
    }
  ],
  "allowPromotionCodes": true,
  "nameCollection": true,
  "billingAddressCollection": true,
  "shippingAddressCollection": true,
  "phoneNumberCollection": true,
  "feeConfig": {
    "feesPassThrough": true,
    "vatCollectionEnabled": true,
    "vatCollectionRate": 0,
    "source": "session"
  },
  "brandingSettings": {
    "colorMode": "light",
    "borderStyle": "rounded",
    "spacing": "condensed",
    "inputSize": "small",
    "inputStyle": "flat",
    "formLayout": "compact",
    "colors": {
      "primary": "string",
      "primaryForeground": "string",
      "background": "string",
      "foreground": "string",
      "border": "string",
      "input": "string",
      "ring": "string",
      "muted": "string",
      "mutedForeground": "string",
      "accent": "string",
      "accentForeground": "string",
      "destructive": "string"
    },
    "fontFamily": "string"
  },
  "locale": "en",
  "paymentMethodTypes": [
    {
      "type": "string",
      "displayName": "string",
      "category": "string",
      "minTransactionAmount": "string",
      "maxTransactionAmount": "string",
      "requiredCustomerFields": [
        null
      ],
      "supportsRefund": true,
      "supportsPartialRefund": true,
      "supportsPartialCapture": true,
      "paymentConfirmation": "immediate"
    }
  ],
  "paymentMethodConfigurationId": "string",
  "fees": {
    "paymentMethodType": "string",
    "feeAmount": 0,
    "feePercentage": 0,
    "vatAmount": 0,
    "totalAmount": 0,
    "cardInfo": {
      "brand": "string",
      "isOnUs": true,
      "isInternational": true
    }
  },
  "customerUpdate": {
    "address": "auto",
    "name": "auto",
    "shipping": "auto"
  },
  "metadata": {},
  "merchantId": "string",
  "merchantName": "string",
  "merchantLogo": "string",
  "paymentLinkId": "string",
  "livemode": true
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid value for parameter.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#parameter_invalid"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such price: price_abc123",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

Retrieve account GET

Returns the account for the authenticated key: merchant id, display profile, chargeable currencies grouped by payment method type, live activation status, and the key's own type, mode, and permissions. Works with any secret or restricted key, and requires no specific permission. Publishable keys are refused.

Retrieve a checkout session GET

Retrieves an existing checkout session by ID. Returns full session data including clientSecret.