Expire a checkout session
Expires an open checkout session. Expired sessions cannot be used for payment.
Expires an open checkout session. Expired sessions cannot be used for payment.
Authorization
api-key AuthorizationBearer <token>
API key for merchant integrations. Send as Authorization: Bearer <your key>.
In: header
Path Parameters
id*string
Checkout session ID
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/checkout/sessions/string/expire"{
"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",
"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": {}
},
"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": {},
"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": {}
},
"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": "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 checkout_session: cs_test_a1b2c3d4",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "invalid_request_error",
"code": "resource_invalid_state",
"message": "Cannot expire a checkout session that is already completed or expired.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_invalid_state"
},
"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"
}Update a checkout session PATCH
Updates an open checkout session. Immutable fields (mode, uiMode, submitType, currency, expiresAfterMinutes) cannot be changed after creation.
List customers GET
Lists customers with search and pagination. Returns only essential fields: id, createdAt, name, phone, email, and latestPaymentMethod. Search supports customer ID, name, email, or phone (supports comma-separated terms).