Callback URL¶

The Callback URL is a redirect-based notification mechanism. After a payment is completed or cancelled, SecPaid redirects the customer's browser to your Callback URL with query parameters describing the outcome.

This complements the Payment Endpoint (server-side webhook). The Callback URL is browser-side and is suitable for redirecting users back to your application after checkout.

Setting Up the Callback URL¶

Option 1 — Profile Settings (recommended)¶

Configure one or more Callback URLs in your SecPaid account settings. Any URL saved there is automatically applied to all links you create, via the UI or the API.

You can store multiple URLs in your profile. When creating a link via the API, reference a saved URL by its zero-based index instead of repeating the full URL:

# Use the first saved Callback URL (index 0)
--data-urlencode 'callback_url=0'

# Use the second saved URL (index 1)
--data-urlencode 'callback_url=1'

After updating Callback URL settings in your profile, log out and back in on all devices for the change to take effect.

Option 2 — Per-Link Override¶

Pass a full URL as callback_url in the body of createLink or createSplitLink to override the profile setting for that specific link:

--data-urlencode 'callback_url=https://yourapp.com/checkout/callback'

You can also pass a comma-separated list of indices or URLs to trigger multiple callbacks for a single link:

# Trigger both the first saved URL and a one-off URL
--data-urlencode 'callback_url=0,https://yourapp.com/other-callback'

Callback Events¶

Successful Payment¶

When a customer completes a payment, they are redirected to:

{callback_url}?pay_id=<pay_id>&user_id=<user_id>&status=success

Example:

https://yourapp.com/checkout/callback?pay_id=12345&user_id=b44c4429-4a7b&status=success

Payment Cancellation¶

When a customer presses the cancel button, they are redirected to:

{callback_url}?pay_id=<pay_id>&user_id=<user_id>&status=cancel

Example:

https://yourapp.com/checkout/callback?pay_id=12345&user_id=b44c4429-4a7b&status=cancel

Query Parameter Reference¶

Parameter	Description
`pay_id`	The payment / link ID
`user_id`	The SecPaid user ID of the link creator
`status`	`success` or `cancel`

Implementation Guide¶

Your callback handler should:

Read the status query parameter.
Use pay_id to identify the order in your system.
For critical order confirmation, always cross-check the payment status by calling getPayInTransactions — the callback is a convenience redirect, not a guaranteed delivery mechanism.
Handle both success and cancel gracefully.

// Example: Express.js callback handler
app.get('/checkout/callback', async (req, res) => {
    const { pay_id, status } = req.query;

    if (status === 'success') {
        // Optionally verify via getPayInTransactions
        await markOrderPaid(pay_id);
        res.redirect('/order/confirmation');
    } else if (status === 'cancel') {
        res.redirect('/cart');
    }
});

Callback vs. Payment Endpoint¶

	Callback URL	Payment Endpoint
Triggered by	Browser redirect	Server-to-server POST
Delivery	Best-effort (user must complete the redirect)	Direct server call
Use case	UX redirect after checkout	Reliable order/payment processing
Payload	Query parameters	JSON body

Use both together for the most robust integration: the Payment Endpoint handles your business logic reliably, while the Callback URL handles the user experience.