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*string

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

checkoutSessionId?|

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

checkoutSession?|null

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.

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.

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.

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?|null

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

amountDetails?|null

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

presentmentDetails?|null

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?|null

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?|null

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

customer?|null

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

nextAction?|null

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

metadata*

Custom key/value pairs you attached when creating or updating the PaymentIntent. Useful for reconciling with your own systems. Empty object if none.

lastPaymentError?|null

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

{
  "id": "pi_3MqAaCB4Otk1z2A30vXyz9aB",
  "object": "payment_intent",
  "checkoutSessionId": "cs_test_a1b2c3d4",
  "checkoutSession": {
    "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": {},
      "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": {},
    "merchantId": "string",
    "merchantName": "string",
    "merchantLogo": "string",
    "paymentLinkId": "string",
    "livemode": true
  },
  "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": {
      "city": "string",
      "country": "string",
      "line1": "string",
      "line2": "string",
      "postalCode": "string",
      "state": "string"
    },
    "name": "Mohamed Ali",
    "phone": "+20 100 123 4567"
  },
  "amountDetails": {
    "productAmount": 10000,
    "tax": {
      "amount": 1400,
      "rateBps": 1400
    },
    "platformFees": {
      "amount": 500,
      "vatAmount": 70
    },
    "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": {},
      "email": "string",
      "name": "string",
      "phone": "string"
    },
    "paymentMethodDetails": {
      "type": "string",
      "card": {
        "threeDSecure": {},
        "wallet": {}
      },
      "valu": {}
    },
    "outcome": {
      "networkStatus": "string",
      "reason": "string",
      "riskLevel": "string",
      "riskScore": 0,
      "sellerMessage": "string",
      "type": "string"
    },
    "balanceTransaction": {
      "id": "txn_abc123",
      "object": "balance_transaction",
      "amount": 22604,
      "availableOn": "string",
      "createdAt": "string",
      "currency": "EGP",
      "description": "string",
      "fee": 912,
      "net": 21692,
      "feeDetails": [
        {}
      ],
      "status": "AVAILABLE",
      "type": "CHARGE",
      "reportingCategory": "string",
      "exchangeRate": 0,
      "source": "string",
      "payoutBatch": {},
      "paymentIntentId": "string",
      "merchantId": "string"
    },
    "presentmentDetails": {
      "amount": 80000,
      "currency": "KWD",
      "exchangeRate": 168.21,
      "exchangeRateId": "exr_3gQWCqaDsihr09Fi5MfwXL"
    },
    "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": "https://shop.merchant.com",
    "merchantDomain": "merchant.com",
    "processorCapabilities": {
      "supportsRefund": true,
      "supportsPartialRefund": true
    },
    "activeHoldId": "hld_xxx",
    "settlementModel": "aggregated"
  },
  "charges": [
    {
      "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"
    }
  ],
  "paymentMethod": {
    "id": "string",
    "object": "string",
    "card": {
      "brand": "string",
      "country": "string",
      "displayBrand": "string",
      "expMonth": 0,
      "expYear": 0,
      "fingerprint": "string",
      "funding": "string",
      "last4": "string",
      "networks": {},
      "regulatedStatus": "string",
      "threeDSecureUsage": {},
      "wallet": {}
    },
    "valu": {
      "loanNumber": "string",
      "tenure": 0,
      "emi": "string",
      "downPayment": "string",
      "financedAmount": "string",
      "firstEmiDueDate": "string",
      "lastInstallmentDate": "string"
    },
    "billingDetails": {
      "address": {},
      "email": "string",
      "name": "string",
      "phone": "string"
    },
    "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": {
      "url": "https://hooks.xpay.app/3ds/redirect/abc123",
      "returnUrl": "https://example.com/checkout/return"
    }
  },
  "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"
  }
}