docs

Introduction

Complete reference for every XPay endpoint and resource.

Retrieve account GET

Returns the account for the authenticated key: merchant id, display profile, chargeable currencies grouped by payment method type, live activation status, and the key's own type, mode, and permissions. Works with any secret or restricted key, and requires no specific permission. Publishable keys are refused.

Create a checkout session POST

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 GET

Retrieves an existing checkout session by ID. Returns full session data including clientSecret. Webhooks report status changes: do not poll this endpoint. See https://docs.xpay.app/en/integrate/webhooks/checking-session-status

Update a checkout session PATCH

Updates an open checkout session. Immutable fields (mode, uiMode, submitType, currency, expiresAfterMinutes) cannot be changed after creation.

Expire a checkout session POST

Expires an open checkout session. Expired sessions cannot be used for payment.

List customers GET

Lists customers with search and pagination. Returns only essential fields: id, createdAt, name, phone, email, and latestPaymentMethod. Search supports customer ID, name, email, phone or external ID (comma-separated terms).

Create a customer POST

Creates a new customer record. At least one of email, phone or externalId is required. Customers are environment-specific (test vs live database).

Get customer by external ID GET

Retrieves a customer by the `externalId` you gave it, such as the user ID in your system. Same response as `GET /customers/:id`.

Get customer by ID GET

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`.

Update customer PATCH

Updates customer information.

List invoices GET

Returns invoices, newest first. Filter by status, customer, dates and amounts.

Create an invoice POST

Creates a draft invoice for a customer. A draft can be edited freely and is not visible to the customer until it is finalized.

Preview an invoice POST

Works out the lines, discounts, tax and total of an invoice without saving it. Nothing is created.

Preview an invoice PDF POST

Returns the PDF an invoice with this content would have, without saving it. It is the same document the customer receives, marked as a draft.

Retrieve an invoice GET

Retrieves an invoice with its lines, payment plan and payments.

Update an invoice PATCH

Updates a draft. On a finalized invoice only payment methods, partial payment settings, delivery and metadata can change.

Delete a draft invoice DELETE

Deletes a draft. A finalized invoice cannot be deleted; void it instead.

Download an invoice PDF GET

Returns the invoice as a PDF file. It always shows the invoice as it is now, including payments received. Pass language to get it in another language.

Add lines to a draft invoice POST

Adds up to 50 lines to the end of a draft.

Update lines of a draft invoice POST

Updates up to 50 lines by ID. Fields that are not sent keep their value.

Remove lines from a draft invoice POST

Removes up to 50 lines by ID.

Finalize an invoice POST

Turns a draft into an open invoice: assigns its number, freezes its amounts and the customer's details, and makes it payable. This cannot be undone.

Send an invoice POST

Sends the invoice to the customer by email, SMS or both, or sends it again. A draft is finalized first. The body is optional: without it the invoice's saved delivery settings are used. Sending is queued, so the response returns before the message is delivered. In test mode nothing reaches the customer.

Send a reminder for an invoice POST

Reminds the customer of an open invoice now, on your reminder channels. Automatic reminders pause for a day afterwards.

Void an invoice POST

Cancels an open or uncollectible invoice that has received no payment. The invoice keeps its number.

Mark an invoice uncollectible POST

Writes off an open invoice. It can still be paid later.

Change the due date of an invoice POST

Moves the due date of a draft or open invoice that has no payment plan.

Duplicate an invoice POST

Creates a new draft with the same customer, lines and options.

Replace the link of an invoice POST

Creates a new link to the invoice page. The old link stops working at once.

Set the payment plan of an invoice PUT

Splits the amount due into dated installments, replacing any existing plan. Send an empty list to remove the plan. On an issued invoice, installments that are already paid cannot change.

Attach a payment to an invoice POST

Records money you received outside XPay, such as cash or a cheque, and adds it to the invoice's payments. No money moves. An amount above what remains becomes credit for the customer.

List the payments of an invoice GET

Returns every payment on the invoice, newest first, online and recorded.

Retrieve an invoice payment GET

Retrieves one payment made on an invoice.

Remove a recorded payment DELETE

Removes a payment you recorded by mistake, so the invoice is owed again. Online payments cannot be removed: refund them instead.

Send the receipt of a payment again POST

Emails the receipt of a received payment to the customer again. The first receipt is sent automatically when the payment arrives. Live mode only: receipts are not emailed in test mode.

List a customer's balance transactions GET

Returns every change to the customer's balance, newest first: credit given, credit used on an invoice, and credit returned.

Adjust a customer's balance POST

Gives the customer credit or takes it back. A negative amount is credit, which the customer's next invoice uses up.

List credit notes GET

Returns credit notes, newest first. Filter by invoice or customer.

Issue a credit note POST

Lowers the amount of an issued invoice. The credit first reduces what the customer still owes. For any part that was already paid, say where it goes: refundAmount, creditAmount and outOfBandAmount must add up to it.

Preview a credit note POST

Works out the lines, tax and total of a credit note, and how much of it lowers the amount owed, without saving it.

Retrieve a credit note GET

Retrieves a credit note with its lines.

Update a credit note PATCH

Changes the note printed on a credit note, or its metadata. Amounts never change.

Download a credit note GET

Returns the credit note as a PDF file, in the language of its invoice.

Void a credit note POST

Takes a credit note back, so the invoice asks for that amount again. Possible only while the invoice is open.

List payment links GET

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 POST

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 GET

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 PATCH

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

List tax rates GET

Returns the tax rates of the account, active ones first.

Create a tax rate POST

Creates a reusable tax rate. The percentage and the inclusive setting cannot be changed later.

Retrieve a tax rate GET

Retrieves a tax rate by its ID.

Update a tax rate PATCH

Renames, archives or restores a tax rate. The percentage and the inclusive setting cannot be changed.

Get product by external ID GET

Retrieves a product by the `externalId` you gave it, such as your SKU. Same response as `GET /products/:id`.

Get product by ID GET

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 PATCH

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 DELETE

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 GET

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 POST

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

List prices by lookup key GET

Retrieves the prices with the given lookup keys, up to 10. Repeat the parameter for several: `lookupKeys=pro_monthly&lookupKeys=pro_yearly`. A key no price has is left out.

Create a price POST

Creates a new Price for an existing Product.

Update a price PATCH

Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.

Delete a price DELETE

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.

List webhook endpoints GET

Lists all webhook endpoints for the merchant.

Create a webhook endpoint POST

Creates a new webhook endpoint. The response includes the signing secret which is only shown once. Store it securely to verify webhook signatures.

Get a webhook endpoint GET

Retrieves a webhook endpoint by ID.

Update a webhook endpoint PATCH

Updates a webhook endpoint. You can update the URL, description, enabled events, status, or metadata.

Delete a webhook endpoint DELETE

Permanently deletes a webhook endpoint. This cannot be undone.

List refunds GET

Lists refunds with optional filters for charge and pagination.

Create a refund POST

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 GET

Retrieves a refund with all details including ledger info.

Balance Transaction

A movement of money in or out of the merchant balance, including signed gross, fees, net and the source resource.

Charge

A Charge represents one attempt to move money from a customer's payment method. PaymentIntent retries create separate charges; refunds reference the charge they reverse.

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

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.

Credit Note

A Credit Note lowers the amount of an issued invoice without changing the invoice itself. It first reduces what the customer still owes (prePaymentAmount). Anything beyond that was already paid (postPaymentAmount) and goes back to the customer by a refund, as customer credit, or outside XPay. Refunding a payment of an invoice directly also writes its credit note.

Customer Balance Transaction

A Customer Balance Transaction is one change to a customer's balance. The balance always equals the sum of its transactions. A negative balance is credit, used up by the customer's next invoice.

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. Give a Customer your own ID as `externalId` and pass it as `externalCustomerId` on later checkout sessions, so you never need to store the XPay customer ID.

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.

Invoice Payment

An Invoice Payment is one payment made on an invoice. An invoice can have several: one per part payment or installment. A payment is backed by a PaymentIntent when the customer paid online, or by a payment record when the merchant recorded money received outside XPay, such as cash or a cheque. Money returned from a payment is shown in amountRefunded and documented by a credit note; the payment's status stays paid.

Invoice

An Invoice is a statement of what a customer owes, with a page where they can pay it. An invoice starts as a draft you can edit freely. Finalizing it assigns its number, freezes its amounts and the customer's details, and makes it payable. A finalized invoice is never edited: correct it with a credit note, or revise it, which replaces it with a new invoice. An invoice can take several payments, online or recorded by you, and is paid when nothing remains.

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

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.

Pending Coupon

The Coupon selected for a Checkout Session before payment completes. It contains the discount terms used to calculate the session total; the Coupon has not yet been redeemed.

Pending Discount

A Discount selected for a Checkout Session before payment completes. Its ID is pending until the discount is redeemed, and it includes the selected Coupon and any Promotion Code used.

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, or by its `lookupKey` in checkout line items, and the customer is charged according to what the Price defines.

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

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

A Refund returns funds from a successful Charge to the original payment method. It can be full or partial. Its status tracks the processor's progress; pending or requires_action does not mean funds have been returned.

Tax Rate

A Tax Rate is a reusable tax you apply to invoice lines, such as 14% VAT. A rate is either inclusive (already inside the price) or exclusive (added on top). The percentage and the inclusive setting are fixed once the rate is created, so issued invoices never change. To change a rate, archive it and create a new one.

Webhook Endpoint With Secret

A Webhook Endpoint with its signing secret, returned only when the endpoint is created or its secret is rotated. Store the secret securely and use it to verify incoming webhook signatures.

Webhook Endpoint

A merchant webhook endpoint, its subscription settings and status.