التوثيق

Create a payment link

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

POST
/payment-links

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

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/payment-links" \  -H "Content-Type: application/json" \  -d '{    "lineItems": [      {        "priceId": "price_abc123",        "quantity": 1,        "adjustableQuantity": {}      }    ],    "afterCompletion": {      "type": "redirect",      "redirect": {        "url": "https://example.com/success"      }    }  }'
{
  "id": "plink_abc123",
  "object": "payment_link",
  "merchantId": "mer_xyz789",
  "active": true,
  "expiresAt": "string",
  "currency": "EGP",
  "computedAmount": 100000,
  "nameCollection": false,
  "billingAddressCollection": false,
  "shippingAddressCollection": false,
  "phoneNumberCollection": false,
  "allowPromotionCodes": false,
  "submitType": "PAY",
  "customerCreation": "always",
  "afterCompletion": {
    "type": "redirect",
    "redirect": {
      "url": "string"
    },
    "hostedConfirmation": {
      "customMessage": "string",
      "returnUrl": "string"
    }
  },
  "lineItems": [
    {
      "id": "li_abc123",
      "quantity": 1,
      "price": {},
      "adjustableQuantity": {},
      "amountSubtotal": 200000,
      "amountTotal": 200000,
      "amountDiscount": 0,
      "amountTax": 0,
      "currency": "EGP",
      "description": "Premium Plan - Monthly",
      "presentmentDetails": {}
    }
  ],
  "customFields": [
    {
      "label": "Company Name",
      "type": "TEXT",
      "isOptional": false,
      "hasLimits": false,
      "limitType": "BETWEEN",
      "minCharacters": 5,
      "maxCharacters": 100,
      "dropdownOptions": [
        {}
      ]
    }
  ],
  "feeConfig": {
    "feesPassThrough": false,
    "vatCollectionEnabled": false,
    "vatCollectionRate": 1400,
    "source": "merchant"
  },
  "metadata": {},
  "brandingSettings": {
    "colorMode": "light",
    "borderStyle": "rounded",
    "spacing": "condensed",
    "inputSize": "small",
    "inputStyle": "flat",
    "formLayout": "compact",
    "colors": {
      "primary": "string",
      "primaryForeground": "string",
      "background": "string",
      "foreground": "string",
      "border": "string",
      "input": "string",
      "ring": "string",
      "muted": "string",
      "mutedForeground": "string",
      "accent": "string",
      "accentForeground": "string",
      "destructive": "string"
    },
    "fontFamily": "string"
  },
  "paymentMethodConfigurationId": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid value for parameter.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#parameter_invalid"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such price: price_abc123",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

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

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