Checkout Session
A Checkout Session represents your customer's session as they pay on an xpay-hosted checkout page. Create a new Session each time a customer begins a checkout: attach line items, customer details, or a PaymentIntent, then redirect the customer to the Session's `url` to begin payment. As the customer progresses, the Session's `status` and `paymentStatus` update; once payment succeeds, the Session contains references to the resulting Customer and PaymentIntent. Sessions expire 24 hours after creation if not completed.
{
"id": "string",
"object": "checkout.session",
"createdAt": "string",
"updatedAt": "string",
"mode": "payment",
"uiMode": "hosted",
"submitType": "PAY",
"customerCreation": "always",
"status": "open",
"paymentStatus": "paid",
"currency": "EGP",
"amountSubtotal": 0,
"amountTotal": 0,
"totalDetails": {
"amountDiscount": 0,
"amountShipping": 0,
"amountTax": 0,
"amountPlatformFee": 0,
"amountCollectedVat": 0
},
"presentmentDetails": {
"amount": 80000,
"currency": "KWD",
"exchangeRate": 168.2,
"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": "string",
"object": "payment_intent",
"checkoutSessionId": "string",
"checkoutSession": {
"id": "string",
"object": "checkout.session",
"createdAt": "string",
"updatedAt": "string",
"mode": "payment",
"uiMode": "hosted",
"submitType": "PAY",
"customerCreation": "always",
"status": "open",
"paymentStatus": "paid",
"currency": "EGP",
"amountSubtotal": 0,
"amountTotal": 0,
"totalDetails": {},
"presentmentDetails": {},
"afterCompletion": {},
"cancelUrl": "string",
"url": "string",
"clientSecret": "string",
"expiresAt": "string",
"customerId": "string",
"customer": {
"metadata": {}
},
"customerDetails": {},
"paymentIntentId": "string",
"paymentIntent": {
"checkoutSession": {},
"shipping": {},
"amountDetails": {},
"latestCharge": {},
"charges": [],
"paymentMethod": {},
"customer": {},
"nextAction": {},
"metadata": {},
"lastPaymentError": {}
},
"lineItems": [
{}
],
"customFields": [
{}
],
"discounts": [
{}
],
"allowPromotionCodes": true,
"nameCollection": true,
"billingAddressCollection": true,
"shippingAddressCollection": true,
"phoneNumberCollection": true,
"feeConfig": {},
"brandingSettings": {},
"locale": "en",
"paymentMethodTypes": [
{}
],
"paymentMethodConfigurationId": "string",
"fees": {},
"customerUpdate": {},
"metadata": {},
"merchantId": "string",
"merchantName": "string",
"merchantLogo": "string",
"paymentLinkId": "string",
"livemode": true
},
"amount": 0,
"amountCapturable": 0,
"amountReceived": 0,
"currency": "EGP",
"status": "string",
"createdAt": "2025-03-25T12:00:00.000Z",
"updatedAt": "2025-03-25T12:00:00.000Z",
"clientSecret": "string",
"captureMethod": "string",
"confirmationMethod": "string",
"description": "string",
"receiptEmail": "string",
"canceledAt": "2025-03-25T12:00:00.000Z",
"shipping": {
"address": {},
"name": "string",
"phone": "string"
},
"amountDetails": {
"productAmount": 0,
"tax": {},
"platformFees": {},
"tip": 0,
"discount": 0
},
"presentmentDetails": {
"amount": 80000,
"currency": "KWD",
"exchangeRate": 168.2,
"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": {},
"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": "string",
"name": "string",
"email": "string",
"phone": "string"
},
"nextAction": {
"type": "string",
"redirectToUrl": {}
},
"metadata": {},
"lastPaymentError": {
"code": "string",
"declineCode": "string",
"networkDeclineCode": "string",
"docUrl": "string",
"message": "string",
"merchantMessage": "string",
"adviceCode": "string",
"param": "string",
"chargeId": "string",
"paymentMethod": {},
"paymentMethodType": "string",
"type": "string",
"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
}Charge
A Charge represents a single attempt to move money from a customer's payment method to your account. It records what was paid, by whom, through which processor, and the final outcome: `succeeded`, `failed`, or `refunded`. A single PaymentIntent may produce multiple Charges if earlier attempts fail; only the most recent successful Charge actually moves funds, and any subsequent Refunds reference it directly.
Coupon
A Coupon defines a reusable discount you can apply to Checkout Sessions and PaymentIntents. Coupons can grant either a percentage off (`percentOff`) or a fixed amount off (`amountOff`), and can apply once, forever, or repeating for a number of billing cycles. You can also cap how many times a Coupon may be redeemed and when it expires. Coupons are the reusable template. Each concrete application of a Coupon to a customer's purchase is recorded as a Discount.