search

Webhook

hashtag
Overview

PaySonic provides a webhook mechanism for merchants to receive real-time updates on the status of their transactions, whether for pay-ins. Merchants can specify a callBackUrl in their API requests, and PaySonic will send notifications to this URL whenever there is a status change in the transaction.

hashtag
Setting Up the Webhook

  1. Implement a Callback Endpoint: Merchants must set up an HTTP POST endpoint that can receive JSON payloads. This endpoint should be capable of processing the incoming webhook data and verifying its authenticity using HMAC-SHA256 signature validation.

  2. Insert the Callback URL: During a pay-in request, insert your endpoint URL in the callBackUrl field. PaySonic will send updates to this URL whenever the transaction status changes.

  3. Status Updates: When a transaction status changes to Waiting, Confirming, Paid, Failed, or Expired, PaySonic will send a JSON payload with the updated status.

  4. Callback Validation: To ensure the integrity and authenticity of the callback, PaySonic signs each callback payload using HMAC-SHA256 with the merchant’s API secret key. This signature is sent in the HTTP header X-TLP-SIGNATURE.

  5. Acknowledge the Callback: Upon receiving the callback, merchants must respond with an HTTP 200 status code and the text "ok" in the response body. This acknowledges the successful receipt of the callback. If the acknowledgment is not received, the webhook will not be retried automatically. Merchants can manually resend webhooks from their PaySonic dashboard.

hashtag
Validating Callbacks

Merchants should validate the HMAC signature included in the X-TLP-SIGNATURE header to ensure the callback is from PaySonic and has not been tampered with. The HMAC signature is generated using the raw POST data and the MERCHANT_API_SECRET as the shared key.

hashtag
Example Web-hook Handling Code

const express = require('express');
const crypto = require('crypto');

const app = express();
const PORT = 3000;
const apiSecretKey = 'YOUR_TLP_API_SECRET_KEY'; // Replace with your actual API secret key

// Middleware to parse incoming JSON requests
app.use(express.json());

// Callback endpoint
app.post('/callback', (req, res) => {
    const data = req.body;

    // Calculate HMAC signature
    const tlpSignature = req.headers['x-tlp-signature'];
    const calculatedHmac = crypto
        .createHmac('sha256', apiSecretKey)
        .update(JSON.stringify(data)) // Use raw body string for HMAC calculation
        .digest('hex');

    if (calculatedHmac === tlpSignature) {
        // Signature is valid
        if (data.type === 'pay-in') {
            console.log('Received pay-in callback:', data);
            // Process pay-in data here
        } 
        // Return HTTP Response 200 with content "ok"
        res.status(200).send('ok');
    } else {
        // Invalid HMAC signature
        res.status(400).send('Invalid HMAC signature');
    }
});

// Start the server
app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
});

Again, please note that these code snippets serve as examples and may require modifications based on your specific implementation and framework.

Example of Web-hook Responses

Again, please note that these response snippets serve as examples and may require modifications based on your specific implementation and framework.

circle-info

Important Considerations

  • Security: Always verify the X-TLP-SIGNATURE header to ensure the callback originates from PaySonic.

  • Response: Always return an HTTP 200 response with "ok" in the body to acknowledge successful receipt of the webhook.

  • Manual Retry: In case of missed callbacks, use the paysonic.network dashboard to manually resend the webhook.

PreviousSupported Base Currency List

Last updated