Last updated

Initiating the Payment

Once a payment is created, we must begin the payment process. There are two ways to do this. The recommended way is to use our JavaScript library, which will handle starting the payment. You can find extensive documentation on the GitHub site. There you can find an integration example of the library simulating a merchant using this library.

The other option to initiate the payment is simply to redirect the customer to the payment URL in Khipu. This URL corresponds to the payment_url parameter returned by the payment creation call.

Customer is Redirected to the Merchant

After the customer makes the payment on the Khipu portal, they will be redirected back to the merchant's website. The merchant's URL to which the user is redirected must be configured for each payment in the return_url field, although it could be the same for all payments.

It is very important to note that when the user returns to the merchant's page, this does not mean that the payment is verified. On this page, the merchant should indicate that the payment is in the verification process and that the user should wait a moment.

The merchant must implement on the payment return page a way to check the status of the payment and inform the user when the payment has been confirmed.

For this, there are 3 strategies, with the most common ones being:

  • WebSockets: The merchant's server informs the client's browser that the payment is confirmed so that it can be displayed. It is the most efficient way but the most complex to implement. For more information, see https://en.wikipedia.org/wiki/WebSocket
  • AJAX Calls: The page verifies through an AJAX call to the merchant's server about the status of the order. When the response is positive, the page informs the user that the payment has been completed.
  • Periodically Reloading the Page: It is the simplest mechanism and consists of using a timer to reload the page periodically, for example, every 10 seconds. Each time the page loads, it checks if the order is complete. If it is, the user is redirected to the success page. If not, it should indicate to the user that they need to continue waiting and use a new timer.

Receiving Notification and Delivering the Service

GET /payments/{payment_id}

At any time after the generation of the payment, you can check its status by querying the endpoint GET /payments/{payment_id}.

If you have configured a URL to receive a notification, then Khipu will invoke it immediately after reconciling the payment. You should receive and process this notification in the webhook you configured for these purposes.

The version of this API defines the way Khipu notifies the merchant, and you should consider that if you use the 3.0 API for payments, you must use the same version in the notifications API. In this version of the API, you will receive a JSON with an object representing the current state of the payment through a POST call.

Important
Khipu expects a response confirming successful delivery of the notification within 30 seconds (in other words, the webhook must return an HTTP 200 status code). If no response is received after 30 seconds, Khipu will attempt to notify again later.