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 pago del Comercio
Paso #1: El comercio crea un pedido en Pagopar
Descripción
El comercio genera un pedido en Pagopar, Pagopar retorna un hash que servirá para armar una URL
Observación
El valor de public key y private key se obtiene desde la opción “Integrar con mi sitio web” de Pagopar.com
Token para este endpoint se genera:
En PHP:
<?php sha1($datos['comercio_token_privado'] . $idPedido . strval(floatval($j['monto_total']))); ?>
¿Vas a utilizar medios de envíos tercerizados ofrecidos por Pagopar?
Para ello, debes seguir estos pasos adicionales explicados en la documentación.
Método: POST
Datos de ejemplo que el Comercio enviaría a Pagopar:
Contenido:
{
"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": ""
}
Explicación de datos a enviar
Campo | Descripción | Ejemplo |
| token | Se genera de la siguiente forma: sha1($datos['comercio_token_privado'] . $idPedido . strval(floatval($j['monto_total']))); | fbe4586135e7f482d6c8ad624413139b9c90825f |
| comprador.ruc | Ruc del comprador. El campo debe estar presente, si no tiene ruc, debe ir con el valor vacío ("") | 4247903-7 |
| comprador.email | E-mail del comprador. Campo obligatorio. | fernandogoetz@gmail.com |
| comprador.ciudad | Si no está utilizando los servicios de couriers ofrecidos por pagopar (Sólo para productos físicos), debe enviar de todas formas el campo con el valor 1. De lo contrario utilizar la documentación de integración de couriers para obtener el ID de ciudad | 1 |
| comprador.nombre | Nombre del comprador. Campo obligatorio. | Rudolph Goetz |
| comprador.telefono | Número de teléfono en formato internacional. | +595972200046 |
| comprador.direccion | Dirección del comprador. El campo debe estar presente, si no tiene dirección, enviar el valor vacío (""). | |
| comprador.documento | Número de cédula. Campo obligatorio. | 4247903 |
| comprador.coordenadas | Coordenadas de la dirección del comprador, si no tiene, enviar con el valor vacío. | |
comprador.razon_social | Razón social del comprador, si no tiene, enviar el campo con el valor vacío. | |
comprador.tipo_documento | Tipo de documento del comprador, por el momento siempre debe enviarse el valor "CI". | CI |
comprador.direccion_referencia | Referencia de la dirección del comprador. El campo debe estar presente, si no tiene referencia, enviar vacío. | |
public_key | Clave publica obtenida desde Pagopar.com en el apartado "Integrar con mi sitio web" | 98b97ce494801bf26575a5c4ff2d4f14 |
monto_total | Monto total que se va a transaccionar, en guaranies (PYG). | 100000 |
tipo_pedido | Si se trata de una transacción simple, debe enviarse el valor "VENTA-COMERCIO". Si es split billing "COMERCIO-HEREDADO". | VENTA-COMERCIO |
compras_items.[0].ciudad | La ciudad del comprador, si no tiene, enviar el valor 1. | 1 |
compras_items.[0].nombre | Nombre del producto o servicio que se está comprando. Obligatorio. | Ticket virtual a evento Ejemplo 2017 |
compras_items.[0].cantidad | Cantidad del producto que se está comprando, solo con fines informativos. | 1 |
compras_items.[0].categoria | Si no está utilizando los servicios de couriers ofrecidos por pagopar (Sólo para productos físicos), debe enviar de todas formas el campo con el valor 909. De lo contrario utilizar la documentación de integración de couriers para obtener el ID de la categoría | 909 |
compras_items.[0].public_key | Clave publica del vendedor, si no es una transacción split billing, será el mismo valor que el campo public_key. | 98b97ce494801bf26575a5c4ff2d4f14 |
compras_items.[0].url_imagen | URL de la imagen del producto. Si no tiene imagen, enviar el campo con el valor vacío. | |
compras_items.[0].descripcion | Descripción del producto que se está comprando. | Ticket virtual a evento Ejemplo 2017 |
compras_items.[0].id_producto | Identificador del producto/servicio que se está comprando. | 895 |
compras_items.[0].precio_total | Precio total del producto/servicio que se está comprando (No es el precio unitario, sino el precio total agrupado por producto) | 100000 |
compras_items.[0].vendedor_telefono | Vendedor del comprador. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion | Dirección del comprador. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion_referencia | Referencia de la dirección del comprador. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion_coordenadas | Coordenadas de la dirección del comprador. Si no tiene, debe enviarse el valor vacío. | |
fecha_maxima_pago | Es la fecha máxima que tiene el comprador para pagar el pedido, una vez que llegue a la fecha establecida, el pedido automáticamente se cancela y ya no puede pagarse. | 2018-01-04 14:14:48 |
id_pedido_comercio | ID del pedido/transacción del comercio. Debe ser único tanto en entorno de Desarrollo y Producción. Alfanumérico. | 1134 |
descripcion_resumen | Descripción breve del pedido, puede coincidir con el valor de compras_items.[0].nombre o enviar con el valor vacío. | Ticket virtual a evento Ejemplo 2017 |
Datos de ejemplo que Pagopar retornaría en caso de éxito (retorna el hash de pedido):
{
"respuesta": true,
"resultado": [
{
"data": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd"
}
]
}
A tener en cuenta, el valor de resultado.data es el identificador del pedido.
Datos de ejemplo que Pagopar retornaría en caso de error:
{ "respuesta": false,"resultado": "Token no coincide."}
Puede ver el detalle de los distintos tipos de errores que pudiera retornar la ejecución del endpoint iniciar-transacción.
Paso #2: El comercio redirecciona a la página de Checkout de Pagopar
Descripción
El comercio redirecciona a la página de Checkout de Pagopar, con el dato obtenido en el paso anterior. Antes de redireccionar, se debe asociar el identificador de pedido del comercio con el hash del Pedido de Pagopar.
Ejemplo en PHP:
<?php header('Location: https://www.pagopar.com/pagos/ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd'); exit(); ?>
Página de Checkout de Pagopar:
¿Tenés permiso de redireccionamiento automático?
Esta caracteristica sólo la tienen algunos comercios previa solicitud y aprobación. Esto sirve para “saltar” la pantalla de Pagopar implementando los medios de pagos en el sitio del comercio, de tal forma, que el cliente final selecciona el medio de pago en el sitio de comercio, le da “finalizar compra” y no verá la pantalla de Pagopar, simplemente verá la página del vPos para abonar con tarjeta de crédito (en caso que haya seleccionado tarjeta de crédito), y en caso de que haya seleccionado alguna boca de cobranza verá la pantalla de redireccionamiento del sitio del comercio, no así la de pagopar.
Para indicar qué medio de pago seleccionó la persona, simplemente hay que agregar el parámetro al momento de redireccionar a la plataforma de Pagopar
https://www.pagopar.com/pagos/$hash?forma_pago=' + idFormaPago;
Lista de formas de pago
11 | Transferencia Bancaria | |
18 | Zimple | |
20 | Wally | |
22 | Wepa | |
23 | Giros Claro | |
24 | Pago QR |
Lista de formas de pago vía WS
Token para este endpoint se genera:
sha1(Private_key + “FORMA-PAGO”) En PHP: sha1($datos['comercio_token_privado'] . “FORMA-PAGO”)
Método: POST
Datos de ejemplo que el comercio enviará a Pagopar:
Contenido:
{
"token": "cebe636c26b55ec95309260941f5a2c00be9b0b6",
"token_publico": "98b97ce494801bf26575a5c4ff2d4f14"
}
Datos de ejemplo que Pagopar retornará para la petición anterior:
Contenido:
{
"respuesta": true,
"resultado": [
{
"forma_pago": "9",
"titulo": "Bancard - Tarjetas de crédito",
"descripcion": "Acepta Visa, Mastercard, American Express, Discover, Diners Club y Credifielco.",
"monto_minimo": "1000"
},
{
"forma_pago": "1",
"titulo": "Procard - Tarjetas de crédito",
"descripcion": "Acepta Visa, Mastercard, Credicard y Unica. (Acepta pagos internacionales)",
"monto_minimo": "1000"
},
{
"forma_pago": "2",
"titulo": "Aqui Pago",
"descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
"monto_minimo": "55000"
},
{
"forma_pago": "3",
"titulo": "Pago Express",
"descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
"monto_minimo": "80000"
},
{
"forma_pago": "4",
"titulo": "Practipago",
"descripcion": "Acercándose a las bocas de pagos habilitadas luego de confirmar el pedido",
"monto_minimo": "50000"
},
{
"forma_pago": "7",
"titulo": "Cuenta Bancaria",
"descripcion": "Home Banking",
"monto_minimo": "50000"
},
{
"forma_pago": "10",
"titulo": "Tigo Money",
"descripcion": "Utilice sus fondos de Tigo Money",
"monto_minimo": "1000"
}
]
}
Paso #3: Pagopar notifica al comercio sobre el pago
Descripción
Pagopar realiza una petición a la URL de respuesta especificada en la opción “Integrar con mi sitio web” de Pagopar.com. En este endpoint, el comercio debe poner como “pagado” un pedido específico en su sistema, por tanto, este punto es crítico, ya que si alguna persona supiera la URL de Respuesta, conociendo el API y el funcionamiento del mismo, podría poner como pagado en el sistema del comercio ciertos pedidos arbitrariamente. Para evitar esto, es extrictamente necesario hacer una validación del token antes de actualizar el estado del pedido a Pagado. Con esto se evita lo anteriormente mencionado, ya que para generar el token se utiliza la clave privada que nunca debe ser compartida ni expuesta.
El comercio debe retornar Código 200, en caso de que el comercio no retorne dicho código de estado, ya sea por un problema de conectividad, servidor caído o similar, Pagopar volverá a avisar sobre el pago cada 10 minutos hasta obtener la respuesta correcta.
Observación
El valor de public key y private key se obtiene desde la opción “Integrar con mi sitio web” de Pagopar.com
El Token en este punto se genera de la siguiente forma: sha1(private_key + hash_pedido)
Método: POST
Datos de ejemplo que Pagopar enviaría al Comercio en caso de pedido pagado:
Contenido:
{
"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
}Datos de ejemplo que el Comercio debe responder a Pagopar en caso de pedido pagado:
Contenido:
[
{
"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"
}
]Datos de ejemplo que Pagopar enviaría al Comercio en caso de reversión:
Contenido:
{
"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
}
Datos de ejemplo que el Comercio debe responder a Pagopar en caso de pedido reversado:
Contenido:
[
{
"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"
}
]
Datos de ejemplo que Pagopar enviaría al Comercio en caso de pedido confirmado (pendiente de pago) para reversión:
Contenido:
{
"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
}
A nivel de código: Recomendamos que el comercio retorne directamente el contenido del resultado del JSON enviado por Pagopar, de este modo se evita armar el JSON manualmente optimizando el código y el funcionamiento (se evitará hacer ajustes adicionales al armado del JSON en caso de que hayan actualizaciones en la estructura del JSON enviado por Pagopar).
Obs.: Estas notificaciones de pago son realizadas únicamente cuando se hace el pago del pedido y se hacen conforme al estado de la transacción (pagado/reversado).
Ejemplo de la validación del Token en Woocommerce/PHP:
Contenido:
<?php $rawInput = file_get_contents('php://input');
$json_pagopar = json_decode($rawInput, true);
global $wpdb;
#Obtenemos el ID de Pedido
$order_db = $wpdb->get_results($wpdb->prepare( "SELECT id FROM wp_transactions_pagopar WHERE hash = %s ORDER BY id DESC LIMIT 1", $json_pagopar['resultado'][0]['hash_pedido']));
#Obtenemos key privado
$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();
# Si coinciden los token, esta validación es extrictamente obligatoria para evitar el uso malisioso de este endpoint
if (sha1($payments['pagopar']->settings['private_key'] . $json_pagopar['resultado'][0]['hash_pedido']) === $json_pagopar['resultado'][0]['token']) {
# Marcamos como pagado en caso de que ya se haya pagado
if (isset($order_db[0]->id)) {
if ($json_pagopar['resultado'][0]['pagado'] === true) {
$order_id = $order_db[0]->id;
global $woocommerce;
$customer_order = new WC_Order((int) $order_id);
// Marcamos el pedido como Pagado
$customer_order->payment_complete();
$customer_order->update_status('completed', 'Pedido Completado/Pagado.');
} elseif ($json_pagopar['resultado'][0]['pagado'] === false) {
// Marcamos el pedido como Pendiente
}
}
} else {
echo 'Token no coincide';
return '';
}
echo json_encode($json_pagopar['resultado']);
?>
Es sumamente importante hacer el control de que el token que envía pagopar es igual al token que genera el comercio, para evitar que personas que puedan conocer su URL de respuesta pueda hacer peticiones e impactar en el estado de sus pedidos, ejemplo, marcando como Pagado.
Paso #4: Pagopar redirecciona a la página del resultado de pago del Comercio
Descripción
Pagopar redirecciona a la página de resultado especificada en la opción “Integrar con mi sitio web” de Pagopar.com, con el hash de pedido. En ese momento, el Comercio realiza una petición a Pagopar para saber el estado de dicho pedido en tiempo real del pedido, y de acuerdo a eso le muestra el mensaje de Pagado/Error al pagar/Pendiente de Pago.
Observación
El valor de public key y private key se obtiene desde la opción “Integrar con mi sitio web” de Pagopar.com
El Token en este punto se genera de la siguiente forma: Sha1(Private_key + "CONSULTA")
URL de ejemplo a la que Pagopar redireccionará: https:// www.misitio.com/pagopar/resultado/
Método: GET
URL a la que el Comercio hará la petición: https://api.pagopar.com/api/pedidos/1.1/traer
Método: POST
Datos de ejemplo que el comercio enviará a Pagopar:
Contenido
{
"hash_pedido": "b1d98a906be9d0dc6956ead8642e0d6393abe9a6fd2743663109aa90e4d73e59",
"token": "cebe636c26b55ec95309260941f5a2c00be9b0b6",
"token_publico": "98b97ce494801bf26575a5c4ff2d4f14"
}Datos de ejemplo que Pagopar retornará para la petición anterior:
Contenido:
{
"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>" } } ] }
Posterior a finalizar los pasos de esta documentación solo faltaría hacer el pase a producción .
Related Articles
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 ...Pagos Recurrentes vía Bancard/Pagopar
Pagos recurrentes con Tarjeta de credito/débito vía Bancard en Pagopar Primeros pasos Descripción La funcionalidad de pagos recurrentes vía Bancard a traves de Pagopar permite realizar un pago en cualquier momento, de una tarjeta de crédito/débito ...Integración de Servicios de pickup/delivery
Pasos para Agregar soporte de servicio de pickup/delivery Flujo normal de Paso #1: Obtener lista de ciudades Paso #2: Obtener lista de categorías Pagopar (opcional) Paso #3: Calcular flete / costo de envío Paso #4: Seleccionar método de envio Paso ...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 ...Sincronización de productos
Introducción En ciertos casos un comercio puede tener un sitio web con sus respectivos productos, y querrá que se sincronicen con los links de pago de Pagopar, de tal forma de evitar la doble carga de productos y sobre todo la doble administración de ...