Khipu API for Creating and Receiving Payments

Introduction

Khipu's API for creating and receiving payments allows collectors (individuals or organizations) with an active collection account on Khipu to generate payments.

The process of creation, payment, and validation is as follows:

1. The collector generates a payment using the API and displays a button for purchase.
2. The payer clicks the payment button on the website or a payment link in an email or other medium and pays using Khipu.
3. The payer is redirected to the return page defined by the collector, where it should indicate that the payment is being verified (or to the failure page if the payment could not be made).
4. A few moments later, Khipu verifies the transaction and notifies the payer by email. Additionally, the merchant is notified by email and/or through the invocation of a web service.
5. The collector validates the payment notification and delivers the traded goods to the payer (or discards the notification if it is invalid).

Collect account

When a person creates a user account on Khipu, a "collection account" will automatically be created for them. This collect account is where payments received from other individuals will be associated.

To start receiving payments, it's necessary to activate this collection account by linking it to a bank account. The bank account is where the daily proceeds will be deposited on the next business day. This bank account can be changed later and will affect all payments that have not yet been settled.

Initially, a collection account does not have a bank account associated with it. To link a bank account, you should go to your Khipu account and try to create a payment request. The system will prompt you to complete a payment using that bank account to ensure that you have access to it. The payment amount will be refunded on the next business day.

Multiple Collection Accounts

A user account on Khipu can create (or have access to) multiple collection accounts. This is useful, for example, to have different businesses, each with its own collect account. Each collection account must have its bank account configured, but multiple collection accounts can share the data of the same bank account where the money will be settled.

Credentials

Every collection account has credentials that allow the use of the REST API. These credentials are generated when the collection account is created.

This new version of the API no longer requires requests to be signed, as the authentication and authorization process is handled by a secret API key associated with the collection account, which must be sent in a special header (x-api-key) in each request. Due to the level of access it provides, the key should not be shared with anyone. You can always create a new key that will invalidate the old one if you want to change it; the process is completely self-managed, and you can review the details in the section Authentication.

However, it is important to know how to locate the "Collection Account ID," which can be useful for expediting a support ticket.

Security

In the creation and validation of a payment, two different security mechanisms are used. On one hand, Khipu uses an extended validation certificate that allows the collector to always know that they are effectively communicating with Khipu's official servers. Additionally, for this new version of the API, the x-api-key header allows the generator of the payment to be unequivocally identified.

Testing Environment and Transition to Production

In this section, we show you the necessary steps to start integrating Khipu into your site. The most important thing to note is that, during the development and testing process, you should use credentials from development collection accounts. Only when your site is ready and the integration is prepared to make real payments should you switch to production collection account credentials.

Collection Account in Developer Mode

Khipu does not have a separate testing version from the production version like other platforms. Instead, the API and servers of the main platform are used. To perform development tests, a "developer collecting account" is used. These billing accounts are identical to normal ones but have some differences:

The associated current accounts are not real as no real money is settled. They are created only for testing purposes. Payments generated with them can only be paid using test banks.

To create a development account, you must follow these steps:

• Register as a user here: https://khipu.com/user/register
• Go to your user profile on Khipu
• In "Developer Options" activate developer mode.
• Then go to settings and choose "Collection Accounts"
• Now a button "Create account in developer mode" will appear.

Now that you have a development account, all you need is the API key. The process is self-service; in the "Account Options" panel, "Integrating Khipu into your website" section, review the Autenticación section for more details.

Testing Bank

Development collection accounts can only receive payments from Test Banks. These banks are created by Khipu for testing purposes.

The test bank allows you to test that the payment process is complete, including going to the bank and depositing to Khipu or using simplified transfer. Since these banks do not operate with real money, you can make as many transfers as you want because the balance never runs out.

Additionally, these banks have on-screen instructions to enter, fill in passwords, and authorize transfers.

Internet Access

To access Khipu's REST API, you need to have an internet connection. This is necessary to create and modify payments.

Whenever Khipu receives a payment, the merchant is notified so that they can deliver the product or service to the customer. This notification can be via email or using the instant notification API. The recommended mechanism is the instant notification because it does not require human intervention once it is well configured. These notifications are invocations that Khipu must make to a web service on the merchant's website, which is why this web service must be visible from the internet. Refer to Webhook for notifications for details on how to use the notification API.

Common Use Case

Let's analyze the most common use case of the REST API, which is making a payment on a web store to purchase a product. The most common flow has the following steps:

• The customer selects their products and chooses to pay.
• The merchant creates a payment using the REST API.
• The merchant sends the customer to pay in Khipu website.
• The customer pays.
• The customer is redirected to the merchant's website and waits a few moments while Khipu verifies the payment.
• The payment is verified, and the merchant is notified via web service.
• The merchant delivers the product or service.

Now let's look at the steps where integration with Khipu is necessary:

Create a payment

POST /payments

After the customer selects their products and chooses to pay, the payment process begins. Most e-commerce software operates similarly. They all have some sort of object that represents the purchase order. What we need to do is link this purchase order to a payment in Khipu.

You can review the documentation for the POST /payments method, which includes code snippets in various programming languages for a quick test. However, we recommend reviewing the Code Generation section to build a more robust client.

In the first step, we obtain the purchase order object. This can be created on the spot or retrieved using its own identifier that allows us to identify that purchase order/payment. At the API level, this value is represented by the transaction_id parameter of the call. This is necessary so that at the time of reconciliation, you can obtain the purchase order and mark it as paid.

The response from the call will be an object with information about the created payment. The payment_id field contains the unique identifier of our payment and the URL to which we should send the user to pay.

Offering a List of Banks (Optional)

GET /banks

This step is optional but can be useful for some merchants. In the previous call to create payments, you can see the parameter "Bank ID to pay". This ID is used to create a payment with a pre-selected bank (only from banks supported by Khipu). To obtain this ID, you can use the call to the GET /banks method, which provides a list of banks supported by Khipu, their names, their IDs, and other information.

The result of the call contains the banks value, which is a list of banks. Each bank has a bank_id with the value that we can use to create configured payments.

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.