Khipu API to create charges and receive payments

A guide to integrate your merchant via our API

Create a Charge

To receive a payment

Introduction

Khipu API to create and receive payments, allows individuals or organizations, with an active charging account in Khipu, to generate charges.
With the following procedure for creation, payment and validation:

1. The collector generates a charge using the API, which displays a button for the purchase.
2. The payer clicks the payment button on the website, or a link within an email (or other means) and pays using Khipu.
3. The payer is redirected to the return page defined by the collector, where “Payment Verification” or “Failed Payment” must be indicated.
4. Moments later Khipu verifies the transaction and notifies the payer by email. Also, the merchant is notified by email and/or by a web service command.
5. The collector then validates the payment notification and delivers the good to the payer (or discards the notification, if invalid).

Important! ! In the third step the payer is redirected to a return page (3a) or a possible payment rejection. The success means that the transaction is at the verification process, it doesn’t mean that it has been completed yet. It is necessary to complete the verification process (step 5) before delivering the goods or services. The same occurs with the Reject (3b), the user still has instances to pay and complete the transaction.

1. Charging account

When the customer creates a user account in Khipu a “charging account” will be automatically created. This charging account will be the account where payments from other customers will be associated to.

To be able to collect, it is mandatory to activate the charging account by associating it with a bank account. The bank account is where the daily collections will be deposited the next business day. This bank account can be changed afterwards and will be affected by all payments still not rendered.

Initially, a charging account doesn’t have a bank account associated to. To associate one, you must go to your Khipu account and try to create a charge. The system will ask you to complete a payment using that bank account to ensure that you have access to it. The payment amount will be returned the next business day.

Important: New personal charging accounts, in the case of Chile, has a maximum charge amount of $50.000. To increase this amount, you must contact our support at: soporte@khipu.com.

2. Multiple charging accounts

A Khipu user account can create (or have access to) multiple charging accounts. This could be used, for example, to have different merchants, each one with its own charging account. Each charging account must have a bank account configured, and several charging accounts can share the same bank account data where the money will be transferred.

3. Credentials

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

Credentials have two parameters:

• receiverId: a unique identifier of a charging account and can’t be changed.
• secret: the secret key of the charging account.

The most important of the credentials is “secret”. This key is used to sign all requirements of the API and shouldn’t be shared with anyone. Khipu support may eventually request the receiverId to follow up cases, but it will not request the secret key. You can always create a new key which will invalidate the former one.

4. Security

Two different security mechanisms are used in the creation and validation of a payment. First, Khipu uses an extended validation certificate which allows the collector to always know that he is communicating effectively with the official Khipu servers, also, the merchant must sign every API call using its unique account credentials.

To understand the signature process in detail please review the signature documentation.

5. Testing environment and final release

In this section we will show you the steps necessary to begin the integration of Khipu to your site. The most important to notice is that, during the development process and testings, developer charging accounts credentials must be used. Credentials must be changed to the final ones when your site is ready, and the integration prepared to make real payments.

6. Charging account in developer mode

Khipu doesn’t have a separate from production testing environment, as other platforms. . Instead, main platform API and servers are used. A “developer charge account” is used for development testing. These charging accounts are identical to the normal ones, with some differences:

Checking accounts associated are not real, as no real money is transferred. They are created just for testing. Charges generated with them can only be paid using test banks.

To create a development account the following steps must be followed:

• Register as a user here: https://khipu.com/user/register
• Go to your user profile in Khipu.
• In “Developer Options” activate the Developer Mode.
• Go to Configure and select: “Charging Accounts”.
• A “Create account in Developer Mode” button will appear.

Now that you have a development account, all you need from it is the account credentials. These are obtained in the “Account Options” in the option “To integrate Khipu to your website”.

7. Test Banks

The developer charging accounts can only receive payments from test banks. These banks are created by Khipu for testing purposes.

A test bank allows for testing the completion of the payment process, including going to the bank and deposit Khipu or use the simplified transfer. As these banks do not use real money, you can make all the transfers you wish as your balance will never run out.

These banks, also, has on-screen instructions to allow for input, fill out codes and make transfers.

8. Correct library installation

We’ve generated libraries for the most popular programming languages. The following code shows how to install these libraries:

9. Internet access

To be able to access Khipu’s API REST it is necessary to have an Internet connection. This is required to be able to create and modify payments.

Each time Khipu receives a payment, the merchant is notified so that it can deliver the goods or services to the final customer. This notification can be an email or using the API instant notifications. The recommended mechanism is the instant notification as it doesn’t require human intervention once it’s configured. These notifications are Khipu invocations that Khipu must perform to a web service in the merchant website. Therefore, this web service must be visible from Internet.

10. Common use case

We will analyze the most common use case of the REST API, which is making a payment in a merchant’s web to obtain a product. The most common flow has the following steps:

• The customer chooses the products and selects to pay.
• The merchant creates a payment using the REST API.
• The merchant sends the customers to Khipu for payment.
• The customer pays.
• The customer is redirected to the merchant’s web site and waits while Khipu verifies the payment.
• The payment is verified, and the merchant is notified through web service.
• The merchant delivers the product or service.

Let’s see now the steps where the integration with Khipu is necessary:

11. Create a charge POST /payments

After the customer selects the product and chooses to pay, the payment process begins. The majority of electronic commerce software work in a similar way. They all have some type of object that symbolizes the purchase order. What we must do is relate this purchase order to a payment in Khipu.

Let’s see the following code:

In the first step we obtain the purchase order object. This can be created now or recovered through the “id”. In the next step a payment is created in Khipu using the associated library.

In the transaction_id parameter of the call the purchase order identifier is sent. This is necessary so that at the time of reconciliation we can obtain the purchase order and consider it paid.

The answer to the call will be an object with information about the charge created. The “payment_id” field contains the identifier of our payment and the url to which we must send the user to pay.

List of banks (optional) POST /banks

This step is optional but may be useful for some businesses. In the previous call to create payments you can see the parameter “ID of the bank to pay”. This ID is used to create a payment with an already chosen bank (only from the banks supported by Khipu). To obtain this id, you can use the banksGet call that provides the list of banks supported by Khipu, their names, their id and other information.

Let’s look at the following example:

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

12. Start Payment

Once a payment has been created, we must start the payment process. This can be done in two ways. The recommended way is to use our javascript library that will take care of the beginning of the payment. You can find extensive documentation on the github website. Also, you can use our library integration example that simulates a store that uses this library.

The other option to start 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 create payment call.

13. Customer is redirected to the merchant

After the customer makes the payment in the Khipu portal he/she will be redirected to the merchant web site. This merchant web site url must be configured for each payment in the “return_url” field, although it could be the same one for all payments.

It is very important to notice that when the user returns to the merchant page this doesn’t mean that the payment has been verified, so in the merchant web page must be stated that the payment is in the verification process and that they must wait.

The web page must periodically consult the merchant’s server to look up the status of the purchase order and inform the user when the payment has been confirmed.

For this, there are three strategies:

• Web-sockets: The merchant server informs the customer browser that the payment is confirmed so that it can be displayed. It is the most efficient way, but the most complex one to implement. More info at: https://en.wikipedia.org/wiki/WebSocket
• AJAX calls: The page verifies through an AJAX call to the merchant server about the state of the order. When the answer is positive the page notifies the user that the payment has been completed.
• Reload the page periodically. It’s the simplest mechanism and consists in using a timer to reload the page periodically, for example every 10 seconds. Every time the page loads the complete order is verified. If it is, the user is redirected to the success page. If not, it must indicate to the user that it is necessary to keep waiting and use a new timer.

14. Receive the notification and deliver the product/service GET /payments

If you have configured a URL to receive a notification, then Khipu will invoke immediately after reconciling the payment. This notification is received by Khipu’s instant notification API. This API version defines the way in which Khipu notifies the merchant.

There are several versions of the API, we will focus on the most recent one: 1.3. In this version, 2 parameters per POST will arrive, one with the version of the API “api_version”, used to verify that it is the correct version. Tthe second parameter is “notification_token”, By using notification_token we can obtain the information of the payment to be able to consider the product as paid.

Important: Khipu waits 30 seconds to receive a notification response. If, after 30 seconds, no answer is received, Khipu will try to notify again later. Therefore, if the process of receiving the notification takes more than 30 seconds, it needs to be done in the background as to respond immediately.

Let’s look at the following code: