Webhooks

​

Overview

Webhooks allow you to receive real-time notifications about the status of service purchases. When you configure a webhook URL in your dashboard, Chipi Pay will send POST requests to that URL whenever the status of a transaction changes.

​

Webhook URL Configuration

Set your webhook URL in the Services Settings section of your dashboard.

​

Webhook Payload

{
  "event": "sku-transaction.completed",
  "data": {
    "skuTransactionId": "sku-tx-1234567890",
    "status": "TransactionStatus.COMPLETED"
  },
  "timestamp": "2024-01-15T10:35:00Z"
}

​

Event Types

​

Available Events

• sku-transaction.completed - SKU Transaction has been completed successfully
• sku-transaction.failed - SKU Transaction has failed

​

Status Values

​

Available Statuses

• PENDING - SKU Transaction is being processed
• COMPLETED - SKU Transaction has been completed successfully
• ERROR - SKU Transaction has failed (check errorMessage for details)

​

Response Requirements

Your webhook endpoint must return a 200 OK status code to acknowledge receipt of the webhook.

​

Security

To verify that webhooks are coming from Chipi Pay, you can:

1. Check the IP address of the request
2. Verify the webhook signature (coming soon)
3. Validate the webhook payload structure

​

Example Webhook Handler

// Express.js example
app.post('/webhook', (req, res) => {
  const { event, data, timestamp } = req.body;
  
  switch (event) {
    case 'transaction.status_updated':
      handleStatusUpdate(data);
      break;
    case 'transaction.completed':
      handleTransactionCompleted(data);
      break;
    case 'transaction.failed':
      handleTransactionFailed(data);
      break;
  }
  
  // Always return 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

function handleStatusUpdate(data) {
  console.log(`Transaction ${data.id} status: ${data.status}`);
  // Update your database or notify your user
}

function handleTransactionCompleted(data) {
  console.log(`Service delivered for transaction ${data.id}`);
  console.log(`Reference: ${data.reference}`);
  console.log(`Amount: ${data.mxnAmount} MXN (${data.usdAmount} USD)`);
  console.log(`File Number: ${data.fileNumber || 'N/A'}`);
  // Notify user of successful service delivery
}

function handleTransactionFailed(data) {
  console.log(`Transaction ${data.id} failed`);
  console.log(`Error: ${data.errorMessage}`);
  // Handle failed transaction (refund, retry, etc.)
}

​

Retry Logic

If your webhook endpoint is unavailable or returns an error status code, Chipi Pay will retry the webhook delivery.

After 3 failed attempts, the webhook will be marked as failed and no further retries will be attempted.

​

Testing Webhooks

You can test your webhook endpoint using tools like:

• webhook.site - Temporary webhook URLs for testing
• ngrok - Expose local endpoints to the internet
• Postman - Mock webhook requests