Payment Intent — XPay docs

A PaymentIntent tracks the full lifecycle of collecting one payment from your customer: from creation, through authorization and 3-D Secure, to capture and final outcome. We recommend creating one PaymentIntent per order: you can inspect its history of Charge attempts, watch its `status` as it transitions, and reference the successful Charge it ultimately produces. PaymentIntents are the object that the hosted Checkout and xpay.js drive on the client to complete a payment.

A PaymentIntent tracks the full lifecycle of collecting one payment from your customer: from creation, through authorization and 3-D Secure, to capture and final outcome. We recommend creating one PaymentIntent per order: you can inspect its history of Charge attempts, watch its status as it transitions, and reference the successful Charge it ultimately produces. PaymentIntents are the object that the hosted Checkout and xpay.js drive on the client to complete a payment.

id*string

Unique identifier for this PaymentIntent. Always prefixed with pi_.

object*"payment_intent"

String identifying the object type. Always payment_intent for this resource.

Value in

"payment_intent"

checkoutSessionId*|

ID of the CheckoutSession that created this PaymentIntent. null for PaymentIntents created directly via the API without a session.

amount*number

Amount the customer is being charged, in the smallest currency unit of currency (e.g. piasters for EGP — 10000 = 100 EGP).

amountCapturable*number

Amount that can still be captured for this PaymentIntent, in the smallest currency unit. Non-zero only when captureMethod is manual and the payment has been authorized but not yet captured. Drops to 0 once captured (fully or partially).

amountReceived*number

Amount actually received from the customer so far, in the smallest currency unit. Equals amount after a successful capture; 0 for payments that haven't reached SUCCEEDED.

currency*string

ISO 4217 currency code this payment is denominated in.

Value in

"EGP"
"USD"
"EUR"
"GBP"
"SAR"
"AED"
"QAR"
"KWD"
"JOD"
"OMR"
"BHD"
"LYD"
"AUD"
"CAD"
"CNY"

status*string

Lifecycle status. Combines the raw processor state with refund state, so values like REFUNDED, PARTIALLY_REFUNDED, UNCAPTURED, and FAILED may appear in addition to the base processor states.

Value in

"REQUIRES_PAYMENT_METHOD"
"REQUIRES_CONFIRMATION"
"REQUIRES_ACTION"
"PROCESSING"
"UNCAPTURED"
"CANCELED"
"SUCCEEDED"
"FAILED"
"REFUNDED"
"PARTIALLY_REFUNDED"
"AMOUNT_CAPTURABLE_UPDATED"
"PAYMENT_FAILED"

createdAt*string

Created timestamp (ISO 8601)

updatedAt*string

Updated timestamp (ISO 8601)

clientSecret*string

Secret used by the SDK to confirm the payment from the customer's browser. Do NOT log this or share it with any party other than the customer. Each PaymentIntent has one client secret for its lifetime.

captureMethod*string

When to capture funds from the customer. automatic (default) captures immediately on successful confirmation. manual only authorizes — call the capture endpoint later (within 7 days) to actually move the money.

confirmationMethod*string

How the PaymentIntent moves out of REQUIRES_CONFIRMATION. automatic (default) confirms as soon as a payment method is attached. manual requires you to call confirm explicitly.

description*|

Arbitrary description you can attach when creating the PaymentIntent. Shown in the dashboard and useful for reconciling with your own systems. null if not provided.

receiptEmail*|

Email to send the receipt to once the payment succeeds. null if no receipt email was set.

canceledAt*|

ISO 8601 timestamp of when this PaymentIntent was canceled. null if it was never canceled.

shipping*|

Shipping address and recipient details for this payment. null if no shipping was collected.

amountDetails*|

Breakdown of amount into product amount, tax, platform fees, tip, and discount. null for legacy payments without itemized breakdown.

presentmentDetails*|

Mirror of amount / currency in the currency the customer actually saw at checkout, when different from the settlement currency. null when customer paid in the same currency.

latestCharge*|

The most recent Charge attempt for this PaymentIntent. null if no Charge has been attempted yet.

charges*array<>

All Charge attempts for this PaymentIntent, sorted by creation time ascending (oldest first). Each retry adds a new Charge. Empty array if no attempts have been made yet.

paymentMethod*|

Payment method attached to this PaymentIntent. null before a method is attached or after a failure clears it.

customer*|

The Customer this payment belongs to. null if no Customer is associated.

nextAction*|

Action the customer must take to advance the payment (e.g. complete 3-D Secure). null when no further action is needed.

metadata*|array<unknown>

Custom metadata attached to this payment, including JSON arrays inherited from checkout. Useful for reconciling with your own systems. Empty object if none.

lastPaymentError*|

Details of the most recent failed payment attempt for this PaymentIntent. null if no attempts have failed.

checkoutSession*|

The CheckoutSession that created this payment, or null if the payment was not created via a session. The session's own paymentIntent field is not included here to keep the response self-contained.

{  "id": "string",  "object": "payment_intent",  "checkoutSessionId": "string",  "amount": 0,  "amountCapturable": 0,  "amountReceived": 0,  "currency": "EGP",  "status": "REQUIRES_PAYMENT_METHOD",  "createdAt": "string",  "updatedAt": "string",  "clientSecret": "string",  "captureMethod": "string",  "confirmationMethod": "string",  "description": "string",  "receiptEmail": "string",  "canceledAt": "string",  "shipping": {    "address": {      "city": "string",      "country": "string",      "line1": "string",      "line2": "string",      "postalCode": "string",      "state": "string"    },    "name": "string",    "phone": "string"  },  "amountDetails": {    "productAmount": 0,    "tax": {      "amount": 0,      "rateBps": 0    },    "platformFees": {      "amount": 0,      "vatAmount": 0    },    "tip": 0,    "discount": 0  },  "presentmentDetails": {    "amount": 0,    "currency": "EGP",    "exchangeRate": 0,    "exchangeRateId": "string"  },  "latestCharge": {    "id": "string",    "object": "charge",    "amount": 0,    "amountCaptured": 0,    "amountRefunded": 0,    "currency": "EGP",    "createdAt": "2019-08-24T14:15:22Z",    "status": "SUCCEEDED",    "paid": true,    "refunded": true,    "captured": true,    "capturedAt": "2019-08-24T14:15:22Z",    "failureCode": "string",    "failureMessage": "string",    "receiptUrl": "string",    "receiptEmail": "string",    "billingDetails": {      "address": {},      "email": "string",      "name": "string",      "phone": "string"    },    "paymentMethodDetails": {      "type": "string",      "card": {},      "valu": {},      "fawry": {}    },    "outcome": {      "networkStatus": "string",      "reason": "string",      "riskLevel": "string",      "riskScore": 0,      "sellerMessage": "string",      "type": "string"    },    "balanceTransaction": {      "id": "string",      "object": "balance_transaction",      "amount": 0,      "availableOn": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "currency": "EGP",      "description": "string",      "fee": 0,      "net": 0,      "feeDetails": [        null      ],      "status": "AVAILABLE",      "type": "CHARGE",      "reportingCategory": "string",      "exchangeRate": 0,      "source": "string",      "payoutBatch": {},      "paymentIntentId": "string",      "merchantId": "string"    },    "presentmentDetails": {      "amount": 0,      "currency": "EGP",      "exchangeRate": 0,      "exchangeRateId": "string"    },    "refunds": [      {}    ],    "paymentIntentId": "string",    "paymentMethodId": "string",    "calculatedStatementDescriptor": "string",    "disputed": true,    "externalChargeId": "string",    "config": {      "vatCollectionEnabled": true,      "vatCollectionRate": 0,      "collectedVatAmount": 0,      "platformFeePassThrough": true,      "merchantFeeDeduction": 0    },    "geocoding": {      "ipAddress": "string",      "location": {}    },    "session": {      "browser": "string",      "browserVersion": "string",      "platform": "string",      "device": "string",      "deviceVendor": "string",      "deviceModel": "string"    },    "merchantOrigin": "string",    "merchantDomain": "string",    "processorCapabilities": {      "supportsRefund": true,      "supportsPartialRefund": true    },    "activeHoldId": "string",    "settlementModel": "aggregated"  },  "charges": [    {      "id": "string",      "object": "charge",      "amount": 0,      "amountCaptured": 0,      "amountRefunded": 0,      "currency": "EGP",      "createdAt": "2019-08-24T14:15:22Z",      "status": "SUCCEEDED",      "paid": true,      "refunded": true,      "captured": true,      "capturedAt": "2019-08-24T14:15:22Z",      "failureCode": "string",      "failureMessage": "string",      "receiptUrl": "string",      "receiptEmail": "string",      "billingDetails": {},      "paymentMethodDetails": {},      "outcome": {},      "balanceTransaction": {        "feeDetails": []      },      "presentmentDetails": {},      "refunds": [        null      ],      "paymentIntentId": "string",      "paymentMethodId": "string",      "calculatedStatementDescriptor": "string",      "disputed": true,      "externalChargeId": "string",      "config": {},      "geocoding": {},      "session": {},      "merchantOrigin": "string",      "merchantDomain": "string",      "processorCapabilities": {},      "activeHoldId": "string",      "settlementModel": "aggregated"    }  ],  "paymentMethod": {    "id": "string",    "object": "payment_method",    "card": {      "brand": "string",      "country": "string",      "displayBrand": "string",      "expMonth": 0,      "expYear": 0,      "fingerprint": "string",      "funding": "string",      "last4": "string",      "networks": {        "available": []      },      "regulatedStatus": "string",      "threeDSecureUsage": {},      "wallet": {}    },    "valu": {      "loanNumber": "string",      "tenure": 0,      "emi": "string",      "downPayment": "string",      "financedAmount": "string",      "firstEmiDueDate": "string",      "lastInstallmentDate": "string"    },    "fawry": {      "fawryRefNumber": "string",      "paymentReferenceNumber": "string",      "paymentMethod": "string",      "paymentTime": 0,      "expiresAt": "2019-08-24T14:15:22Z"    },    "billingDetails": {      "address": {},      "email": "string",      "name": "string",      "phone": "string"    },    "type": "card",    "createdAt": "2019-08-24T14:15:22Z"  },  "customer": {    "id": "string",    "name": "string",    "email": "string",    "phone": "string"  },  "nextAction": {    "type": "redirect_to_url",    "redirectToUrl": {      "url": "string",      "returnUrl": "string"    },    "displayVoucherDetails": {      "provider": "string",      "reference": "string",      "expiresAt": "2019-08-24T14:15:22Z",      "instructions": "string",      "hostedVoucherUrl": "string"    }  },  "metadata": {    "property1": null,    "property2": null  },  "lastPaymentError": {    "code": "string",    "declineCode": "string",    "networkDeclineCode": "string",    "docUrl": "string",    "message": "string",    "merchantMessage": "string",    "adviceCode": "confirm_card_data",    "param": "string",    "chargeId": "string",    "paymentMethod": {      "id": "string",      "type": "string",      "card": {},      "billingDetails": {}    },    "paymentMethodType": "string",    "type": "api_error",    "processorCode": "string",    "processorMessage": "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": {      "amountDiscount": 0,      "amountShipping": 0,      "amountTax": 0,      "amountPlatformFee": 0,      "amountCollectedVat": 0    },    "presentmentDetails": {      "amount": 0,      "currency": "EGP",      "exchangeRate": 0,      "exchangeRateId": "string",      "amountSubtotal": 0,      "amountTotal": 0,      "amountDiscount": 0,      "amountCollectedVat": 0,      "amountPlatformFee": 0,      "amountTax": 0    },    "afterCompletion": {      "type": "redirect",      "redirect": {},      "hostedConfirmation": {}    },    "cancelUrl": "string",    "url": "string",    "clientSecret": "string",    "expiresAt": "string",    "isExpired": true,    "customerId": "string",    "customer": {      "id": "string",      "type": "guest",      "name": "string",      "email": "string",      "phone": "string",      "address": {},      "shipping": {},      "metadata": {}    },    "customerDetails": {      "name": "string",      "email": "string",      "phone": "string",      "billingDetails": {},      "shipping": {}    },    "paymentIntentId": "string",    "lineItems": [      {}    ],    "customFields": [      {        "dropdownOptions": []      }    ],    "discounts": [      {}    ],    "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": {},      "fontFamily": "string"    },    "locale": "en",    "paymentMethodTypes": [      {        "requiredCustomerFields": []      }    ],    "paymentMethodConfigurationId": "string",    "fees": {      "paymentMethodType": "string",      "feeAmount": 0,      "feePercentage": 0,      "vatAmount": 0,      "totalAmount": 0,      "cardInfo": {}    },    "customerUpdate": {      "address": "auto",      "name": "auto",      "shipping": "auto"    },    "metadata": {      "property1": null,      "property2": null    },    "merchantId": "string",    "merchantName": "string",    "merchantLogo": "string",    "paymentLinkId": "string",    "livemode": true  }}