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

    Authentication/Webhook Validation

    API Authentication#

    API keys are issued per merchant and can be obtained in the Merchant panel under Integration menu.
    Send either header x-api-key: <api-key> or Authorization: Bearer <api-key>.
    Keep keys secret, rotate them periodically, and remove old keys immediately when rotating.

    Example#

    Webhook Signature Verification#

    When you set webhookUrl while creating a payment link, SX Digital Pay signs every webhook request (payment_link.created, payment_link.status_changed, payment_link.payment_status_changed).
    Headers:
    x-sxpay-signature: HMAC-SHA256 hex digest of "{timestamp}.{rawBody}" using the link’s webhookSecret.
    x-sxpay-timestamp: Epoch milliseconds (use to prevent replay).
    Verification steps:
    1.
    Read the raw request body (exact bytes, before JSON parse).
    2.
    Compute expected = HMAC_SHA256(webhookSecret, timestamp + "." + rawBody).
    3.
    Compare expected with x-sxpay-signature using constant-time comparison.
    4.
    Optionally reject if the timestamp is too old (e.g., > 5 minutes) to mitigate replay attacks.

    Node.js Example#

    Handling Failures#

    If verification fails, return a non-2xx status; SX Digital Pay will treat the delivery as failed.
    Make sure your endpoint responds quickly (ideally < 5s) and is highly available; retries from SX Digital Pay will occur when the response is non-2xx.

    Best Practices#

    Store webhookSecret securely; it is only returned at link creation time.
    Use HTTPS for webhookUrl.
    Log request IDs and timestamps to help debug delivery issues.
    Rotate API keys and webhook endpoints/secrets when decommissioning environments.
    Modified at 2025-12-07 05:59:35
    Previous
    Getting started
    Next
    Create single-use payment link
    Built with