API - Integración de medios de pagos

API - Integración de medios de pagos

Flujo normal de compra

  1. Paso #1: El comercio crea un pedido en Pagopar
  2. Paso #2: El comercio redirecciona a la página de Checkout de Pagopar
  3. Paso #3: Pagopar notifica al comercio sobre el pago
  4. 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.fernandogoetz.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
tokenSe genera de la siguiente forma: sha1($datos['comercio_token_privado'] . $idPedido . strval(floatval($j['monto_total'])));fbe4586135e7f482d6c8ad624413139b9c90825f
comprador.rucRuc del comprador. El campo debe estar presente, si no tiene ruc, debe ir con el valor vacío ("")4247903-7
comprador.emailE-mail del comprador. Campo obligatorio.fernandogoetz@gmail.com
comprador.ciudadSi 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.nombreNombre del comprador. Campo obligatorio.
Rudolph Goetz
comprador.telefonoNúmero de teléfono en formato internacional.+595972200046
comprador.direccionDirección del comprador. El campo debe estar presente, si no tiene dirección, enviar el valor vacío ("").
comprador.documentoNúmero de cédula. Campo obligatorio.4247903
comprador.coordenadasCoordenadas 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:



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


Lista de formas de pago

Identificador

Forma de Pago

URL Imagen

9

Bancard - Tarjetas de crédito/débito
(Acepta Visa, Mastercard, American Express, Discover, Diners Club y Credifielco.)

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

1

Procard - Tarjetas de crédito/débito

(Acepta Visa, Mastercard, Credicard y 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

7

Cuenta Bancaria


10

Tigo Money

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

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


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 a el Comercio en caso de pedido confirmado (pendiente de pago):
Contenido:
{
    "resultado": [
        {
            "pagado": false,
            "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
}


Datos de ejemplo que Pagopar enviaría a el Comercio en caso de pedido pagado:
Contenido:
{
    "resultado": [
        {
            "pagado": true,
            "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 Pagopar enviaría a el Comercio en caso de reversión:
Contenido:
{
    "resultado": [
        {
            "pagado": false,
            "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 pagado:
Contenido:
[
    {
        "pagado": true,
        "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 el Comercio debe responder a Pagopar en caso de pedido reversado:
Contenido:
[
    {
        "pagado": false,
        "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"
    }
]



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"
        }
    ]
}



Pagina de redireccionamientoPagina de redireccionamiento
























    • Related Articles

    • Pagos Recurrentes vía Bancard/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 previamente catastrada/guardada por el usuario. El usuario ...
    • Integración de Servicios de pickup/delivery

      Pasos para Agregar soporte de servicio de pickup/delivery Flujo normal de compra Paso #1: Obtener lista de ciudades Paso #2: Calcular flete Paso #3: Seleccionar método de envio y crea el pedido Paso #1: Obtener lista de ciudades Descripción El ...
    • 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 ...
    • Entornos y pase a Producción

      Entornos de desarrollo y producción En Pagopar existen dos entornos, por defecto, cuando uno empieza la integración se están utilizando las claves públicas y privadas de desarrollo/staging, una vez terminado la integración, debe pasar a producción y ...
    • Listado de errores al iniciar transacción

      Este es un listado de algunos de los errores que se pudieran presentar al realizar la petición iniciar-transacción Descripción del error Explicación Token no coincide El token debe ser generado según en el endpoint, en el caso del endpoint ...