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
Para facilidad de integración, contamos con un proyecto en POSTMAN con los endpoints utilizados en esta documentación.
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": "[email protected]",
"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": "",
"forma_pago": 9
}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. | [email protected] |
| 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. En caso que la forma de pago sea PIX se debe enviar el CPF o CPNJ | 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" inclusive si la forma de pago sea PIX. | 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 | Telefono del vendedor. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion | Dirección del vendedor. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion_referencia | Referencia de la dirección del vendedor. Si no tiene, debe enviarse el valor vacío. | |
compras_items.[0].vendedor_direccion_coordenadas | Coordenadas de la dirección del vendedor. 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 |
forma_pago | 9 | Forma de pago en la que se pagará el pedido creado |
Datos de ejemplo que Pagopar retornaría en caso de éxito (retorna el hash de pedido):
{ "respuesta": true, "resultado": [ { "data": "ad57c9c94f745fdd9bc9093bb409297607264af1a904e6300e71c24f15d618fd","pedido": "1750"} ] }
El campo 'data' es el que utilizará en su base de datos para relacionar los datos de cada pedido, este campo es obligatorio almacenarlo. En cambio el campo 'pedido' tiene un uso meramente informativo
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.
Para cobrar con divisa en dólares: En lugar de utilizar el endpoint iniciar-transaccion, debes utilizar el endpoint iniciar-transaccion-divisa para iniciar una transacción en dólares estadounidenses.
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 | |
25 | PIX |
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": "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"
}
]
}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. Esta notificación puede demorar hasta 2 minutos en realizarse, para ver el estado real del pedido debe consultar al endpoint especificado en el Paso #4.
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
Catastro de tarjetas - Pagos recurrentes - Preautorización
Catastro de tarjetas para pagos recurrentes o sin acción del usuario Primeros pasos Descripción La funcionalidad de pagos recurrentes a través de Pagopar permite realizar un pago en cualquier momento, de una tarjeta de crédito/débito previamente ...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 ...(Versión Inglés) API - Steps to integrate Pagopar to my website
Normal flow of purchase Step # 1: The shop creates an order in Pagopar. Step # 2: The shop redirects to the Pagopar checkout page. Step # 3: Pagopar notifies the shop of the payment. Step # 4: Pagopar redirects to the shop´s payment result page. Step ...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 ...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 ...