API Checkout

Integración pagos spot con múltiples medios de pago

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

Introducción

Integra a tu sitio Web o aplicación móvil el Checkout de VirtualPOS y accede de forma automática a múltiples medios de pagos para maximizar las ventas de tu negocio.

Inicia una tracción de pago y recibe notificaciones vía Webhook, conoce al instante las comisiones y fecha de liquidación de cada pago.


La siguiente documentación especifica la API REST para integración de comercios con VirtualPOS. Las operaciones permitirán realizar transacciones financieras de pago con todos los medios de pago disponibles.

Requisitos preliminares para integrarse:

  1. El comercio debe tener una cuenta activa con VirtualPOS.

  2. Contar con una secret_key activa y válida para utilizar la API.

  3. Contar con una plataforma de software que implemente el estándar JWT (RFC 7519)

Consultas técnicas asociada la integración deben ser enviadas al correo soporte@virtualpos.cl


Breve explicación del modelo de integración

El comercio para iniciar una transacción deberá realizar los siguientes pasos:

  1. Iniciar una transacción VirtualPOS. El inicio de la transacción se realiza a través del método de la API /payment/request esta operación creará una orden de recaudación en estado “pendiente” en VirtualPOS con toda la información necesaria para gestionar su autorización a través de los medios de pago disponibles (WebpayPlus, Onepay, Khipu, MACH, Chek, Redpay, etc.). Importante, transcurridos 30 días seguidos en estado “pendiente” la orden de recaudación pasará a estado “expirada”, impidiendo su pago.

  2. Redireccionamiento. El redireccionamiento permite al usuario pagador visualizar los medios de pago en su navegador Web a través del checkout. Se mostrarán únicamente los medios de pago contratados por el comercio. El usuario pagador debe ser redirigido a la URL “url_redirect” entregada como resultado del método API /payment/request.

    De forma alternativa, para medios de pago que soporten QR (Onepay, MACH, Chek, etc.), es posible desplegar directamente el código QR en la solución de software del comercio, ejemplo sistema de caja, aplicación móvil, voucher impreso, etc. de tal forma que el usuario pagador escanee y acepte directamente el pago en su App, mejorando así la experiencia de compra.

  3. Recepcionar y validar resultado de transacción. Para pagos direccionados al checkout de virtualPOS, una vez resuelta la autorización financiera del pago se redireccionará a la página de solución del comercio, enviado el parámetro “uuid” a través del verbo HTTP/POST. Al momento de recepcionar el “uuid” se deberá ejecutar la operación /payment/getstatus para conocer el estado y resultado de la transacción. El estado “pendiente”, indica que aún no se ha obtenido autorización financiera. El estado "pagado" indica que el pago ya se encuentra autorizado y el comercio podrá entregar el producto o servicio a su cliente.

  4. Webhook de notificación. Con el objetivo de garantizar que el comercio reciba la respuesta por parte de VirtualPOS, es posible incorporar en el inicio de la transacción la URL de un Webhook (parámetro callback_url) que deberá implementar el comercio para recibir la notificación asíncrona. Si el cliente pagador pierde conexión o cierra su navegador web, el resultado de la transacción podrá ser recuperado a través de la notificación enviada al webhook. Esta notificación siempre se enviará independientemente de si el flujo de páginas en el navegador del cliente termina de forma exitosa o no. La notificación se realiza a través de una llamada POST al callback_url con el parámetro uuid de la transacción, posterior a eso el comercio deberá consultar el estado de la transacción invocando el método getstatus, y si es necesario, actualizar el estado del pago en sus sistemas.

Otras consideraciones importantes:

  • Para pagos directos con QR, es necesario una vez desplegado el QR consultar de forma periódica el estado de la transacción. Se recomienda consultar cada 5 segundos por un periodo total de 1 minuto.

  • Es requisito almacenar por al menos 1 año la información del pago autorizado entregada en la consulta del estado (uuid de la transacción, fecha de autorización, monto, código de autorización, cantidad de cuotas, monto de cada cuota).

  • Dependiendo del resultado de la transacción, el comercio debe desplegar un mensaje al usuario pagador de éxito o fracaso. En caso de fracaso se debe permitir reintentar el pago a través del mismo “uuid” de transacción.

Firma de operaciones de la API

Para integrarse con VirtualPOS es necesario firmar el mensaje con la secret_key asociada a la cuenta VirtualPOS, con el fin de garantizar que ninguno de los valores enviados sean alterados en el tránsito del mensaje.

En el siguiente recuadro se ejemplifica, en lenguaje PHP, el código necesario para la firma del mensaje utilizando la secret key de su cuenta VirtualPOS y la invocación de la API.

En este ejemplo, asociado al método getstatus requiere únicamente el parámetro uuid.

Una vez generada la firma, esta debe ser incluida en el listado de parámetros del objeto JSON como un parámetro adicional con nombre signature.

En el header es necesario incluir el parámetro “Authorization” con valor de la api key del Comercio.

$token_payload = array(); 
$token_payload['uuid'] = $uuid;
$jwt = JWT::encode($token_payload, $secret_key);

$client = new Client([ 'headers' => [ 'Content-Type' => 'application/json' , 'Authorization'=>$api_key ] ]);

$response = $client->post( $endpoint , [ 'json' => [ 'uuid' => $uuid, 'signature' => $jwt ] ]);

$response_decode = json_decode($response->getBody()->getContents());

Operaciones disponibles

/payment/request

Permite iniciar una transacción de pago spot en VirtualPOS

Método: POST

Request BODY:

{
"amount": 9990,
"email": "user@example.com",
"social_id": "12345678-9",
"first_name": "John",
"last_name": "Doe",
"phone": "56987654321",
"description": "OC-1234 : Apple Watch 3G 2021",
"return_url": "Base64('http://www.miecommerce.com/return')",
"callback_url": "Base64('http://www.miecommerce.com/callback')",
"merchant_internal_code": "id_1234",
"merchant_internal_channel": "portal_pagos",
"payment_method": "webpay",
"signature": "jwt_encode()"
}

Descripción de parámetros:

amount*

integer

ejemplo: 9990

Monto de venta en pesos chilenos CLP

email*

string

Correo electrónico del cliente

social_id*

string

ejemplo: 12345678-9

Correo electrónico del cliente

first_name*

string

ejemplo: John

Nombre del cliente

last_name*

string

ejemplo: Doe

Apellido del cliente

phone

string

ejemplo_ 56988776655

Teléfono del cliente

description*

string

ejemplo: OC-1234: Apple Watch 3G

Breve descripción del producto o servicio a pagar

return_url*

string

ejemplo: Base64('http://www.micom.com/return')
URL a la cual se retornará una vez que se haya finalizado el proceso de pago en VirtualPOS, La URL debe ser codificada en Base64

callback_url*

string

ejemplo: Base64('http://www.micom.com/callback') URL a la cual se realizará un callback Asíncrono una vez que se haya finalizado el proceso de pago en VirtualPOS. La URL debe ser codificada en Base64

merchant_internal_code

string

ejemplo: id_1234
Identificador del comercio, útil para efectuar la trazabilidad de la transacción, por ejemplo el número de factura, pedido, boleta, etc.

merchant_internal_channel

string

ejemplo: portal_pagos
Identificador del canal que utiliza el comercio para iniciar la transacción en VirtualPOS

payment_method

string

ejemplo: webpay

Identificador del medio de pago con el cual se realizará la transacción, de no incluir este parámetro, la transacción se iniciara con el checkout por defecto que incluye todos los medios de pagos disponibles.

Posibles valores:

  • webpay

  • khipu

  • onepay

  • chek

  • mach

  • redpay

signature*

string

ejemplo: jwt_encode()
Firma de la transacción

* Obligatorios

Respuesta 200, transacción iniciada correctamente. Ejemplo:

{
"status": "OK",
"code": 200,
"client": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"social_id": "12345678-9",
"phone": "56961934502"
},
"commerce": {
"commerce_id": "76123456-7",
"name": "Comercial Andes"
},
"order": {
"uuid": "57276136aad3ecad",
"status": "pagado",
"created_at": "2022-07-22T01:48:52.780Z"
},
"url_redirect": "https://pay.virtualpos-sandbox.com/preview/083613a748190d26"
}

Respuesta 401, transacción con error

{
"status": "ERROR",
"code": 401,
"message": "Ocurrió un problema al iniciar la transacción."
}


/payment/getstatus

Permite consultar el estado y detalles de una transacción de pago spot en VirtualPOS

Método: POST

Request BODY:

{
"uuid": "083613a748190d26",
"signature": "jwt_encode()"
}

Descripción de parámetros:

uuid

string

ejemplo: 083613a748190d26

Identificador único de la transacción VirtualPOS.

signature*

string

ejemplo: jwt_encode()
Firma de la transacción

Respuesta 200, operación exitosa. Ejemplo:

{
"status": "OK",
"code": 200,
"client": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"social_id": "12345678-9",
"phone": "56961934502"
},
"commerce": {
"commerce_id": "76123456-7",
"name": "Comercial Andes"
},
"order": {
"uuid": "083613a748190d26",
"status": "pagado",
"created_at": "2021-09-08 11:20:31",
"card_number": 1234,
"authorized_at": "2021-09-08 11:21:31",
"auth_code": "1234",
"installment_amount": 0,
"installment_number": 0,
"payment_type_code": "VN",
"amount": 9990,
"merchant_internal_code": "OC-1234",
"merchant_internal_channel": "portal_pagos",
"deposits": [
{
"description": "1/1",
"installment": 9900,
"processing_flat_fee": 0,
"processing_fee": 117,
"payout_amount": 9783,
"payout_date": "2021-09-21"
}
]
}
}

Respuesta 401, error al recuperar información de la transacción.

{
"status": "ERROR",
"code": 401,
"message": "Ocurrió un problema al recuperar la información de la transacción."
}

¿Ha quedado contestada tu pregunta?