Skip to content

Payment Endpoint (Webhook)

The Payment Endpoint is a URL on your server that SecPaid calls via POST whenever a payment event occurs on a link. It delivers a JSON payload with the transaction details.

Setting Your Payment Endpoint

Configure one or more Payment Endpoint URLs in your SecPaid account settings. Any URL saved there is automatically applied to every link 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 Payment Endpoint URL (index 0)
--data-urlencode 'payment_endpoint=0'

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

After changing Payment Endpoint settings in your profile, log out and back in on all devices for the change to take effect.

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

--data-urlencode 'payment_endpoint=https://yourapp.com/webhook/payment'

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

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

Event Types

SecPaid sends a POST request to your Payment Endpoint for two events:

Successful Payment

Sent when a customer completes a payment.

{
    "ResponseCode": 1,
    "data[pay_id]": 1466,
    "data[amount]": 100,
    "data[user_id]": "b44c4429-4a7b-4e27-85af-c1c2f43f4ffe",
    "data[status]": "success"
}

Payment Cancellation

Sent when a customer presses the cancel button on the payment page.

{
    "ResponseCode": 1,
    "data[pay_id]": 1466,
    "data[amount]": 100,
    "data[user_id]": "b44c4429-4a7b-4e27-85af-c1c2f43f4ffe",
    "data[Status]": "cancel"
}

Field Reference

Field Description
ResponseCode Always 1 for webhook events
data[pay_id] The payment / link ID
data[amount] The payment amount
data[user_id] The SecPaid user ID of the link creator
data[status] success or cancel

Implementation Guide

Your endpoint must:

  1. Accept POST requests with a JSON body.
  2. Respond with HTTP 200 promptly — SecPaid does not retry on non-2xx responses.
  3. Validate ResponseCode before processing.
  4. Use data[pay_id] to look up the transaction in your system.
  5. Handle both success and cancel events.
// Example: minimal PHP handler
$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['ResponseCode'] == 1) {
    $payId  = $payload['data[pay_id]'];
    $status = $payload['data[status]'] ?? $payload['data[Status]'];

    if ($status === 'success') {
        // mark order as paid
    } elseif ($status === 'cancel') {
        // handle cancellation
    }
}

Security Considerations

  • Accept requests only from SecPaid IP ranges (contact support for the current list).
  • Always use HTTPS on your endpoint.
  • Log all incoming webhook payloads for debugging and audit purposes.
  • Do not expose sensitive logic based solely on the webhook — cross-check with getPayInTransactions for critical flows.