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

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:

Nombre store_code
Tiendas Seven Eleven SEVEN_ELEVEN
Tiendas Extra EXTRA
Farmacia Benavides FARMACIA_BENAVIDES
Farmacias del Ahorro FARMACIAS_DEL_AHORRO
Via Servicios VIA_SERVICIOS
Tiendas Circle K CIRCLE_K
Grupo RFP GRUPO_RFP
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
email 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-PFCPE2692S2720I3612

Campos 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:00

Campos 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.
email 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.