Webhooks

Invoice callbacks are HTTP POST messages sent from the iPint server to your server. The primary purpose of a callback is to alert your server that the status of an invoice has changed.

How it works

1. You provide an invoice_callback_url when calling POST /checkout
2. iPint sends an HTTP POST to that URL when the invoice status changes
3. Your server responds with HTTP 200 (empty body) to acknowledge receipt
4. You then call GET /invoice to verify the actual status

When callbacks are sent

Callbacks are sent for the following statuses:

• COMPLETED — payment successful
• FAILED — payment failed

Callback payload

The body is JSON and contains:

{
  "invoice_id": "invoice id",
  "status": "COMPLETED"
}

For a failed payment:

{
  "invoice_id": "invoice id",
  "status": "FAILED"
}

Security notes

• Do not whitelist iPint's sending IP addresses — these are subject to change without notice.
• Use HTTPS for your invoice_callback_url.
• Do not rely on callback data — always verify via GET /invoice.

Expected response

The iPint server expects an HTTP 200 response with an empty body.

• Any other HTTP response is considered a failed delivery.
• iPint attempts to send the request multiple times until successful or until the server gives up.

Handling the callback

// Your webhook endpoint (e.g. /api/webhook)
app.post("/webhook", (req, res) => {
  const { invoice_id, status } = req.body;

  // 1. Respond immediately with 200
  res.status(200).send();

  // 2. Verify the status by calling GET /invoice
  verifyInvoice(invoice_id).then((invoice) => {
    if (invoice.transaction_status === "COMPLETED") {
      // Mark payment successful in your system
      fulfillOrder(invoice_id);
    } else if (invoice.transaction_status === "FAILED") {
      // Mark payment failed
      cancelOrder(invoice_id);
    }
  });
});

Next steps

• GET /invoice — verify payment status
• Check Payment Status guide — full walkthrough
• POST /checkout — where to set the callback URL