Create single-use payment link

POST

/payment-links

Creates a single-use payment link. Currency comes from the authenticated merchant and isMultiUse is always false.

Validation rules:

title is required and cannot be empty.

amount must be a number greater than zero.

expiresAt, if sent, must be a future ISO 8601 date-time.

externalReference, if sent, must be unique per merchant (409 if it already exists).

webhookUrl, if sent, must be http(s); webhookSecret is optional and if omitted a secure secret is generated and returned only on creation.

metadata accepts only JSON objects; other types are ignored and stored as null.

Request

Authorization

API Key

Add parameter in header

x-api-key

Example:

x-api-key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Link created successfully.

Body

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠409

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.sxdigitalpay.com/api/external/payment-links' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Premium subscription",
    "description": "Annual plan invoice",
    "amount": 129.9,
    "expiresAt": "2026-01-31T23:59:59.000Z",
    "externalReference": "annual-plan-2025",
    "metadata": {
        "plan": "premium",
        "period": "annual"
    },
    "webhookUrl": "https://merchant.com/webhooks/sxpay"
}'

Response Example

201 - default

{
    "success": true,
    "paymentLink": {
        "id": "pl_123",
        "externalReference": "annual-plan-2025",
        "title": "Premium subscription",
        "description": "Annual plan invoice",
        "amount": 129.9,
        "currency": "USD",
        "status": "ACTIVE",
        "isMultiUse": false,
        "isActive": true,
        "isExpired": false,
        "expiresAt": "2025-01-31T23:59:59.000Z",
        "url": "https://app.sxdigitalpay.com/quote/[merchantShortName]/[paymentLinkId]",
        "shortUrl": "https://sxpay.me/[paymentLinkShortId]",
        "metadata": {
            "plan": "premium",
            "period": "annual"
        },
        "paymentStatus": "NOT_STARTED",
        "paymentsSummary": {
            "total": 0,
            "byStatus": {}
        },
        "payments": [],
        "webhookUrl": "https://merchant.com/webhooks/sxpay",
        "webhookSecret": "8f2c58c1c9a34f7e8b1a2c3d4e5f6789"
    }
}

Modified at 2025-12-07 04:55:53

Authentication/Webhook Validation

List single-use payment links