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.
{
"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": {
"city": "string",
"country": "string",
"line1": "string",
"line2": "string",
"postalCode": "string",
"state": "string"
},
"email": "string",
"name": "string",
"phone": "string"
},
"paymentMethodDetails": {
"type": "string",
"card": {
"brand": "string",
"country": "string",
"expMonth": 0,
"expYear": 0,
"funding": "string",
"last4": "string",
"network": "string",
"fingerprint": "string",
"threeDSecure": {},
"wallet": {}
},
"valu": {
"loanNumber": "string",
"tenure": 0,
"emi": "string",
"downPayment": "string",
"financedAmount": "string",
"firstEmiDueDate": "string",
"lastInstallmentDate": "string"
}
},
"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": {
"id": "pb_xxx",
"object": "payout_batch",
"amount": 0,
"currency": "EGP",
"status": "paid",
"arrivalDate": "string",
"createdAt": "string",
"updatedAt": "string"
},
"paymentIntentId": "string",
"merchantId": "string"
},
"presentmentDetails": {
"amount": 80000,
"currency": "KWD",
"exchangeRate": 168.2,
"exchangeRateId": "exr_3gQWCqaDsihr09Fi5MfwXL"
},
"refunds": [
{
"id": "re_abc123",
"object": "refund",
"amount": 50000,
"chargeId": "ch_xyz789",
"paymentIntentId": "pi_xyz789",
"balanceTransactionId": "string",
"failureBalanceTransactionId": "string",
"externalRefundId": "string",
"createdAt": "2025-03-25T12:00:00.000Z",
"currency": "EGP",
"presentmentDetails": {},
"status": "PENDING",
"reason": "DUPLICATE",
"failureReason": "lost_or_stolen_card",
"pendingReason": "processing",
"description": "string",
"destinationDetails": {
"card": {},
"wallet": {},
"bankTransfer": {},
"kiosk": {}
},
"nextAction": {
"displayDetails": {}
},
"instructionsEmail": "string",
"receiptNumber": "string",
"feeAmount": 0
}
],
"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": {
"countryCode": "US",
"countryName": "United States",
"regionCode": "CA",
"regionName": "California",
"cityName": "Los Angeles"
}
},
"session": {
"browser": "string",
"browserVersion": "string",
"platform": "string",
"device": "string",
"deviceVendor": "string",
"deviceModel": "string"
},
"processorCapabilities": {
"supportsRefund": true,
"supportsPartialRefund": true
},
"activeHoldId": "hld_xxx",
"settlementModel": "aggregated"
}Balance Transaction
A Balance Transaction records every movement of money in or out of your xpay balance: successful charges, refunds, payouts, processing fees, and adjustments. Each Balance Transaction links back to its `source` (the Charge, Refund, or Payout that produced it) and breaks down `gross`, `fee`, and `net` amounts. Use Balance Transactions to reconcile what was paid into your account against what was settled to your bank.
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.