(Versión Inglés) API - Steps to integrate Pagopar to my website

(Versión Inglés) API - Steps to integrate Pagopar to my website

Normal flow of purchase

  1. Step # 1: The shop creates an order in Pagopar. 
  2. Step # 2: The shop redirects to the Pagopar checkout page.  
  3. Step # 3: Pagopar notifies the shop of the payment.
  4. Step # 4: Pagopar redirects to the shop´s payment result page. 



Step # 1: The shop creates an order in Pagopar.  

Description
The shop generates an order in Pagopar, Pagopar returns a hash that will be used to build a URL.


Obs.
The value of public key and private key is obtained from the option “integrate with my website” from  Pagopar.com  
Token from this endpoint is generated: 

In PHP:

<?php sha1($datos['comercio_token_privado'] . $idPedido . strval(floatval($j['monto_total']))); ?>

Are you going to use third-party shipping methods offered by Pagopar? 

To do so, you must follow these additional steps explained in the documentation.

Method: POST

Sample data that the commerce would send to Pagopar: 
Content:

{
  "token": "fbe4586135e7f482d6c8ad624413139b9c90825f",
  "comprador": {
    "ruc": "4247903-7",
    "email": "fernandogoetz@gmail.com",
    "ciudad": null,
    "nombre": "Rudolph Goetz",
    "telefono": "0972200046",
    "direccion": "",
    "documento": "4247903",
    "coordenadas": "",
    "razon_social": "Rudolph Goetz",
    "tipo_documento": "CI",
    "direccion_referencia": null
  },
  "public_key": "98b97ce494801bf26575a5c4ff2d4f14",
  "monto_total": 100000,
  "tipo_pedido": "VENTA-COMERCIO",
  "compras_items": [
    {
      "ciudad": "1",
      "nombre": "Ticket virtual a evento Ejemplo 2017",
      "cantidad": 1,
      "categoria": "909",
      "public_key": "98b97ce494801bf26575a5c4ff2d4f14",
      "url_imagen": "http://www.example.com/d7/wordpress/wp-content/uploads/2017/10/ticket.png",
      "descripcion": "Ticket virtual a evento Ejemplo 2017",
      "id_producto": 895,
      "precio_total": 100000,
      "vendedor_telefono": "",
      "vendedor_direccion": "",
      "vendedor_direccion_referencia": "",
      "vendedor_direccion_coordenadas": ""
    }
  ],
  "fecha_maxima_pago": "2018-01-04 14:14:48",
  "id_pedido_comercio": "1134",
  "descripcion_resumen": ""
}

Explanation of data to be sent  

Field
Description
Example
tokenIt is generated as follows: sha1($datos['comercio_token_privado'] . $idPedido . strval(floatval($j['monto_total'])));fbe4586135e7f482d6c8ad624413139b9c90825f
comprador.rucBuyer's Tax ID. The field must be present; if there is no Tax ID, it should be provided with an empty value ('')4247903-7
comprador.emailBuyer's Email. Mandatory fieldfernandogoetz@gmail.com
comprador.ciudadIf you are not using the courier services offered by Pagopar (Only for physical products), you must still send the field with the value 1. Otherwise, refer to the courier integration documentation to obtain the city ID.1
comprador.nombreBuyer's Name. Mandatory field.Rudolph Goetz
comprador.telefonoPhone number in international format.+595972200046
comprador.direccionBuyer's Address. The field must be present; if there is no address, send the empty value ('').
comprador.documentoID Number. Mandatory field.4247903
comprador.coordenadasCoordinates of the buyer's address, if not available, send with the empty value.
comprador.razon_social
Buyer's business name, if not available, send the field with the empty value.

comprador.tipo_documento
Buyer's document type, for now, must always be sent with the value 'CI'.
CI
comprador.direccion_referencia
Buyer's address reference. The field must be present; if there is no reference, send it empty.

public_key
Public key obtained from Pagopar.com in the 'Integrar con mi sitio web' section.
98b97ce494801bf26575a5c4ff2d4f14
monto_total
Total amount to be transacted, in the currency 'Guaraníes (PYG)'.
100000
tipo_pedido
If it's a simple transaction, the value 'VENTA-COMERCIO' must be sent. If it's split billing, 'COMERCIO-HEREDADO'. 
VENTA-COMERCIO
compras_items.[0].ciudad
The buyer's city, if not available, send the value 1.
1
compras_items.[0].nombre
Name of the product or service being purchased. Mandatory.
Ticket virtual a evento Ejemplo 2017
compras_items.[0].cantidad
Quantity of the product being purchased, for informational purposes only.
1
compras_items.[0].categoria
If you are not using courier services offered by Pagopar (Only for physical products), you must still send the field with the value 909. Otherwise, refer to the courier integration documentation to obtain the category ID.
909
compras_items.[0].public_key
Seller's public key, if it is not a split billing transaction, it will be the same value as the 'public_key' field.
98b97ce494801bf26575a5c4ff2d4f14
compras_items.[0].url_imagen
Product image URL. If there is no image, send the field with the empty value.
compras_items.[0].descripcion
Description of the product being purchased.
Ticket virtual a evento Ejemplo 2017
compras_items.[0].id_producto
Identifier of the product/service being purchased.
895
compras_items.[0].precio_total
Total price of the product/service being purchased (It is not the unit price, but the total price grouped by product).
100000
compras_items.[0].vendedor_telefono
Buyer's phone number. If not available, it must be sent with the empty value.

compras_items.[0].vendedor_direccion
Seller's address. If not available, it must be sent with the empty value.
 

compras_items.[0].vendedor_direccion_referencia
Reference of the seller's address. If not available, it must be sent with the empty value.

compras_items.[0].vendedor_direccion_coordenadas
Coordinates of the seller's address. If not available, it must be sent with the empty value.

fecha_maxima_pago
It is the maximum date that the buyer has to pay the order. Once it reaches the specified date, the order is automatically canceled and can no longer be paid.
2018-01-04 14:14:48
id_pedido_comercio
Alfanumérico.Commerce order/transaction ID. It must be unique in both Development and Production environments. Alphanumeric.
1134
descripcion_resumen
Brief description of the order, it can match the value of purchases_items.[0].name or be sent with the empty value.
Ticket virtual a evento Ejemplo 2017

Sample data that Pagopar would return on success (returns the order hash):

{
    "respuesta": true,
    "resultado": [
        {
            "data": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
            "pedido": "1750"
} ] }

The 'data' field is the one you will use in your database to associate the data of each order; this field is mandatory to store. On the other hand, the 'pedido' field is used purely for informational purposes 

Keep in mind, the value of result.data is the order identifier.

Sample data that Pagopar would return in case of error:

{ "respuesta": false,
   "resultado": "Token no coincide."
}

You can see the details of the different types of errors that the execution of the 'iniciar-transacción' endpoint might return.

Step # 2: The commerce redirects to the Pagopar checkout page.

Description 
The commerce redirects to the page Checkout of Pagopar, with the data obtained in the  first step. Before redirecting, the commerce identifier must be associated with the Order hash.

Example in PHP: 



Pagopar Checkout page:





Do you have automatic redirection permission? 

This feature is only available to some shops upon request and approval. This serves to “skip” Pagopar  screen by implementing payment methods in the shop website, in such a way that final customer selects  the payment method on the shop website, clicks “Finalize purchase” and won´t see Pagopar screen. You  will only see the vPOS page to pay with a credit card (in case you have selected that payment method),  and in case you have selected a collection point you will see the redirection screen of the shop site, not  the Pagopar screen.

To indicate which payment method have been selected, simply add the parameter when redirecting to  the Pagopar platform.

 https://www.pagopar.com/pagos/$hash?forma_pago=' + idPaymentMethod; 

List of payment methods 

Id

Payment Method

Image URL

9

Bancard - Credit/Debit Cards (Accepts Visa, Mastercard, American Express, Discover, Diners Club, and Credifielco.

https://cdn.pagopar.com/assets/images/plugins/woocommerce/tarjetas-credito.png

1

Procard - Credit/Debit Cards (Accepts Visa, Mastercard, Credicard, and Unica).

https://cdn.pagopar.com/assets/images/plugins/woocommerce/tarjetas-credito.png

2

Aqui Pago

https://cdn.pagopar.com/assets/images/pago-aquipago.png

3

Pago Express

https://cdn.pagopar.com/assets/images/pago-pagoexpress.png

4

Practipago

https://cdn.pagopar.com/assets/images/pago-practipago.png

10

Tigo Money

https://cdn.pagopar.com/assets/images/pago-tigo-money.png

11
Transferencia Bancaria

12

Billetera Personal

https://cdn.pagopar.com/assets/images/pago-billetera-personal.png

13

Pago Móvil

https://cdn.pagopar.com/assets/images/pago-infonet-pago-movil.png

15

Infonet Cobranzas

https://cdn.pagopar.com/assets/images/pago-infonet.png

18
Zimple
20
Wally
 22
 Wepa
23
Giros Claro
 24
QR payments


List of payment methods via WS

Token for this endpoint is generated:

 sha1(Private_key + “FORMA-PAGO”) 


In PHP: sha1($datos['comercio_token_privado'] . “FORMA-PAGO”)


Method: POST

Sample data that the shop will send to Pagopar:

Content:

{
    "token": "cebe636c26b55ec95309260941f5a2c00be9b0b6",
    "token_publico": "98b97ce494801bf26575a5c4ff2d4f14"
}

Sample data that Pagopar will return for the previous request:
Content:
{
    "respuesta": true,
    "resultado": [
        {
            "forma_pago": "25",
            "titulo": "PIX",
            "descripcion": "PIX vía QR",
            "monto_minimo": "1000",
            "porcentaje_comision": "3.00"
        },
        {
            "forma_pago": "24",
            "titulo": "Pago QR",
            "descripcion": "Pagá con la app de tu banco, financiera o cooperativa a través de un QR",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "18",
            "titulo": "Zimple",
            "descripcion": "Utilice sus fondos de Zimple",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "9",
            "titulo": "Tarjetas de crédito",
            "descripcion": "Acepta Visa, Mastercard, American Express, Cabal, Panal, Discover, Diners Club.",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82",
            "pagos_internacionales": false
        },
        {
            "forma_pago": "10",
            "titulo": "Tigo Money",
            "descripcion": "Utilice sus fondos de Tigo Money",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "11",
            "titulo": "Transferencia Bancaria",
            "descripcion": "Pago con transferencias bancarias. Los pagos se procesan de 08:30 a 17:30 hs.",
            "monto_minimo": "1000",
            "porcentaje_comision": "3.30"
        },
        {
            "forma_pago": "12",
            "titulo": "Billetera Personal",
            "descripcion": "Utilice sus fondos de Billetera Personal",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "13",
            "titulo": "Pago Móvil",
            "descripcion": "Usando la App Pago Móvil / www.infonet.com.py",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "20",
            "titulo": "Wally",
            "descripcion": "Utilice sus fondos de Wally",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "23",
            "titulo": "Giros Claro",
            "descripcion": "Utilice sus fondos de Billetera Claro",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "22",
            "titulo": "Wepa",
            "descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "2",
            "titulo": "Aqui Pago",
            "descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "3",
            "titulo": "Pago Express",
            "descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        },
        {
            "forma_pago": "15",
            "titulo": "Infonet Cobranzas",
            "descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
            "monto_minimo": "1000",
            "porcentaje_comision": "6.82"
        }
    ]
}

Step # 3: Pagopar notifies the shop of the payment.


Description
Pagopar makes a request to the response URL specifies in the option “Integrate with my website” of  Pagopar.com. In this endpoint, the shop must put “paid” as the specified order in thier system,  therefore this point is critical, because if someone knew the response URL, knowing the API and how it  works, they could put as “Paid” some orders in the shop system. In order to avoid that, it is strictly  necessary to validate the token before updating the order status to Paid. This avoids the  aforementioned, since the private key is used to generate the token, which should never be shared or  exposed.  
The shop must return Code 200, in case shop does not return that status Code, either due to a  connectivity problem, a fallen server or similar, Pagopar will notify about the payment every 10 minutes  until you get the correct answer.

Obs
The value of public key and private key is obtained from the option “Integrate with my website” from  Pagopar.com 
At this point Token is generated as follows: sha1(private_key + hash_pedido) 


Method: POST

Sample data that Pagopar would send to the Merchant in case of a paid order:
Content:
{
  "resultado": [
    {
      "pagado": true,
      "numero_comprobante_interno": "8230473",
      "ultimo_mensaje_error": null,
      "forma_pago": "Tarjetas de crédito/débito",
      "fecha_pago": "2023-06-07 09:11:49.52895",
      "monto": "100000.00",
      "fecha_maxima_pago": "2023-06-14 09:11:32",
      "hash_pedido": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
      "numero_pedido": "1746",
      "cancelado": false,
      "forma_pago_identificador": "1",
      "token": "9c2ed973536395bf3f91c43ffa925bacadcf58e5"
    }
  ],
  "respuesta": true
}

Sample data that the Merchant must respond to Pagopar in case of a paid order:
Content:
[
    {
      "pagado": true,
      "numero_comprobante_interno": "8230473",
      "ultimo_mensaje_error": null,
      "forma_pago": "Tarjetas de crédito/débito",
      "fecha_pago": "2023-06-07 09:11:49.52895",
      "monto": "100000.00",
      "fecha_maxima_pago": "2023-06-14 09:11:32",
      "hash_pedido": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
      "numero_pedido": "1746",
      "cancelado": false,
      "forma_pago_identificador": "1",
      "token": "9c2ed973536395bf3f91c43ffa925bacadcf58e5"
    }
  ]


Sample data that Pagopar would send to the Merchant in case of a reversal:
Content:
{
    "resultado": [
        {
            "pagado": false,
            "numero_comprobante_interno": "8230473",
            "ultimo_mensaje_error": null,
            "forma_pago": "Tarjetas de crédito/débito",
            "fecha_pago": null,
            "monto": "100000.00",
            "fecha_maxima_pago": "2018-01-04 23:40:36",
            "hash_pedido": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
            "numero_pedido": "1746",
            "cancelado": false,
            "forma_pago_identificador": "1",
            "token": "aec22cacc0415f067f0da57ce5148085b36cd067"
        }
    ],
    "respuesta": true
}


Sample data that the Merchant must respond to Pagopar in case of a reversed order:
Content:
[
    {
        "pagado": false,
        "numero_comprobante_interno": "8230473",
        "ultimo_mensaje_error": null,
        "forma_pago": "Tarjetas de crédito/débito",
        "fecha_pago": null,
        "monto": "100000.00",
        "fecha_maxima_pago": "2018-01-04 23:40:36",
        "hash_pedido": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
        "numero_pedido": "1746",
        "cancelado": false,
        "forma_pago_identificador": "1",
        "token": "aec22cacc0415f067f0da57ce5148085b36cd067"
    }
]

Sample data that Pagopar would send to the Merchant in case of a confirmed (pending payment) order for reversal:
Content:
{
    "resultado": [
        {
            "pagado": false,
            "numero_comprobante_interno": "8230473",
            "ultimo_mensaje_error": null,
            "forma_pago": "Pagoexpress",
            "fecha_pago": null,
            "monto": "100000.00",
            "fecha_maxima_pago": "2018-01-04 23:40:36",
            "hash_pedido": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd",
            "numero_pedido": "1746",
            "cancelado": false,
            "forma_pago_identificador": "3",
            "token": "aec22cacc0415f067f0da57ce5148085b36cd067"
        }
    ],
    "respuesta": true
}

In terms of code : We recommend that the merchant directly returns the content of the JSON result sent by Pagopar, thus avoiding manually constructing the JSON, optimizing code and functionality (additional adjustments to JSON construction will be avoided in case there are updates in the structure of the JSON sent by Pagopar).

Obs: These payment notifications are made only when the payment for the order is completed and are done according to the transaction status (paid/reversed).


Example of Token validation in Woocommerce/PHP.:
Content:
<?php $rawInput = file_get_contents('php://input');
 $json_pagopar = json_decode($rawInput, true); 
global $wpdb; 
#We obtain the Order ID 
$order_db = $wpdb->get_results($wpdb->prepare( "SELECT id FROM wp_transactions_pagopar WHERE hash = %s ORDER BY id DESC LIMIT 1", $json_pagopar['result'][0]['hash_pedido'])); 

#We obtain the Private Key
$db = new DBPagopar(DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, "wp_transactions_pagopar"); 
$pedidoPagopar = new Pagopar(null, $db, $origin_pagopar); 
$payments = WC()->payment_gateways->payment_gateways(); 
#If the tokens match, this validation is strictly mandatory to prevent malicious use of this endpoint
if (sha1($payments['pagopar']->settings['private_key'] . $json_pagopar['result'][0]['hash_pedido']) === $json_pagopar['resultado'][0]['token']) { 
#We mark it as paid if it has already been paid 
if (isset($order_db[0]->id)) { 
if ($json_pagopar['result'][0]['pagado'] === true) { 
$order_id = $order_db[0]->id; 
global $woocommerce; 
$customer_order = new WC_Order((int) $order_id); 

//We mark the order as Paid 
$customer_order->payment_complete(); 
$customer_order->update_status('completed', 'Order Completed/Paid.'); 
} elseif ($json_pagopar['result'][0]['pagado'] === false) { 
//We mark the order as Pending 
            } 
      } 
} else { 
echo 'Token does not match'; 
return ''; 
} 
echo json_encode($json_pagopar['result']); 
?>


It is extremely important to verify that the token sent by Pagopar is the same as the token generated by the merchant, to prevent individuals who may know your response URL from making requests and affecting the status of your orders, for example, marking them as Paid. 

Step # 4: Pagopar redirects to the shop´s payment result page.


Description 
Pagopar redirects to the result page specified in the option “Integrate with my website” from  Pagopar.com, with the order hash. In that moment the shop makes a request to Pagopar to know the  status of that order in real time, and accordingly it shows the message of Paid / Error when paying  /Pending Payment.


Obs
The value of public key and private key is obtained from the option “Integrate with my website” from  Pagopar.com 
At this point the Token is generated as follows: Sha1(Private_key + "CONSULTA") 


Example URL to which Pagopar will redirect: https://www.mywebsite.com/pagopar/result/
Method: GET


The URL to which the Merchant will make the request: https://api.pagopar.com/api/pedidos/1.1/traer
Method: POST


Example data that the merchant will send to Pagopar:

Content
{
  "hash_pedido": "b1d98a906be9d0dc6956ead8642e0d6393abe9a6fd2743663109aa90e4d73e59",
  "token": "cebe636c26b55ec95309260941f5a2c00be9b0b6",
  "token_publico": "98b97ce494801bf26575a5c4ff2d4f14"
}

Example data that Pagopar will return for the previous request:
Content:
{
  "respuesta": true,
  "resultado": [
    {
      "pagado": false,
      "forma_pago": "Pago Express",
      "fecha_pago": null,
      "monto": "100000.00",
      "fecha_maxima_pago": "2018-01-05 02:09:37",
      "hash_pedido": "b1d98a906be9d0dc6956ead8642e0d6393abe9a6fd2743663109aa90e4d73e59",
      "numero_pedido": "1750",
      "cancelado": true,
      "forma_pago_identificador": "3",
      "token": "fa443e1b63c7a51bd14732ed22098c62b7ebb4dd",
      "mensaje_resultado_pago": {
        "titulo": "Pedido pendiente de pago",
        "descripcion": "<ul><li>  Eligió pagar con Pago Express, recuerde que tiene hasta las
             02:09:37 del 05/01/2018 para pagar.</li><li>  Debe ir a boca de cobranza de Pago Express,
             decir que quiere pagar el comercio <strong>Pagopar</strong>, mencionando su cédula <strong>
            0</strong> o número de pedido <strong>1.750</strong>.</li></ul>"
      }
    }
  ]
}



Pagina de redireccionamiento Pagina de redireccionamiento


Following the completion of the steps in this documentation, the only remaining task is to transition to production.
























    • Related Articles

    • API - Integración de medios de pagos

      Flujo normal de compra Paso #1: El comercio crea un pedido en Pagopar Paso #2: El comercio redirecciona a la página de Checkout de Pagopar Paso #3: Pagopar notifica al comercio sobre el pago Paso #4: Pagopar redirecciona a la página del resultado de ...
    • Pagopar Login

      ¿Qué es Pagopar Login? Pagopar Login es una herramienta que te permite conectar una cuenta de usuario de tu sitio web con una cuenta específica (comercio) de Pagopar. Esto puede ser muy útil cuando se utiliza Split Billing, ya que Pagopar retorna los ...
    • Transacciones con divisa en USD

      Iniciar transacción con divisa en USD Descripción general Pagopar ha ampliado sus funcionalidades para cobrar pagos en dólares estadounidenses (USD). Para realizar cobros en USD, es necesario configurar el cobro de tus ventas con transferencia ...
    • Integración de Servicios de pickup/delivery - Versión 1.1

      Hemos actualizado la versión de servicio de Pickup/delivery a la versión 2.0, el cual agrega más opciones de envío por parte de AEX, además de agregar un nuevo proveedor llamado MOBI. Recomendamos altamente integrar la versión 2.0 para mayor soporte ...
    • Integración de Billetera Personal en el sitio del comercio

      La integración del medio de pago Billetera Personal ya está incluida en la API de integración de medios de pagos, es decir, ya integrando dicha API tenés disponible el medio de pago seleccionado, no obstante, si se quiere incrustar todo el medio de ...