Todas las colecciones
Instalación
Pago Fácil API Documentation
Pago Fácil API Documentation

This documentation is aimed at those who want to create their own connections with the platform from web services, platforms or applications

Amanda avatar
Escrito por Amanda
Actualizado hace más de una semana

Payment Process

The payment proccess begings with the creation of Pago Fácil transaction through a POST to endponint initTransaction corresponding to the environment you want to create the transaction (Desarrollo, Beta and Producción).

Endpoints

Here you can find the different points that will be used to create the transactions.

Distinction of the environments

  • Desarrollo (Development): Here you can make your integrations and tests. All the information used on this server is completely fictitious.

  • Beta: These endpoints work with production data, but it have the new features that are still being tested. Features like new payment methods can change before you move on to the production server.

  • Producción (Production): In this environment you will find all the functionalities already tested and it is possible that it is the only one you need to access.

Dashboards

In the dashboards you will create the different services you'll be using on the platform. It is important to know that although the users are the same for the development and production server, the associated services are completely different.

Create transaction

In order to create a transaction you can use the following endpoints per POST (URL ENCONDED) depending on the environment you want to connect to. All endpoints only accept HTTPS connections. Remember to review the section on how to create a transaction to see the data needed to initialize the payment.

Example

Example of a transaction using Pago Fácil

Redirects to a single payment method

In case you do not want to show the list of payment methods, you can specify the payment method with which you want to make the transaction by doing the post to the initTransaction. Example:

POST: https://gw-dev.pagofacil.cl/initTransaction?method=WebPayPST

The above example skip the screen where the different payment methods are displayed, and go directly to BCI Pagos. The methods currently supported are as follows:

  • BCI Pagos (VISA - MASTERCARD): Open the payment window (credit and debit cards).

  • MultiCajaCupon: Open the payment window through MultiCaja (cash).

  • Pago46: Open the Pago46 payment page directly (cash).

  • MACH: Prepaid card payment method

Create a transaction

List of functions related to the creation and payment of a transaction.

InitTransaction

This endpoint initializes a transaction through a form-generated post method. Returns a page with all payment methods available for a particular currency.

Request InitTransaction

All the variables are required.

  • x_account_id (String): Corresponds to the service Token Service that you want to generate the transaction.

  • x_amount (Number): Amount of the transaction. Supports decimals if the currency used uses them.

  • x_currency (String): Currency to be used for the transaction. Example, CLP, USD, BOB.

  • x_reference (String): "You" order number. This number should be unique for service so as not to have a duplication of payments problem.

  • x_customer_email (String): Mail where the payment confirmation will be sent to the customer.

  • x_url_complete (String): Address where you will be redirected when completing the transaction. A POST will be sent to this URL with the same callback data explained in the Response section.

  • x_url_cancel (String): Address where it will be redirected in case of cancellation. It is recommended to use the address of the shopping cart.

  • x_url_callback (String): Address where you will be notified of transaction changes asynchronously through a POST method.

  • x_signature (String): Message signed. Please check the Signing process section to find out how to generate it.

  • x_shop_country (ISO-3166-1alpha-2): For example, CL, US. 

  • x_session_id (String): Unique identifier of the user's session that makes the payment. It is added as a security layer to validate the transaction.

Response initTransaction

The response is executed on two occasions. As a callback behind the payment flow to the designated URL for this purpose, in addition to returning to the complete URL also designated. While you do not need to verify the information in the two moments, we recommend it.

  • x_account_id (String): Corresponds to the service Token Service that you want to generate the transaction.

  • x_amount (Number): The amount associated with the order. It can be decimal in case the currency allows it.

  • x_currency (String): Currency to be used for the transaction.

  • x_gateway_reference (Number): Corresponds to the transaction ID on the platform (BigInt).

  • x_reference (String): Corresponds to the order number in your store.

  • x_result (String): Order status. They can be completed, failed or pending.

  • x_timestamp (String): Time the order was completed in UTC. ISO-8601 in UTC (2018-03-24T12:15:41Z).

  • x_test (Boolean): Identifies if the order was performed in the test environment (true/false).

  • x_signature (String): Message signed. Please check the Signing process section to find out how to generate it.

Signing process

How does it work?

To validate information is sent from the appropriate person, this is verified through a signature generated by the HMAC SHA256 algorithm. To generate this signature you need a secret key (Token Secret) that is provided when you generate the service in Pago Fácil. How well it says its name, this key is secret and should not be shared with anyone, as this could cause that the information of the state of the transaction is not trustworthy.

This process is not complex but it is important to follow the steps in order so that it does not become frustrating

Process

  1. You must get an array with all the variables that start with x _ from the body of the POST (AKA: Payload).

  2. This array must be sorted alphabetically.

  3. Once the array is obtained, a string is created with all the variables and their concatenated values.

  4. The resulting string is signed with the SHA256 algorithm mentioned above.

Example in Ruby

def sign(fields, key=@key)
Digest::HMAC.hexdigest(fields.sort.join, key, Digest::SHA256)
end

Example in JavaScript

//Remember that the array must always be ordered before signing.
let sortedArray = Object.entries(payload).sort();

function signPayload(payload, secret, prefix = "x_", signature = "signature") {
    console.log("signPayload");
    let payloadFirmado;
    let firma = prefix + signature;
    let mensaje = "";
    for (let index = 0; index < payload.length; index++) {
        console.log(payload[index]);
        if (payload[index][0] != firma) {
            mensaje += payload[index][0] + payload[index][1];
        }
    }
    let hmac = crypto.createHmac('sha256', secret);
    hmac.setEncoding('hex');
    hmac.write(mensaje);
    hmac.end();
    payloadFirmado = hmac.read();
    return payloadFirmado;
}

Example in PHP

function firmarArreglo($arreglo) {
    //Order Array
    ksort($arreglo);
    //Concatenate Array
    $mensaje = $this->concatenarArreglo($arreglo);
    //Signature Message
    $mensajeFirmado = $this->firmarMensaje($mensaje, $this->ct_token_secret);
    //Save and return the signed message
    $this->ct_firma = $mensajeFirmado;
    return $mensajeFirmado;
}
function firmarMensaje($mensaje, $claveCifrado) {
    $mensajeFirmado = hash_hmac('sha256', $mensaje, $claveCifrado);
    return $mensajeFirmado;
}
public function concatenarArreglo($arreglo) {
    $resultado = "";
    foreach ($arreglo as $field => $value) {
        $resultado .= $field . $value;
    }
    return $resultado;
}

PHP SDK

In this section you can find the instructions to make use of the PHP SDK available for Pago Fácil connections.

Installation

To install the library it is recommended to make use of composer using the command:

composer require pagofacil/php-sdk

Use

To make use of the library, you must first load the autoload file generated by composer:

include_once 'vendor/autoload.php';

After this, calls to the Request and Transaction classes must be made through their namespaces, leaving the code as follows:

include_once 'vendor/autoload.php';
use PagoFacil\lib\Request;
use PagoFacil\lib\Transaction;

Once the required classes are imported the process starts to generate a payment. For this you must create a variable type request, where you must complete the necessary parameters to start the transaction as follows:

$request = new Request(); // The Request object is created

$request->account_id = ''; // Token Service delivered by Pago Fácil
$request->amount = 0; // Transaction amount
$request->currency = 'CLP'; // Transaction currency
$request->reference = ''; // Order number of the store
$request->customer_email = ''; // Customer's email
$request->url_complete = ''; // URL to which the system is redirected
$request->url_cancel = ''; // Cancellation URL
$request->url_callback = ''; // Response URL
$request->shop_country = 'CL'; // ISO country code
$request->session_id = date('Ymdhis').rand(0,9).rand(0,9).rand(0,9); // Session ID

After having this variable creates a new transaction to which is passed by parameter the variable request created earlier:

$transaction = new Transaction($request); // The transaction is created
$transaction->environment = 'DESARROLLO'; // It specifies the environment in which one is going to work. It can be DESSARROLLO, BETA or PRODUCCION

$transaction->setToken(''); // The Token Secret delivered by Pago Fácil must be colocal

$transaction->initTransaction($request); // The transaction is started sending the created request by parameters

When making the call to initTransaction the system redirects to Pago Fácil to do the transaction. Once is done, the system send by POST a response to the URL specified in url_callback. At this point you must verify that both the signature and the amount matches.

To verify the signature you can make use of the function validate() of the transaction. This function is passed by parameters an array with the data received from the POST. For example:

$transaction = new Transaction();
$transaction->setToken(''); // The Token Secret delivered by Pago Fácil must be colocal

if($transaction->validate($_POST)){
    error_log('TRANSACCION CORRECTA');
}else{
    error_log('ERROR FIRMA');
}

After the validate is done, a check of the received amount must be made to have greater security of the response, as well as any other verification that you wish to do.

If the answer is OK the system will send to the URL specified in url_complete. Once in that direction you must verify again that the signature and amount correspond. For example:

$transaction = new Transaction();
$transaction->setToken(''); // The Token Secret delivered by Pago Fácil must be colocal

if($transaction->validate($_POST)){
    echo 'Orden recibida exitosamente';
    error_log('TRANSACCION CORRECTA');
}else{
    echo 'Error en firma';
    error_log('ERROR FIRMA');
}

After the validate is done, a check of the received amount must be made to have greater security of the response, as well as any other verification that you wish to do.

¿Ha quedado contestada tu pregunta?