Create single-use payment link

Sandbox

https://sandbox.sxdigitalpay.com/api/v1

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

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.

callbackUrl, if sent, must be a valid http(s) URL. After a successful payment the customer is redirected to it.

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.

Headers

Body

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠409

🟠429TooManyRequests

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://sandbox.sxdigitalpay.com/api/v1/payment-links' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Payment title",
    "description": "Payment Description",
    "amount": 129.9,
    "expiresAt": "{{$date.future}}",
    "externalReference": "{{$string.uuid}}",
    "metadata": null,
    "webhookUrl": "https://merchant.com/webhooks/sxpay",
    "webhookSecret": "WebhookSecretForWebhookValidation",
    "callbackUrl": "https://merchant.com/checkout/success"
}'

Response Example

201 - Success

{
    "success": true,
    "paymentLink": {
        "id": "pl_123",
        "externalReference": "1b4db7eb-4057-5ddf-91e0-36dec72071f5",
        "title": "Payment Title",
        "description": "Payment Description",
        "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": null,
        "callbackUrl": "https://merchant.com/checkout/success",
        "paymentStatus": "NOT_STARTED",
        "paymentsSummary": {
            "total": 0,
            "byStatus": {}
        },
        "payments": [],
        "webhookUrl": "https://merchant.com/webhooks/sxpay",
        "webhookSecret": "8f2c58c1c9a34f7e8b1a2c3d4e5f6789"
    }
}

Get merchant profile

List single-use payment links