Advanced usage examples

Send a payment email

You can set up Khipu to automatically send an email with the generated payment request. All you need to do is fill in a couple of fields when invoking the GET method /payments:

• payer_name : It is the name of the person who must pay.
• payer_email : It is the email address of the payer.
• send_email : If you send true, Khipu will send the payment request by email.

It is important to note a few things:

• If send_email is true , the other fields ( payer_name and payer_email ) will be required.
• The content of the body field is not sent in the email. It is only displayed on the payment page.
• If you also send true in the send reminders field along with true in the send email field, in addition to the initial payment request email, two reminder emails will be sent with a one-week interval between each, as long as the payment has not been paid or deleted at the time of managing the reminder.

Create a payment request and distribute it using its URL

You can have Khipu generate a payment link for you to use anywhere you want. All you need to do is fill in a couple of fields at the time of creation:

• payer_name : It is the name of the person who must pay.
• payer_email : It is the email address of the payer.
• send_email : false . (Use true if you also want Khipu to send an email with the payment request.)
• body : Text to be displayed on the payment page.

It is important to note a few things:

The content of the body field is not sent in the email. It is only displayed on the payment page. If send_email is true, you can also send true in the send_reminders parameter. By doing this, Khipu will send 2 payment reminders: one a week after the payment request and another one the following week.

Creating a payment request with an expiration date

Often, a payment should only be valid until a particular date, for example, purchasing a ticket for an event (after the event, it makes no sense to pay for it). For this, we can specify a maximum payment date or expiration date. After this date, the payment cannot be canceled.

The maximum date for a payment is sent in the expires_date parameter. This date has some conditions:

• It must be greater than the current date and time when the payment request is generated, and it must be less than that time plus 10 years.
• The date must be in the ISO 8601 , for example, you can apply a mask like yyyy-MM-ddTHH:mm:ss.fffzzz

Even if the expiration date is not sent, the payment will be generated with one. In the case of an email request (when send_email is true), the expiration is 60 days from the creation moment. Otherwise, the deadline is one day.

Sending merchant information for conciliation

Payments in Khipu have a variable called custom where you can store any type of information. This information can be retrieved at any time, for example, when we receive the notification via web service from Khipu.

We can retrieve the information from the custom field using the GET method /payments/{payment_id}.

Deleting a payment before the payer completes it

Sometimes it is necessary to delete a payment that has been generated, for example, if we run out of stock or encounter any problem in delivering the product/service. To delete a payment, it must not have been paid or marked as paid.

To delete a payment under the described conditions, we only need its identifier and use the DELETE method /payments/{payment_id}.

Integrator merchants

An integrator is a collection account in Khipu that has the ability to create child merchant accounts for their clients and collect payments, using Khipu, for them. For example, an integrator could be a company that provides online store service to several merchants, each merchant creates an online store in that service, using the same service creates a Khipu collection account, and collects payments online. The Khipu service allows the final merchant to collect for their products and the integrator to collect a commission.

We will call a child collection account each normal collection account that is associated with an integrator collection account. This is very important for when you need to send the credentials in each call. Additional collection accounts are created using the POST method

Creating a child collection account for an integrator

Child accounts are created using a special call. This call will return the credentials of a new collection account. We must save these credentials to be able to generate payments on behalf of this new account.

In this call, we need to send the following data:

• Email and name of the account owner. If the email exists in Khipu, the existing user will be used. If not, a new user will be created and the account will be associated with them.
• Country for the account: The country where the account will operate.
• Billing information: Information for issuing an invoice or receipt.
• Contact information: Information for Khipu to contact the account administrator.

It is very important to know that this account is not ready to collect payments. The creation process sends an email to the specified email address so that the account owner (the email owner) can complete the payment process. Only once this process is completed can the account start operating.

Creating a payment with integrator commission is identical to creating a normal payment but with two details:

• The integrator_fee parameter must be sent with the amount that the integrator will receive. This amount cannot exceed the original amount minus the Khipu commission.
• The credentials used for the call must be the credentials of the child account. This is because the payment must be made on behalf of this account.

Modifying the owner user of a payment

Each payment in Khipu is associated with a “responsible user” who is the owner of the payment. They receive copies of payment receipts and copies of weekly reminders. If the Khipu web interface is being used, the responsible user is always the one who creates the payment. If more than one person has access to the merchant's payment account, you can specify using the API who the owner of each payment created is, in the responsible_user_email field.

To specify a user as the owner of a payment, the user must be able to collect using the merchant's account.

Payment with authentication

It is possible to create payments that can only be paid using a bank account belonging to a specific person. This is done by specifying the personal identifier of the user. For example, a bank account in Chile is associated with a RUT (Unique Taxpayer Identification Number). If a specific RUT is specified for a payment, it can only be paid using an account associated with that RUT. The field for this purpose is fixed_payer_personal_identifier.

Refunding a payment that has not been settled

It is possible to refund the charge until 1:00 am the following business day. The customer will receive an email explaining that the merchant was unable to complete the transaction and that the funds will be returned to the customer's bank account.

The method is POST /payments/{payment_id}/refunds

Receiving and validating settlement notifications via web service

Khipu allows you to receive notifications on your website automatically with the details of each settlement made to the current account associated with your collection account.

Configuration

To receive notifications, first log in to your Khipu account and go to Account Options. In the Instant Settlement Notification section, you must add the URL where your website will listen for notifications and define the version of the notification API you want to use (3.0).

PHP Example

Settlement notifications are made using a message in standard JOSE JWS format, and gzipped.

The settlement notification messages are signed with the following certificate.

Download the public key certificate

If you are using a development collection account, you should use the Khipu development certificate.

Download the public key certificate (development)

This example utilizes the Namshi/Jose library:

<?php
require_once 'vendor/autoload.php';

use NamshiJOSEJWS;

$jws_text=gzdecode($HTTP_RAW_POST_DATA);

$jws=JWS::load($jws_text);

// Read the certificate
$filename = 'khipu_signer.pem';
$fp = fopen($filename, "r");
$cert = fread($fp, filesize($filename));
fclose($fp);
$pubkey = openssl_get_publickey($cert);

$payload = $jws->getPayload();

if ($jws->isValid($public_key)) {
/*
  If the message signature is valid, the message can be processed
*/

    $report=$payload['report'];
    $fecha_desde=$report['startDate']; // Start date of the settlement
    $fecha_hasta=$report['endDate']; // End date of the settlement
    $report_items=$report['items']; // Payments included in the settlement
    foreach($report_items as $item){
       $customer=$item['customer']; // Payer's information
       local_process($item['paymentDate'],       // Payment date
                     $item['paymentSubject'],    // Payment subject
                     $item['khOperationCodeUID'],// Unique Khipu operation code
                     $item['merchantTxID'],      // Merchant-reported transaction ID
                     $item['customer']['customerName'], // Payer's name
                     $item['customer']['customerUID'],  // Payer's ID number
                     $item['customer']['customerEmail'], // Payer's email
                     $item['customer']['customerBankName'], // Origin bank name
                     $item['feeScheme'], // Commission scheme
                     $item['txAmount'],  // Transaction amount
                     $item['khipuFee']); // Khipu commission
    }
}