SX Digital Pay
    SX Digital Pay
    • Getting started
    • Authentication/Webhook Validation
    • PaymentLinks
      • Create single-use payment link
        POST
      • List single-use payment links
        GET
      • Get link details
        GET
    • Webhooks
      • Link created
      • Link status changed
      • Link paymentStatus changed
    • Schemas
      • PaymentLinkStatus
      • PaymentLinkPaymentStatus
      • PaymentStatus
      • PaymentMethod
      • PaymentLinkBase
      • PaymentLinkSummary
      • PaymentLinkWithWebhook
      • PaymentLinkWithPayments
      • PaymentLinkCreated
      • PaymentsSummary
      • CreatePaymentLinkRequest
      • PaymentCustomer
      • PaymentQuote
      • Payment
      • Pagination
      • Error
      • WebhookLinkPayload
      • WebhookPaymentPayload
      • WebhookLinkEventData
      • WebhookLinkPaymentStatusEventData
      • WebhookEvent

    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, and checks the link details (or webhook) to know whether a payment was completed.

    Environments#

    Production: https://api.sxdigitalpay.com/api/external

    Authentication#

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

    Rate limiting#

    External API: 60 requests per minute per API key.
    Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and return 429 + Retry-After when the limit is exceeded.

    Core Flow#

    1.
    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).
    2.
    Redirect the customer to the link
    Use url or shortUrl from the response. The checkout and payment capture happen on SX Digital Pay.
    3.
    Track the link and payments
    Read paymentStatus (NOT_STARTED, PENDING, COMPLETED) and payments[] from GET /payment-links/{id}.
    Or subscribe to the webhook payment_link.payment_status_changed to be notified when the link's paymentStatus changes.

    Key Endpoints#

    Create link: POST /payment-links
    List links: GET /payment-links (filters: status, externalReference, pagination)
    Get link details (payments + paymentStatus): GET /payment-links/{id}
    Payments are embedded in the link details response; there is no separate payments endpoint.

    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.
    paymentStatus (aggregated by link):
    NOT_STARTED: no payments exist for the link.
    PENDING: at least one payment exists but none completed.
    COMPLETED: at least one payment completed for the link (even if a payment was later refunded or disputed).

    Webhooks#

    Configure webhookUrl when creating the link to receive events:
    payment_link.created
    payment_link.status_changed
    payment_link.payment_status_changed
    payment_link.payment_status_changed is the simplest way to know when a link starts receiving payments (NOT_STARTED → PENDING) and when a payment is completed (PENDING → COMPLETED). The payload also includes the latest payment summary and counts.
    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)#

    1.
    Create link:
    2.
    Redirect customer to the returned url (or shortUrl).
    3.
    Receive webhook payment_link.payment_status_changed with paymentStatus: COMPLETED (and latestPayment) or poll GET /payment-links/{id} to reconcile.
    4.
    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) against GET /payment-links/{id} to read paymentStatus and payments[].

    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, paymentStatus, isMultiUse:false, isActive, isExpired, expiresAt, url, shortUrl, metadata, optional webhookUrl, optional webhookSecret (only at creation).
    Payments embedded in link details: paymentsSummary (counts by status) plus payments[] with id, status, timestamps, optional customer, optional quote (amount, currency, paymentMethod, installments, totalBRL).
    Payment status (per payment): PENDING | COMPLETED | DISPUTED | REFUNDED.

    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.

    Support#

    If you have any questions, concerns, or wish to report a bug, please do not hesitate to contact us: developers@sxdigitalpay.com
    Modified at 2025-12-07 06:01:10
    Next
    Authentication/Webhook Validation
    Built with