Callbacks

Webhooks/Callbacks are a fundamental part of building a robust and reliable payment integration. They provide a powerful way for our system to communicate with your application in real time, ensuring you always have the most up-to-date information about your transactions.

What are Webhooks/Callbacks?

Webhooks, also known as callbacks, are a mechanism for your server to receive real-time notifications about events from our payment gateway. Think of them as an automated phone call: instead of your server constantly calling us to ask "Is the payment ready yet?", we call your server as soon as a significant event happens, like a successful payment or a refund. This "push" communication model is far more efficient than the traditional "pull" model of polling.

When you configure a webhook, you provide us with a specific URL on your server. When a payment event occurs, we send an HTTP POST request to that URL. This request contains a JSON/URL encoded payload with all the relevant transaction details, including the status, amount, and unique identifiers. Using webhooks is crucial for updating your database and fulfilling orders, as it guarantees you receive the final and definitive status of a transaction.

Types of Callbacks

In payment processing, there are two primary types of callbacks you will encounter:

1. Browser-to-Browser (B2B) Callbacks This is a redirection-based callback. After a customer completes a payment on our payment gateway's page, we redirect their browser back to a specific URL on your website. The redirect URL can include transaction details as query parameters. This url is the returnURL in the Sale API.

• Purpose: To provide a seamless user experience by returning the customer to your site. You can use this to show a success or failure page to the customer.
• Limitations: The merchant doesn't get a real-time response with this method as it depends on the user's browser.
• Recommendation: It should be used exclusively for front-end user experience.

2. Server-to-Server (S2S) Callbacks (Webhooks) This is the recommended and most secure method for receiving transaction updates. An S2S callback is a direct communication between our server and your server. When an event occurs, our server makes an HTTP POST request directly to the webhook URL you have configured. This URL is configured on the PG System during Merchant Onboarding.

• Purpose: To provide a definitive, tamper-proof, and reliable update on the transaction status. The request comes from our server, not the customer's browser, making it highly secure.
• Benefits: You receive the final status of a transaction, which is essential for accurate order fulfillment, inventory management, and financial reconciliation. It works even if the customer's browser is closed.
• Recommendation: Always use S2S callbacks to update your backend system and confirm the status of a payment. This should be your single source of truth for transaction status.

S2S Callback

JPSL will send an S2S response to the merchant’s server URL. The merchant’s server URL should be capable of handling the following content types:

application/json

{
  "acqName": null,
  "aggregatorID": "JP2000000000001",
  "TransmissionDateTime": "20250811145424",
  "paymentInstId": "9869117887@upi",
  "invoiceStatus": "Paid",
  "customerMobileNo": "9869117887",
  "customerEmailID": "[email protected]",
  "paymentSubInstType": "SAVINGS",
  "paymentMode": "UPI",
  "amount": "1.00",
  "merchantId": "JP2000000000016",
  "invoiceNo": "250004903651",
  "userID": null,
  "chargeAmount": "1.00",
  "txnID": "2000255997583",
  "paymentID": "145422916311",
  "paymentDateTime": "20250811145424",
  "addlParam1": "TEST1234456783",
  "addlParam2": "TEST",
  "secureHash": "584f7880c7dd87d204a602ff57d1eca3434213ae38804a596b2e26296ca92b12"
}

Response On Payment Advice URL

{
  "acqName": "PayPhi",
  "TransmissionDateTime": "20241018134237",
  "paymentInstId": "6XXX XXXX XXXX 3677",
  "cardNetwork": "RuPay",
  "customerEmailID": "[email protected]",
  "paymentSubInstType": "DC",
  "paymentMode": "Card",
  "amount": "100.00",
  "responseCode": "0000",
  "respDescription": "Transaction successful",
  "merchantId": "JP2001100060874",
  "merchantTxnNo": "Test4916110172",
  "txnID": "7700204186825",
  "paymentDateTime": "20241018134249",
  "paymentID": "55529451079",
  "secureHash": "cf400919608792963d9d8594517b58f762b67647f1b00901b86c40179922dc7f"
}