DESCRIPCIÓN
PagoFacil proporciona una API tipo REST para integrar pagos en efectivo en diversas aplicaciones. Una vez generada la orden de compra, le llegará un correo electrónico al cliente con el cual podrá asistir a la tienda de conveniencia seleccionada para realizar el pago.
MÉTODOS DE INTEGRACIÓN
- Realizar una orden de pago.
- Consultar la información de una orden de pago.
- Consultar varias órdenes de compra en a un periodo de tiempo.
- Webhooks.
URL
Base de la URL que va a consumir todos los servicios web.
Stage/Pruebas - https://sandbox.pagofacil.tech
Producción - https://api.pagofacil.tech
1. Realizar una orden de pago.
Esta API te permite generar una orden de pago en efectivo para que el cliente proceda a realizar el pago en las tiendas de conveniencia.
| Método | URL |
|---|---|
| POST | /cash/charge |
Campos de la petición:
| Campo | Tipo | Longitud | Descripción | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Nota 1: Debe ser único e irrepetible para cada orden. Nota 2: Lista de código de tiendas disponibles:
|
|||||||||||||||||||
| branch_key | String | 100 | Api key de la sucursal | ||||||||||||||||
| user_key | String | 100 | Api key usuario | ||||||||||||||||
| order_id | String | 45 | Dato único para identificación de la orden de compra 1 | ||||||||||||||||
| product | String | 100 | Descripción o nombre del producto | ||||||||||||||||
| amount | Decimal | (8,2) | Monto a pagar. | ||||||||||||||||
| store_code | String | 30 | Código de la tienda de conveniencia. 2 | ||||||||||||||||
| customer | String | 100 | Nombre del comprador | ||||||||||||||||
| String | 100 | Correo electrónico del comprador | |||||||||||||||||
| expiration | Datetime | – | Fecha limite de pago de la orden (fecha de expiración). | ||||||||||||||||
Ejemplo de la petición API:
{
"branch_key":"e147ee31531d815e2308d",
"user_key":"f541b3f11f0f9b3fb3349",
"order_id":"75464",
"product":"Playera",
"amount":"1.0",
"store_code":"SANTANDER",
"customer":"11",
"email":"[email protected]"
}Campos de la respuesta:
| Campo | Descripción |
|---|---|
| error | Este parámetro regresa dos tipos de valores. En caso de realizar una petición exitosa, regresará un entero con valor “0”; de manera contraria devuelve un entero con valor “1” |
| message | Cuando la petición se completó de manera correcta, devuelve una cadena de caracteres con la leyenda “success”, de otra forma devuelve una cadena de caracteres especificando qué tipo de error está surgiendo |
| charge | Este último parámetro tiene la característica de OMITIRSE cuando la petición ha sido incorrecta. En caso de resultar satisfactoria, devuelve un arreglo de datos con los siguientes valores: |
| charge: reference | Referencia de la orden de compra generada por PagoFacil. |
| charge: cutomer_order | Número de orden de cliente generada por PagoFacil. |
| charge: amount | Cantidad monetaria por la que se debe procesar dicha transacción. |
| charge: convenience_store | Nombre de la tienda de conveniencia donde se debe realizar la transacción. |
| charge: store_fixed_rate | Calificación de la tienda de conveniencia dónde se debe realizar la transacción. |
| charge: store_schedule | Horario de la tienda de conveniencia dónde se debe realizar la transacción. |
| charge: store_image | Ruta del logo/imagen de tienda de conveniencia dónde se debe realizar la transacción. |
| charge: bank_account_number | Número de cuenta bancaria dónde se requiere el pago. |
| charge: bank | Banco dónde se requiere realizar el pago. |
| charge: created_at | Fecha y hora de creación de la orden de pago. |
| charge: expiration_date | Fecha y hora de vigencia de la orden de pago. |
| charge: status | Se refiere al estado de la transacción de la orden de pago. |
| charge: reference_number | Es el dato que se genera una vez que ha sido pagada la orden de pago. |
| charge: agreement_number | Este valor se refiere al número de convenio relacionado al banco en donde se esta realizando la transacción.
Es importante presentar este dato en los establecimientos Seven Eleven y Extra para que el cliente realice su pago. |
Ejemplo de la respuesta JSON:
{
"error" : "0",
"message" : "success",
"charge" : {
"reference" : "S-PFCPE2692S2720I3926",
"customer_order": "43",
"amount": "550",
"convenience_store": "SANTANDER",
"store_fixed_rate": "9.00",
"store_schedule": "8:00 - 20:00",
"store_image": "santander.png",
"bank_account_number": "xx-xxxxxxxx-x",
"bank": "Banco de pruebas",
"created_at": "",
"expiration_date": "2018-09-22 12:9:00",
"status": "pending",
"reference_number": "",
"agreement_number": ""
}
}
A continuación, un ejemplo de la notificación que se debe mostrar al cliente final como una Orden De Pago:
2. Consultar la información de una orden de pago.
Permite consultar la información de una orden de pago generada anteriormente.
| Método | URL |
|---|---|
| GET | /cash/charge |
Campos de la petición:
| Campo | Tipo | Longitud | Descripción |
|---|---|---|---|
| branch_key | String | 100 | Api key sucursal. |
| user_key | String | 100 | Api key usuario. |
| reference | String | 45 | Identificador enviado por PagoFacil al realizar una orden de pago. |
Ejemplo de la petición API:
https://sandbox.pagofacil.tech/cash/charge?branch_key=e147ee31531d815e2308d6d6d39929ab599deb98&user_key=f541b3f11f0f9b3fb33499684f22f6d711f2af58&reference=S-PFCPE2692S2720I3612Campos de la respuesta:
| Campo | Descripción |
|---|---|
| error | Al realizar una petición a esta api, puede devolver dos valores: en caso de ser exitosa, devolverá un “0” como entero. De manera contraria, devolverá un entero con valor “1”. |
| message | Al igual que el punto anterior, retorna dos valores. Regresa “vacío” cuando ha sido correcta la transacción. De otra forma, regresa una cadena de caracteres con información del error. |
| charge | Este parámetro se OMITE cuando surge algún error pero cuando ha sido satisfactoria la petición, devolverá un parámetro del tipo array con los siguientes datos: |
| charge: reference | Referencia de la orden de compra generada por PagoFacil. |
| charge: customer_order | Número de orden de cliente generada por PagoFacil. |
| charge: email | Correo electrónico del comprador. |
| charge: amount | Cifra monetaria de la transacción. |
| charge: convenience_store | Nombre de la tienda de conveniencia dónde se debe realizar la transacción. |
| charge: store_fixed_rate | Calificación de la tienda de conveniencia dónde se debe realizar la transacción. |
| charge: store_schedule | Horario de atención dónde se debe realizar la transacción. |
| charge: store_image | Link de la imagen de la tienda de conveniencia dónde se debe realizar la transacción. |
| charge: bank_account_number | Número de cuenta bancaria donde se requiere el pago. |
| charge: bank | Banco dónde se requiere realizar el pago. |
| charge: created_at | Fecha y hora de creación de la orden de pago. |
| charge: expiration_date | Fecha y hora de vigencia de la orden de pago. |
| charge: status | Se refiere al estado de la transacción de la orden de pago.
(2: pendiente, 4: pagado, 5: pagado manual) |
| charge: fee | Porcentaje de la comisión cobrada. |
| charge: fee_amount | Monto de la comisión cobrada sin IVA. |
| charge: tax_amount | Cifra monetaria del valor de los impuestos de la transacción. |
| charge: fixed_rate | Monto de ajuste. |
| charge: total_fee_amount | Monto total de la transacción. |
Ejemplo de respuesta JSON:
{
"error": "0",
"message": "",
"charge": {
"reference": "S-PFCPE2692S2720I3926",
"customer_order": "43",
"email": "[email protected]",
"amount": "550.00",
"convenience_store": "SANTANDER",
"store_fixed_rate": "9.00",
"store_schedule": "8:00 - 20:00",
"store_image": "santander.png",
"bank_account_number": "xx-xxxxxxxx-x",
"bank": "BANCO DE PRUEBAS",
"created_at": "2018-09-17 17:25:49",
"expiration_date": "2018-09-22 12:09:00",
"status": "2",
"fee": "0.00",
"fee_amount": "0.00",
"tax_amount": "0.00",
"fixed_rate": "3.00",
"total_fee_amount": "0.00"
}
}
3. Consultar varias ordenes de compra en a un periodo de tiempo.
Permite obtener la información de varias órdenes de compra consultando por un periodo de fechas.
| Método | URL |
|---|---|
| GET | /cash/charges |
Campos de la petición:
| Campo | Tipo | Longitud | Descripción |
|---|---|---|---|
| Nota1: debe solicitarla a [email protected] | |||
| branch_key | String | 100 | Api key sucursal. |
| user_key | String | 100 | Api key usuario. |
| secret_key | String | 64 | Clave privada.1 |
| date_start | String | 19 | Fecha inicial del reporte, formato AAAA-MM-DD HH:MM:SS |
| date_end | String | 19 | Fecha final del reporte, formato AAAA-MM-DD HH:MM:SS |
Ejemplo de la petición API:
https://sandbox.pagofacil.tech/cash/charges?branch_key=e147ee31531d815e2308d&user_key=f541b3f11f0f9b3fb334996&secret_key=c68bd305206c6487a307d&date_start=2018-06-12 00:00:00&date_end=2018-06-12 23:00:00Campos de la respuesta:
| Campo | Descripción |
|---|---|
| error | La respuesta de este parámetro es de dos tipos. Cuando la petición es exitosa, regresará un entero con valor “0”; de lo contrario devuelve un entero con valor “1” |
| message | Al realizar una petición de manera correcta, devuelve una cadena de caracteres con el mensaje “success”, de otra forma devuelve una cadena de caracteres especificando “invalid request”. |
| charges | Este último parámetro tiene la característica de OMITIRSE cuando la petición ha sido incorrecta. En caso de resultar satisfactoria, devuelve un arreglo de arreglos de datos con los siguientes valores cada arreglo: |
| charges: cash_charge_id | Identificador del cargo por la transacción generada. |
| charges: company_id | Identificador de la compañía dónde se generó la transacción. |
| charges: branch_id | Identificador de la sucursal dónde se expidió la orden de compra. |
| charges: user_id | Identificador del usuario del sistema quien generó la transacción. |
| charges: reference | Cadena de identificación generada por PagoFácil. |
| charges: customer_reference | Identificador del cliente que realiza la transacción. |
| charges: cash_processor_reference | Referencia de la tienda de conveniencia del pago. |
| charges: cash_processor_reference_short | Referencia clave de la tienda de conveniencia. |
| charges: amount | Monto del valor de la transacción. |
| charges: status | Es el estado en el que se encuentra la orden de pago. |
| charges: status_desc | Palabra clave del estado en el que se encuentra la orden de pago. |
| charges: expiration | Fecha de caducidad de la orden de pago. |
| charges: created | Fecha de creación de la orden de pago. |
| charges: status_at | Fecha con que se actualizó por última vez el estatus de la orden de pago. |
| charges: paid_at | Después de haber sido pagada la orden de pago, este valor indica dónde fue realizado el pago. |
| charges: convenience_store_id | Identificador de la tienda de conveniencia dónde se debe realizar la transacción. |
| charges: bank_account_number | Número de cuenta bancaria dónde se debe pagar la transacción. |
| charges: bank_id | Identificador del banco al que pertenece la cuenta bancaria dónde se debe pagar la transacción. |
| charges: paid | Indica si la orden de pago ya ha sido pagada o no. |
| charges: brand_name | Marca comercial con la que se relaciona la orden de pago. |
| charges: convenience_store | Nombre completo de la tienda de conveniencia dónde se debe pagar la transacción. |
| charges: convenience_store_code | Código de identificación de la tienda de conveniencia antes mencionada. |
| charges: buyer_name | Nombre del comprador. |
| charges: buyer_email | correo electrónico del comprador. |
| charges: product_name | Nombre del producto por el que se debe pagar la transacción. |
| charges: bank_name | Nombre del banco dónde se debe pagar la transacción. |
| charges: fee_percentage | Porcentaje de la comisión cobrada. |
| charges: fee_percentage_amount | Monto de la comisión cobrada. |
| charges: tax_percentage | Porcentaje de impuestos que se retienen por la transacción. |
| charges: tax_amount | Monto de los impuestos que se retienen por la transacción. |
| charges: fixed_rate | Comisión cobrada por transacción. |
| charges: total_fee_amount | Total de la comisión cobrada. |
Ejemplo de la respuesta JSON:
{
"error": "0",
"message": "success",
"charges": [
{
"cash_charge_id": "3926",
"company_id": "2692",
"branch_id": "2720",
"user_id": "2691",
"reference": "S-PFCPE2692S2720I3926",
"customer_reference": "43",
"cash_processor_reference": "VSZMDQ4UWGRFP96",
"cash_processor_reference_short": "GRFP96",
"cash_processor_id": "1",
"amount": "550.00",
"status": "2",
"status_desc": "PENDIENTE",
"expiration": "2018-09-22 12:09:00",
"created": "2018-09-17 17:25:49",
"status_at": "2018-09-17 17:25:49",
"paid_at": null,
"convenience_store_id": "1",
"bank_account_number": "xx-xxxxxxxx-x",
"bank_id": "169",
"paid": "0",
"brand_name": "PAGOFACIL DEMO",
"convenience_store": "SANTANDER",
"convenience_store_code": "SANTANDER",
"buyer_name": "11",
"buyer_email": "[email protected]",
"product_name": "Zapatos",
"bank_name": "BANCO DE PRUEBAS",
"cash_charge_fee_id": "3844",
"fee_percentage": "0.00",
"fee_percentage_amount": "0.00",
"tax_percentage": "16.00",
"tax_amount": "0.00",
"fixed_rate": "3.00",
"total_fee_amount": "0.00",
"fee_percentage_processor": "0.00",
"fee_percentage_amount_processor": "0.00",
"fixed_rate_processor": "0.00",
"profit": "0.00"
},
{
"cash_charge_id": "3922",
"company_id": "2692",
"branch_id": "4663",
"user_id": "2691",
"reference": "S-PFCPE2692S4663I3922",
"customer_reference": "luigi",
"cash_processor_reference": "3HIK1Z56P0XWJCS",
"cash_processor_reference_short": "0XWJCS",
"cash_processor_id": "1",
"amount": "50.00",
"status": "2",
"status_desc": "PENDIENTE",
"expiration": "2018-09-12 12:09:00",
"created": "2018-09-07 15:36:14",
"status_at": "2018-09-07 15:36:14",
"paid_at": null,
"convenience_store_id": "1",
"bank_account_number": "xx-xxxxxxxx-x",
"bank_id": "169",
"paid": "0",
"brand_name": "PAGOFACIL DEMO",
"convenience_store": "SANTANDER",
"convenience_store_code": "SANTANDER",
"buyer_name": "Luigi",
"buyer_email": "[email protected]",
"product_name": "prueba",
"bank_name": "BANCO DE PRUEBAS",
"cash_charge_fee_id": "3840",
"fee_percentage": "0.00",
"fee_percentage_amount": "0.00",
"tax_percentage": "16.00",
"tax_amount": "0.00",
"fixed_rate": "3.00",
"total_fee_amount": "2.42",
"fee_percentage_processor": "0.00",
"fee_percentage_amount_processor": "0.00",
"fixed_rate_processor": "0.00",
"profit": "0.00"
}
]
}WEBHOOKS
Desde el sistema Manager, se pueden configurar las URLs a las cuales se enviarán los datos una vez que la orden se refleje el pago.
Éstas mismas, se pueden dar de alta desde Configuraciones > Pagos en Efectivo.
Campos de la petición:
| Campo | Tipo | Longitud | Descripción |
|---|---|---|---|
| reference | String | 45 | Referencia de la Orden de compra. |
| customer_order | String | 20 | Número de la orden. |
| String | 100 | Correo de cliente. | |
| amount | Decimal | Cantidad de la transacción. | |
| convenience_store | String | 20 | Tienda de conveniencia. |
| bank_account_number | String | 20 | Numero de referencia bancaria de la orden. |
| bank | String | 20 | Banco dónde se realizó el depósito. |
| created_at | Timestamp | Fecha de creación de la Orden. | |
| expiration_date | Timestamp | Fecha de expiración de la Orden. | |
| status | String | 2 | Status de la Orden
(2: pendiente de pago, 4: orden pagada, 5: orden pagada manual). |
| fee | Decimal | Comisión cobrada. | |
| fee_amount | Decimal | Comisión cobrada. | |
| tax_amount | Decimal | Impuesto de la comisión. | |
| fixed_rate | Decimal | Comisión cobrada por la tienda de conveniencia. | |
| total_fee_amount | Decimal | Total de la comisión. |
POSTMAN
En el siguiente link lo redirigirá a un ejemplo práctico en diferentes lenguajes de programación mediante la herramienta Postman.