The Payment Links API allows you to generate hosted payment pages that can be shared with customers via email, SMS, chat, or social media. These links support both simple one-time purchases and complex recurring subscriptions.
While this guide focuses on the API for automated integrations, please note that Payment Links can also be created manually without any coding.
When to use the Dashboard:
- Ad-hoc Requests: Quickly creating a link for a specific customer support interaction.
- No-Code Testing: Verifying the payment flow before integrating the API.
- Simple Operations: Merchants who do not need programmatic generation.
You can access this functionality by logging into your xMoney Merchant Dashboard and navigating to the Payment Links section. The dashboard provides a visual interface to set the amount, currency, and description, instantly generating a URL you can copy and paste.
Payment Links use a specific server URL different from the standard API transaction endpoints.
Base URL:
- Stage Env: https://office-api-stage.xmoney.com
- Live Env: https://office-api.xmoney.com
All requests require authentication using a Bearer Token in the header.
Authorization: <YOUR_API_PRIVATE_KEY>Generate a new payment link via API. You can define the link to be a simple description-based charge or a detailed itemized cart.
- Endpoint:
POST /payment-link - Content-Type:
application/x-www-form-urlencoded
Required Parameters
| Parameter | Type | Description |
|---|---|---|
| siteId | Integer | The ID of your site |
| amount | Float | The total amount to charge (e.g., 100.00). |
| currency | String | ISO Currency code (e.g., USD, EUR, GBP). |
| orderType | String | purchase (one-off) or recurring (subscription). |
| active | Integer | 1 (active) or 0 (inactive). |
| contentType | String | Description (simple) or Items (detailed cart). |
Use contentType: Description for a generic charge.
curl -X POST "https://office-api-stage.xmoney.com/payment-link" \
-H "Authorization: YOUR_PRIVATE_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "siteId=123" \
-d "amount=50.00" \
-d "currency=USD" \
-d "orderType=purchase" \
-d "active=1" \
-d "contentType=Description" \
-d "content=Consulting Services" \
-d "customerEmail=client@example.com"Use contentType: Items to list specific products. You must use array notation for the items.
curl -X POST "https://office-api-stage.xmoney.com/payment-link" \
-H "Authorization: YOUR_PRIVATE_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "siteId=123" \
-d "amount=30.00" \
-d "currency=USD" \
-d "orderType=purchase" \
-d "active=1" \
-d "contentType=Items" \
# Item 1
-d "content[0][item]=T-Shirt" \
-d "content[0][unitPrice]=20.00" \
-d "content[0][units]=1" \
-d "content[0][type]=physical" \
# Item 2
-d "content[1][item]=Stickers" \
-d "content[1][unitPrice]=5.00" \
-d "content[1][units]=2" \
-d "content[1][type]=physical"To create a subscription link, set orderType to recurring and provide interval details.
| Parameter | Description |
|---|---|
| intervalType | day or month. |
| intervalValue | Number of intervals (e.g., 1 for every month). |
| trialAmount (Optional) | Amount for the first charge. |
| firstBillDate (Optional) | ISO 8601 date for the first recurring charge. |
Example:
curl -X POST "https://office-api-stage.xmoney.com/payment-link" \
-H "Authorization: YOUR_PRIVATE_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "siteId=123" \
-d "amount=10.00" \
-d "currency=USD" \
-d "orderType=recurring" \
-d "contentType=Description" \
-d "content=Monthly Sub" \
-d "intervalType=month" \
-d "intervalValue=1"{
"code": 0,
"message": "string",
"data": {
"hash": string,
}
}Retrieve a single payment link using its unique hash.
- Endpoint:
GET /payment-link/{hash}
Search for payment links associated with a site.
- Endpoint:
GET /payment-link - Required Parameter:
siteId
Filtering Options (Query Parameters):
| Parameter | Description |
|---|---|
| amount | Filter by specific amount. |
| active | 1 or 0. |
| startDate / endDate | Filter by creation date (format: yyyy-mm-dd hh:mm:ss). |
| customerEmail | Filter by customer email. |
| limitAccess | Filter by number of allowed accesses. |
Modify an existing payment link. Note that changing amounts or items will affect future customers using this link.
- Endpoint:
PUT /payment-link/{hash} - Body: Same parameters as the Create endpoint.
Permanently remove a payment link.
- Endpoint:
DELETE /payment-link/{hash}
You can limit how a link is used or when it expires via the following parameters during Creation or Update:
limitAccess: Integer. The maximum number of times the link can be successfully paid.expireDate: String (Date format: yyyy-mm-dd). The date after which the link becomes invalid.active: Set to 0 to temporarily disable the link without deleting it.
If you know the customer details beforehand, you can pre-fill them to simplify their checkout experience:
customerEmailcustomerIdentifiercustomerTags[]
You can force specific fields to be mandatory during checkout by setting these parameters to 1:
customerRequiredFields[firstName]customerRequiredFields[lastName]customerRequiredFields[address]customerRequiredFields[phone]- (and others as defined in the schema)
For specialized industries, you can pass Level 3 data using the level3Type parameter (set to airline or tourism) and the associated fields (e.g., level3AirlineTicketNumber, level3TourismDepartureDate, etc.). Refer to the full API schema for the complete list of Level 3 fields.
This guide covers the core functionalities for creating and managing Payment Links, including one-time purchases, subscriptions, and itemized carts.
For a complete list of all available parameters, error codes, and specific data constraints (including detailed Level 3 data fields for Airline and Tourism sectors), please refer to the official API documentation:
- Full API Reference: https://docs.xmoney.com/api/reference/payment-links