Receive Wire Transfers

October 25, 2023

Your customers will be able to use the balance in their bank account to make purchases on your website or application

Allow your customers to use the available balance in their bank account to purchase your products or services from your iOS app via a PSE or PSE Avanza. To do so, you must enable the list of banks available in Colombia, obtain the basic data of your paying customers and redirect them to the website of their virtual bank branch to authorize the debit to their bank account.

The payment flow for PSE (Version 1.0) that you will integrate is as follows:

The payment flow for PSE Avanza (Version 2.0) that you will integrate is as follows:

With this version we improve the user experience allowing your customers to purchase in fewer steps.

1. Set up your App

The APP is responsible for collecting the basic user’s payment data, generating a token for that information through Kushki’s servers, and sending that information to your back end to start the payment process.

Install Kushki’s SDK

We will use CocoaPods for its installation. If you do not have it already installed, you can get the latest version here.

Embed the library in your project, by adding the following line to your Podfile:

pod 'Kushki', '~> 2.4.2'

Then run the following command:

pod install

For updating to the latest version, run this:

pod update Kushki

Set it up

let publicMerchantId = "public-merchant-id"
let kushki = 
  Kushki(
    publicMerchantId: publicMerchantId,
    currency: "USD",
    environment: KushkiEnvironment.testing
  )

Request the list of banks

Before generating the token, you need to load the complete list of available banks, so that the paying customer can select the entity to make the transfer:

  var callback = function(response) {
  if(!response.code){
    console.log(response);
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
}

kushki.requestBankList(callback); // Also you can set the function directly

Request the Token and submit it to your Back End

Once the user enters their payment information in the form, use the following example to obtain the token and submit it:

private func requestKushkiTransferToken(amount: Amount, callbackUrl:String, userType:String, documentType:String, documentNumber:String, email:String, description:String) {
        let publicMerchantId = "publicMerchantId"
        let kushki = Kushki(publicMerchantId: publicMerchantId,
                            currency: "USD",
                            environment: KushkiEnvironment.testing)
        kushki.requestTransferToken(amount: amount, callbackUrl: callbackUrl, userType: userType, documentType: documentType, documentNumber: documentNumber, email: email,paymentDescription: description) { transaction in
            let message = transaction.isSuccessful() ?
                transaction.token : transaction.code + ": " + transaction.message
            //                transaction.code + ": " + transaction.message
            DispatchQueue.main.async(execute: {
                let alert = UIAlertController(title: "Kushki Token",
                                              message: message,
                                              preferredStyle: UIAlertController.Style.alert)
                alert.addAction(UIAlertAction(title: "Ok", style: .default))
                self.present(alert, animated: true)
            })
            self.ResponseView.text = "Response transfer token: \n\n" + message
        }
    }

2. Set up your Back-end

The back end is responsible for receiving the token obtained from your front end and starting the payment process with Kushki.

When the user submits the form, your front end sends a token to an endpoint that you specified previously. Using this token, you must make a call to our charge endpoint to start the charge process.

var request = require("request");
var options = {
       method: 'POST',
       headers: ['Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
           'content-type': 'application/json'
       ]
       url: 'https://api-uat.kushkipagos.com/transfer/v1/init', // Ambiente de prueba
       headers: {
           'content-type': 'application/json'
       },
       body: {
           "token": "b1d6f46f88fe4759aad9ae0e37cdf905",
           "amount": {
               "subtotalIva": 0,
               "subtotalIva0": 90000,
               "iva": 0,
           },
           "contactDetails": {
               "fullName": "John Doe",
               "address": "Centro 123",
               "email": "test@kushkipagos.com",
               "phoneNumber": "3912345678"
           },
           "metadata": {
                  "userId": "IB344"
           }
    }
           };
           json: true
       };
       request(options, function(error, response, body) {
           if (error) throw new Error(error);
           console.log(body);
       });

import requests

url = "https://api-uat.kushkipagos.com/transfer/v1/init"

payload = "{\n  \"token\":\"b1d6f46f88fe4759aad9ae0e37cdf905\",\n  \"amount\": {\n  \"subtotalIva\": 0,\n  \"subtotalIva0\": 90000,\n  \"iva\": 0,\n  }\n  },\n  \"contactDetails\": {\n  \"fullName\": \"John Doe\",\n  \"address\": \"Centro 123\",\n  \"phoneNumber\": \"3912345678\"\n  },\n  \"email\": \"test@kushkipagos.com\"\n  },\n  \"metadata\": {\n  \"userId\": \"IB344\"\n  }\n}"
headers = {'content-type': 'application/json'}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
 "token": "b1d6f46f88fe4759aad9ae0e37cdf905",
 "amount": {
   "subtotalIva": 0,
   "subtotalIva0": 90000,
   "iva": 0,
 },
 "contactDetails": {
   "fullName": "John Doe",
   "address": "Centro 123",
   "email": "test@kushkipagos.com",
   "phoneNumber": "3912345678"
 },
 "metadata": {
   "userId": "IB344"
 }
}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/transfer/v1/init');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
 'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

• For PSE (Version 1.0)

According to the consumption response of the method to initiate the transaction, redirect the user to PSE using the redirectUrl parameter, so that your customer can authenticate and authorize the transaction amount to be debited from the balance of his/her bank account.

• For PSE Avanza (Version 2.0)

According to the consumption response of the method to initiate the transaction, redirect the user to the URL that Kushki returns, so that your customer can authenticate in the virtual portal of his/her bank entity and authorize the transaction amount to be debited from the balance of his/her bank account.

Muestra el resultado de la transacción

Once the payment is completed in the PSE portal (Version 1.0) or in the bank’s website (Version 2.0), the customer will receive a GET callback to the callbackUrl you specified when requesting the token.

Along with the return URL we will send you on the transaction token route, with which you can check the status of the transaction using this endpoint. In addition, you will obtain the necessary information for your customer’s payment voucher.

For example, for callbackUrl = 'http://www.example.com' the customer will return to:

GET https://www.example.com/?token=26735cbb653a421ba7138eb515e0ab1d

where token is equal to 26735cbb653a421ba7138eb515e0ab1d

According to the response that you receive from the transaction status, it shows the user a success or failure screen to inform the customer whether the payment was made correctly or if there was an error.

3. Test your Integration

There are test identification numbers that you can use to ensure that your integration is ready. Use them to simulate any status:

• Approved transaction: 123456789
• Pending transaction: 999999990
• Transaction not authorized ('NOT_AUTHORIZED'): 100000002
• Failed transaction ('FAILED'): Any identification number

4. Prepare your Certification

Read the following guidelines for technical certification approval (required to obtain productive account credentials):

• The calculation of taxes and the total amount must be the correct amount.
• Messages displayed on the screen are in line with Kushki’s responses.
• All Kushki responses must be saved and recorded (required in case you need support).
• The customer must recognize the payment method being used, therefore you must include the PSE logo.
• You can show the payment method, such as:
  • Debit from checking/savings account
  • PSE bank debit
• Avoid using the following texts:
  • Wire transfer
  • Debit to account
• For redirection, do not use containers such as Frame, Panel, IFrame, etc. Avoid functions such as pop-ups that are blocked by browsers, or redirect in the same tab or window.
• In the payment voucher, add the following information:
  • Name of your company (Name or corporate name)
  • NIT of your company (TIN)
  • Payment description
  • Transaction date
  • Transaction status
  • Traceability code (CUS)
  • Transaction number
  • Bank
  • Amount
• Display the transaction status as shown below:
  • ProcessorState OK:APROBADA The status must not be displayed in English. In addition, avoid the use of synonyms, such as: successful, authorized, accepted, paid or affirmative.
  • ProcessorState PENDING:PENDIENTE The status must not be displayed in English. In addition, avoid the use of synonyms, such as: pending confirmation, unresolved or incomplete.
  • ProcessorState NOT_AUTHORIZED:RECHAZADA The status must not be displayed in English. In addition, avoid the use of synonyms, such as: declined, canceled, rejected.
  • ProcessorState FAILED:FALLIDA The status must not be displayed in English. In addition, avoid the use of synonyms, such as: fail or error.
• Include within the payment receipt, a link (button) to access a query module showing the following basic data: CUS, amount, transaction date, current status. Companies that do not require authentication with username and password to make payments will not have to build the query module.
• Include an option to download and print the receipt.
• If the transaction is PENDING, a new transaction must NOT be allowed until the final status of the transaction is approved or rejected.
• The transaction cannot be PENDING:PENDIENTE for more than 21 minutes.
• All statuses must include the text with a phone number and an email address of your company, where your customers can check the transaction status.
• In the event of successful receipt of the Webhook notification, respond to the request with a statusCode 200, and inform your customer.
• The ”Pay” button is disabled after the first click.
• Kushki’s logo must be visible for the customer. You can find our logo in several formats here.
• Make sure to send all the variables required, specified in the API reference.