Getting Started

This guide explains how to integrate external systems with SX Digital Pay to generate single-use payment links and track their lifecycle through API calls and webhooks. The external system creates a link, redirects the customer to that link, and monitors status changes to reconcile payments internally.

Environments

Production: https://api.sxdigitalpay.com

Authentication

Send either header x-api-key: <api-key> or Authorization: Bearer <api-key>. See Authentication/Webhook Verification for full details.

Core Flow

Create a payment link

POST /payment-links

Required fields: title, amount (> 0).

Optional but recommended: externalReference (idempotency per merchant), expiresAt, metadata (JSON object), webhookUrl, webhookSecret (otherwise generated and returned only once).

Redirect the customer to the link

Use url or shortUrl from the response. The checkout and payment capture happen on SX Digital Pay.

Track the link and payments

Webhooks (if webhookUrl was provided) notify status changes for links and payments.

Polling endpoints are available if webhooks are not configured or as a fallback.

Key Endpoints

Create link: POST /payment-links

List links: GET /payment-links (filters: status, externalReference, pagination)

Get link details: GET /payment-links/{id}

List payments for a link: GET /payment-links/{id}/payments

Link Status and Behavior

ACTIVE: link is usable; isActive is true while not expired.

INACTIVE: disabled by the platform or business logic.

EXPIRED: past expiresAt or otherwise expired.

Links are single-use (isMultiUse always false). After a payment is completed, expect the link to become inactive and receive a webhook if configured.

Webhooks

Configure webhookUrl when creating the link to receive events:

payment_link.created

payment_link.status_changed

payment.status_changed

Headers:

x-sxpay-signature: HMAC-SHA256 of "{timestamp}.{rawBody}" using the link’s webhookSecret.

x-sxpay-timestamp: Epoch milliseconds.

Verify the signature before processing. If verification fails, reject the webhook.

Typical Integration Steps (Example)

Create link:

Redirect customer to the returned url (or shortUrl).

Receive webhook payment.status_changed with status: COMPLETED or poll GET /payment-links/{id}/payments to reconcile.

When you receive a completed payment, mark the order as paid in your system.

Polling vs. Webhooks

Prefer webhooks for near real-time updates.

Use polling as a backup (e.g., on webhook failures or for periodic reconciliation).

Errors and Responses

401 Missing/invalid API key.

403 Merchant inactive.

404 Resource not found (link or payment).

400 Validation issues (title, amount, dates, webhookUrl).

409 externalReference already exists for the merchant.

Data Models (high level)

PaymentLink: id, title, amount, currency, status, isMultiUse:false, isActive, isExpired, expiresAt, url, shortUrl, metadata, optional webhookUrl, optional webhookSecret (only at creation).

Payment: id, status (PENDING | COMPLETED | DISPUTED | REFUNDED), timestamps, optional customer, optional quote (amount, currency, paymentMethod, installments, totalBRL).

Recommendations

Use externalReference for idempotency and reconciliation on your side.

Store the webhookSecret securely; it is only returned at creation time.

Validate HMAC signatures and check x-sxpay-timestamp freshness to prevent replay attacks.

Implement retries with exponential backoff for webhook delivery on your endpoint. SX Digital Pay expects 2xx to consider the webhook delivered.

Environments#

Authentication#

Core Flow#

Key Endpoints#

Link Status and Behavior#

Webhooks#

Typical Integration Steps (Example)#

Polling vs. Webhooks#

Errors and Responses#

Data Models (high level)#

Recommendations#