# Docs - Docs: Guides for accepting payments with XPay - [Introduction](/en): Payments for Egypt businesses. Take cards and local methods via API, hosted checkout, or your own UI. - Get Started: Your first 5 minutes with XPay - [Quickstart](/en/get-started/quickstart): Take your first XPay payment in five minutes. No code required. - [Choose your integration](/en/get-started/choose-your-integration): Pick one of four integration patterns based on how much code you want to write. - [Test mode & test cards](/en/get-started/test-mode): Build and test your XPay integration end to end without moving real money. - [Onboarding & KYC](/en/get-started/onboarding): Submit your business for review and unlock live payments. - Features: What XPay does: concepts and dashboard usage - Products: Product catalog, pricing model, and coupons - [Product catalog](/en/features/products/product-catalog): Build your catalog, read a product's full detail page, and archive or delete products you no longer sell. - [Prices](/en/features/products/prices): How XPay models prices: one-time, recurring, customer-set amounts, stock, scheduling, and the seven price status states. - [Coupons and promotion codes](/en/features/products/coupons): Define a discount, attach customer-facing promotion codes to it, and read what redeemed where. - [Payment Links](/en/features/payment-links): Create a shareable URL in the dashboard and accept payments without writing any code. Send the link by email or WhatsApp, post it on social, drop it on a button, or print a QR code. - Customers: Find customers, read their profile, and act on guest grouping and signals - [Customer profile](/en/features/customers/customer-profile): Find a customer in your dashboard, read their full profile, and act on it. - [Guest customers](/en/features/customers/guest-customers): What guest records are, how XPay groups them, and how the Related sections on a profile work. - [Customer signals](/en/features/customers/customer-signals): What each signal on a customer profile means, when it fires, and how to act on it. - Transactions: Payments, refunds, transaction signals, balance and activity - [Payments](/en/features/transactions/payments): Find any payment, read its full lifecycle, refund it, and trace the funds to your payout. - [Refunds](/en/features/transactions/refunds): Issue a refund from the dashboard, read refund state across the dashboard, and understand fees and timing. - [Transaction signals](/en/features/transactions/transaction-signals): What each signal on a payment means, when it fires, and how to act on it. - [Balance and activity](/en/features/transactions/balance-and-activity): Your available and pending balance, and the running record of every payment, refund, fee, and adjustment. - Checkout customization: Branding and payment methods - [Branding](/en/features/checkout-customization/branding): Set your default logo, locale, presets, appearance, colors, and font for every checkout your customers see. - [Payment methods](/en/features/checkout-customization/payment-methods): Configure which payment methods appear on your checkouts, with multiple configurations and a default per merchant. - Account & operations: Team, API keys, payouts, notifications - [Team and roles](/en/features/account-and-operations/team-and-roles): Invite teammates by phone, assign one of seven roles, and manage members and pending invitations. - [API keys](/en/features/account-and-operations/api-keys): Create publishable, secret, and restricted API keys, scope them with the permissions selector, and roll them when needed. - [Payouts and settlement](/en/features/account-and-operations/payouts-and-settlement): How and when XPay disburses your balance to your bank, plus the settlement-method form, schedule view, and the payout batch detail page. - [Notifications](/en/features/account-and-operations/notifications): Communication preferences for your team. Pick which notifications each role receives by email and WhatsApp. - Integrate: Build with XPay: patterns, webhooks, errors, debugging - [Object model](/en/integrate/object-model): How XPay's resources fit together. What you create, what you read, and the two IDs to store on your order record. - Checkout Session: Configure the Checkout Session: line items, customer lifecycle, after-completion, and more. - [Overview](/en/integrate/checkout-session/overview): The Checkout Session is the central object every integration creates. The same shape comes back from POST, GET, the SDK client, and every checkout.session webhook. - [Line items & pricing](/en/integrate/checkout-session/line-items-and-pricing): How `lineItems` work on a Checkout Session: existing prices vs inline `priceData`, fixed and adjustable quantity, custom-amount lines, currency, and the availability gate. - [Customer lifecycle](/en/integrate/checkout-session/customer-lifecycle): Decide who the customer is, what the form collects, and how XPay's customer record evolves across one-time payers and returning customers. - [After completion](/en/integrate/checkout-session/after-completion): Send the customer back to your site, or let XPay show a hosted thank-you page. Plus how to handle failed payments and why the webhook is the source of truth. - [Advanced configuration](/en/integrate/checkout-session/advanced-configuration): Submit button text, locale, branding, payment-method restrictions, promotion codes, fees, expiration, and metadata. Everything else you can set on a Checkout Session. - [Refunds](/en/integrate/refunds): Reverse a successful payment in full or in part. One POST against the Payment Intent or Charge, plus an optional GET to read it back. - Integration patterns: Four ways to take a payment, ranked by effort - [Payment Links (no-code)](/en/integrate/integration-patterns/payment-links): Use the URL your merchant created in the dashboard. Embed it on a site, drop it in an email, print a QR code, or listen for paid events with a webhook. - [Hosted Checkout](/en/integrate/integration-patterns/hosted-checkout): Server-only integration. Create a Checkout Session, redirect the customer to XPay's hosted page, confirm with a webhook. - [Drop-in](/en/integrate/integration-patterns/drop-in): Server plus a few lines of frontend. Open XPay's checkout in a modal or inline iframe on your domain. The customer never leaves your site. - [Elements](/en/integrate/integration-patterns/elements): Build your own checkout UI. Your form collects customer details, our PaymentElement handles cards and local methods, your code calls confirm(). Maximum control. - Webhooks: Receive events, verify them, retry on failure - [Setting up an endpoint](/en/integrate/webhooks/setting-up-an-endpoint): Add a webhook endpoint in the dashboard, pick the events you care about, and store the signing secret on your server. - [Verifying signatures](/en/integrate/webhooks/verifying-signatures): Confirm every webhook is really from XPay before you trust it. HMAC-SHA256 over the raw body, with a 5-minute replay window. - [Replaying & retries](/en/integrate/webhooks/replaying-and-retries): How XPay automatically retries failed deliveries, and how to manually resend an event from the Workbench. - [Local development](/en/integrate/webhooks/local-development): Tunnel webhook deliveries to your laptop while you build. Build, fix, replay, repeat. - [Event reference](/en/integrate/webhooks/event-reference): Every webhook event XPay can deliver, when it fires, and the object it carries. - Errors: How XPay surfaces failures: the API envelope, payment failures on a resource, and the full code reference - [Introduction](/en/integrate/errors/introduction): XPay surfaces failures in two distinct places: the response body of an API call you made, and the lastPaymentError field on a payment that failed. Pick the surface that matches your problem. - [API errors](/en/integrate/errors/api-errors): The error envelope returned by every failed API call. Three error types, the fields they carry, and the handler pattern. - [API error codes](/en/integrate/errors/api-error-codes): Every code returned in `error.code` on a failed API call, grouped by domain. Each entry's URL is the value of `error.doc_url`. - [Payment errors](/en/integrate/errors/payment-errors): When a customer's payment fails, the error sits on the Payment Intent's lastPaymentError field. The shape, the adviceCode, and how to split copy between your customer and your team. - [Payment error codes](/en/integrate/errors/payment-error-codes): Every value of `lastPaymentError.code`, grouped by domain. Each entry's URL is the value of `lastPaymentError.docUrl`. - [Decline codes](/en/integrate/errors/decline-codes): Issuer-level decline reasons returned in `lastPaymentError.declineCode`. Plus how to read the raw `networkDeclineCode` passthrough. - Workbench: Inspect resources, watch events, read logs, check health, live in the dashboard - [Introduction](/en/integrate/workbench/introduction): The Workbench is a slide-up drawer that lives in the dashboard. Inspect resources, watch events, read logs, and check health without leaving the page. - [Inspector](/en/integrate/workbench/inspector): Paste any XPay ID and see the full graph of related resources, the JSON payload, the events that fired on it, and the request logs around it. - [Events panel](/en/integrate/workbench/events-panel): Watch every webhook event your account has produced, drill into deliveries and attempts, and replay any of them. - [Logs panel](/en/integrate/workbench/logs-panel): Every API request your account has made: method, path, status, headers, body, response. Filter by error, by resource, by source. - [Health panel](/en/integrate/workbench/health-panel): Spot the patterns in your account's recent failures. Errors grouped by root cause, sorted by frequency, with a sample log per group. - [Idempotency](/en/integrate/idempotency): Safely retry write requests with an Idempotency-Key. XPay records the first result and replays it, so a retried call never repeats the side effect. - [AI agents](/en/integrate/ai-agents): Every page on this site is available as plain markdown, plus a full-site export and the OpenAPI spec. Point your coding assistant at these instead of scraping HTML. - API Reference: Complete reference for every XPay endpoint and resource. - [Introduction](/en/api-reference): Complete reference for every XPay endpoint and resource. - **Checkout Sessions** - [Create a checkout session](/en/api-reference/checkout-sessions/createCheckoutSession): Creates a new checkout session for hosted or embedded checkout. Returns a session with a URL to redirect customers for payment. - [Retrieve a checkout session](/en/api-reference/checkout-sessions/getCheckoutSession): Retrieves an existing checkout session by ID. Returns full session data including clientSecret. - [Update a checkout session](/en/api-reference/checkout-sessions/updateMerchantCheckoutSession): Updates an open checkout session. Immutable fields (mode, uiMode, submitType, currency, expiresAfterMinutes) cannot be changed after creation. - [Expire a checkout session](/en/api-reference/checkout-sessions/expireCheckoutSession): Expires an open checkout session. Expired sessions cannot be used for payment. - **Customers** - [List customers](/en/api-reference/customers/listCustomers): 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). - [Create a customer](/en/api-reference/customers/createCustomer): Creates a new customer record. At least one contact method (email or phone) is required. Customers are environment-specific (test vs live database). - [Get customer by ID](/en/api-reference/customers/getCustomer): Retrieves customer lifecycle information (id, type, name, email, phone, address, metadata). Response shape is identical to the `customer.*` webhook payload. For transaction counts + payment methods, call `GET /customers/:id/stats`. - **Payment Links** - [List payment links](/en/api-reference/payment-links/listPaymentLinks): Lists payment links with filtering, pagination, and search. Features: - Filter by active status - Search by product name, description, or unit label - Filter by amount (equal, between, greater, less) - Filter by date (last period, equal, between, after, before) - Pagination support - [Create a payment link](/en/api-reference/payment-links/createPaymentLink): Creates a new payment link — a shareable URL you can send to customers. Features: - Supports multiple line items with adjustable quantities - Custom fields for collecting additional customer information - After-completion settings (redirect or hosted confirmation) - Automatic amount calculation from line items - Validates currency consistency across line items - [Get a payment link by ID](/en/api-reference/payment-links/getPaymentLink): Retrieves a payment link with all related data including: - Line items with prices and products - Custom fields with dropdown options - After-completion settings - [Update a payment link](/en/api-reference/payment-links/updatePaymentLink): Partially updates an existing payment link. Only provided fields will be updated. Features: - Partial updates: only send fields you want to update - Updates line items with adjustable quantities (if provided, replaces all existing line items) - Updates custom fields (if provided, replaces all existing custom fields) - Updates after-completion settings (if provided, replaces existing settings) - Recalculates amount from line items when line items are updated - Validates currency consistency across line items when line items are updated Notes: - If `lineItems` is provided, all existing line items are replaced - If `customFields` is provided, all existing custom fields are replaced - If `customFields` is an empty array, all custom fields are removed - `expiresAt` can be set to `null` to remove expiration - **Products** - [Get product by ID](/en/api-reference/products/getProduct): Retrieves product information including all associated prices. Response shape is identical to the `product.*` webhook payload. For per-price usage counts, call `GET /products/:id/stats`. - [Update product](/en/api-reference/products/updateProduct): Updates product information. Can update product data fields, default price, and image. - The `defaultPrice` field should be the ID of the Price object to set as the default price for this product - The `image` field should be a URL string (use the `/upload-url` endpoint to get a one-time upload URL first) - [Delete product](/en/api-reference/products/deleteProduct): Deletes a product and cascade-deletes all of its prices in one transaction. Fails if any of the product's prices have ever been referenced by a line item — in that case the product must be archived instead. - [List products](/en/api-reference/products/listProducts): Lists products with search and filters. Supports: - Active filter (`active=true/false`) - Metadata filter (JSON string) - Search in `name`, `description`, and `unitLabel` fields - Pagination - [Create a product](/en/api-reference/products/createProduct): Creates a new product. Optionally includes: - An image URL (use the `/upload-url` endpoint to get a one-time upload URL first) - A default price object which will be set as the default price for this product - **Prices** - [Create a price](/en/api-reference/prices/createPrice): Creates a new Price for an existing Product. - [Update a price](/en/api-reference/prices/updatePrice): Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged. - [Delete a price](/en/api-reference/prices/deletePrice): Deletes a price. Only prices that have never been referenced by a line item can be deleted — once a price has been used in any checkout session or payment link, archive it instead. If the price is set as the default price for a product, the default price reference will be cleared. - **Refunds** - [List refunds](/en/api-reference/refunds/listRefunds): Lists refunds with optional filters for charge and pagination. - [Create a refund](/en/api-reference/refunds/createRefund): Creates a full or partial refund for a successful charge. Target: provide EXACTLY ONE of `chargeId` or `paymentIntentId`. When `paymentIntentId` is supplied the server resolves it to the unique succeeded charge under that intent; the request is rejected if the intent has zero or multiple succeeded charges. Features: - Full or partial refunds - Ledger reversal (double-entry bookkeeping) - Balance updates (debits available funds) - Updates `charge.amountRefunded` - Updates `paymentIntent.amountRefunded` Refund behaviour: - Hits available balance immediately (no hold period) - Creates negative balance transactions - Reverses the original charge's ledger entries - Platform keeps fees (business decision) - [Get refund by ID](/en/api-reference/refunds/getRefund): Retrieves a refund with all details including ledger info. - **Objects** - [Balance Transaction](/en/api-reference/objects/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. - [Charge](/en/api-reference/objects/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. - [Checkout Session](/en/api-reference/objects/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. - [Coupon](/en/api-reference/objects/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. To give customers a redeemable code (e.g. `SUMMER25`) instead of applying the Coupon directly, create one or more Promotion Codes that map to this Coupon — a single Coupon can have many Promotion Codes, each with its own per-code restrictions. You receive `coupon.*` and `promotion_code.*` webhook events for each as they are created or changed. - [Customer](/en/api-reference/objects/customer): A Customer represents a buyer you do business with. Use Customers to save payment methods for reuse, track lifetime spend, attach metadata for your CRM, and group related Charges, Refunds, and Checkout Sessions under a single record. You can identify a Customer by their email or by a stable external ID from your own system and reference them on any future payment. - [Discount](/en/api-reference/objects/discount): A Discount records a single application of a Coupon to a specific Checkout Session, PaymentIntent, or Customer. Where a Coupon is the reusable template, a Discount captures the concrete redemption: which Coupon was applied, when it became active, when it expires, and (when applicable) which Promotion Code the customer entered to claim it. - [Payment Intent](/en/api-reference/objects/payment-intent): 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. - [Payment Link](/en/api-reference/objects/payment-link): A Payment Link is a shareable URL you can send to a customer to collect a single payment or set up a subscription, without writing any checkout code. Open the URL in any browser and we render the hosted checkout, collect payment details, and process the payment. Use Payment Links for one-off invoices, social-media checkout, in-person QR codes, or anywhere you need a checkout page without integrating the SDK. - [Price](/en/api-reference/objects/price): A Price defines what a Product costs: the unit amount, currency, and (for subscriptions) billing interval. A single Product can have many Prices, letting you offer the same item in multiple currencies, tiers, or billing models without duplicating your catalog. Reference a Price by ID when creating Checkout Sessions, Payment Links, or line items, and the customer is charged according to what the Price defines. - [Product](/en/api-reference/objects/product): A Product represents a good or service you sell. Products carry only descriptive information (name, description, images), while their pricing is described separately by Price objects. A single Product can have many Prices: for example, the same digital course offered in EGP and USD, or at different tiers. Use Products to model your catalog and Prices to model how each is sold. - [Promotion Code](/en/api-reference/objects/promotion-code): A Promotion Code is a customer-facing alphanumeric code (for example `SUMMER25`) that maps to a single Coupon. One Coupon can have many Promotion Codes, letting you run different campaigns (email vs. social, customer-specific codes, regional codes, …) against the same underlying discount. Customers enter the code at checkout to redeem the Coupon's discount. Promotion Codes can carry their own restrictions on top of the Coupon — a per-code redemption cap, an expiry date, or a binding to a specific Customer. You receive `promotion_code.created` and `promotion_code.updated` webhook events whenever a code is created or modified. - [Refund](/en/api-reference/objects/refund): A Refund returns funds from a successful Charge back to the customer's original payment method. Refunds can be full or partial, and a single Charge can be refunded multiple times up to its original amount. The Refund's `status` reflects the processor's progress as the money makes its way back: `pending` while in flight, `succeeded` once the funds have been returned, or `failed` if the processor rejected the request. - SDK: Client libraries: types, methods, and components - [Introduction](/en/sdk): Reference for the XPay client SDKs. The integrate guides cover how to use them; this tab lists every public symbol. - [@xpayeg/sdk](/en/sdk/sdk-js): The browser JavaScript SDK. Reference for every public export, method signature, and option type. - [@xpayeg/react](/en/sdk/sdk-react): The React SDK. XPayProvider, hooks, and components built on top of @xpayeg/sdk. - [Mobile](/en/sdk/mobile): Native iOS, Android, and React Native SDKs are not yet shipped. ## Machine-readable sources - [OpenAPI specification](https://docs.xpay.app/openapi.json): the complete machine-readable API (every endpoint, object, field, and enum). - [Full documentation](https://docs.xpay.app/llms-full.txt): every page on this site as a single markdown file. - Any page listed above also serves markdown directly — append `.md` or `.mdx` to its URL, or request it with `Accept: text/markdown`.