Documentaci N de La API de Payment
Documentaci N de La API de Payment
Documentaci N de La API de Payment
Introducción:
El objetivo que se persigue con este documento es proporcionar una guía a los
desarrolladores para utilizar la API REST de pago que utiliza la plataforma ENZONA y
así puedan integrar sus aplicaciones con la misma. La API REST para realizar los
pagos permite, entre otras cosas, que quien quiera implantar un negocio pueda
emplear una aplicación que le permita tener registradas todas sus ventas, pagos a
empleados, etc, integrándose a esta plataforma, y, por otro lado, brindan al cliente la
posibilidad de no emplear dinero en efectivo para proceder a pagar. La API REST de
pago brinda la opción, en función de cómo se conciba el negocio, de que, para pagar
el costo asociado a un producto determinado, el cliente lo pueda efectuar ya sea
especificando de manera explícita cuál es el producto y el precio correspondiente al
mismo, o escaneando un código de barras o un código QR que identifica a dicho
producto.
A continuación, se explica de forma más detallada, cuáles son los escenarios, el flujo,
y los parámetros de entrada de datos para utilizar esta API.
Índice
Introducción:................................................................................................................................. 1
Pasos para usar el API:................................................................................................................ 4
Flujo de trabajo del API de Payment para crear un pago.............................................................6
Pasos para realizar el flujo del API de Payment cuando se crea un pago...............................6
Explicación de los Links al crear un pago creado satisfactoriamente...........................................8
PaymentAPI:................................................................................................................................ 9
Permite crear un pago.............................................................................................................. 9
Parámetros de entrada:........................................................................................................ 9
Parámetros de Salida:........................................................................................................ 10
Obtiene un listado de todos los pagos realizados..................................................................11
Parámetros de entrada:...................................................................................................... 11
Parámetros de Salida:........................................................................................................ 11
Obtiene los detalles de un pago realizado..............................................................................12
Parámetros de entrada:...................................................................................................... 12
Parámetros de Salida:........................................................................................................ 12
Permite completar un pago.................................................................................................... 13
Parámetros de entrada:...................................................................................................... 13
Parámetros de Salida:........................................................................................................ 13
Permite cancelar un pago....................................................................................................... 14
Parámetros de entrada:...................................................................................................... 14
Parámetros de Salida:........................................................................................................ 14
Permite obtener un pago........................................................................................................ 15
Parámetros de entrada:...................................................................................................... 15
Parámetros de Salida:........................................................................................................ 15
Permite realizar la devolución de un pago..............................................................................16
Parámetros de entrada:...................................................................................................... 16
Parámetros de entrada:...................................................................................................... 16
Parámetros de Salida:........................................................................................................ 16
Obtiene los detalles de una devolución realizada..................................................................17
Parámetros de entrada:...................................................................................................... 17
Parámetros de Salida:........................................................................................................ 17
Obtiene una lista de devoluciones realizadas........................................................................18
Parámetros de entrada:...................................................................................................... 18
Parámetros de Salida:........................................................................................................ 18
Lista de devoluciones de un pago.......................................................................................... 19
Parámetros de entrada:...................................................................................................... 19
Parámetros de Salida:........................................................................................................ 19
Permite crear un recieve code................................................................................................ 20
Parámetros de entrada:...................................................................................................... 20
Parámetros de Salida:........................................................................................................ 20
Tabla 1. Código de estados generales y denominaciones.........................................................18
Tabla 2. Código de estados de las transacciones y sus denominaciones..................................19
Tabla 3. Código de errores de la plataforma enzona.................................................................21
Pasos para usar el API:
1. Una vez hecho los pasos del documento sobre la autenticación y obtención de
token de acceso debe tener en cuenta q el token que genere haya sido con el
alcance enzona_payment, así asegura tener permisos sobre los recursos del
API en cuestión.
5. Una vez hecho esto, llenamos los parámetros con los valores correctos y con el
formato correcto, seleccionamos el botón Execute y la API dará su respuesta.
Flujo de trabajo del API de Payment para crear un pago
Pasos para realizar el flujo del API de Payment cuando se crea un pago
4. Si enzona redirecciona a la url de retorno que fue entrada por parámetros por
usted al crear el pago entonces el pago fue confirmado por el cliente y el
comercio procede a completarlo utilizando el API de que tiene por recurso
/payments/{transaction_uuid}/complete.
1. Al crear el pago correctamente, el mismo devuelve cinco links, los cuales serán
explicados a continuación.
2. El primer link tiene por método REDIRECT y por rel confirm, el cual
redirecciona al cliente que esté efectuando el pago, a la plataforma de enzona
para que lo confirme.
3. El segundo links tiene por método POST y por rel complete, este es el link
utilizado para completar el pago mediante el API que tiene por recurso
/payments/{transaction_uuid}/complete
4. El tercer link tiene por método POST y por rel cancel, este link es utilizado para
cancelar el pago mediante el recurso del API
/payments/{transaction_uuid}/cancel
5. El cuarto link tiene por método POST y por rel refund, este link es utilizado para
la devolución del pago, explicado en el recurso del API
/payments/{transaction_uuid}/refund
6. El quinto link tiene por método GET y por rel self, este link es utilizado para
devolver los detalles de un pago, explicado en el recurso del API
/payments/{transaction_uuid}
PaymentAPI:
Permite crear un pago
Recurso: /payments
Método: POST
Parámetros de entrada:
{
"description": Es una descripción del pago,
"currency": Tipo de moneda, puede ser CUP o CUC,
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"name": Nombre del Producto,
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto
}
],
"merchant_op_id": Identificador de la operación del comercio,
"invoice_number": Número de la factura,
"return_url": url de retorno,
"cancel_url": url de cancelación,
"terminal_id": identificador de los terminals (POS, Caja Registradora, etc),
"buyer_identity_code": Código del comprador (Este Parámetro no se utiliza para crear
un pago)
}
Parámetros de Salida:
{
"transaction_uuid": Identificador de la transacción,
"currency": Tipo de moneda, puede ser CUP o CUC,
"created_at": Fecha de creación del pago,
"update_at": Fecha de actualización del pago,
"status_code": Código de estado de la transacción,
"status_denom": Denominación de estado de la transacción,
"description": Descripción del pago,
"invoice_number": Número de factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": Nombre del Producto
}
],
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Obtiene un listado de todos los pagos realizados
Recurso: /payments
Método: GET
Parámetros de entrada:
merchant_uuid: Identificador del comercio
limit: cantidad de datos a mostrar
offset: donde se va a empezar a mostrar los datos
status_filter: Estado de; pago
start_date_filter: Fecha inicial para filtrar los pagos
end_date_filter: Fecha final para filtrar los pagos
order_filter: para ordenar los pagos obtenidos (Ascendentemente o
descendentemente)
Parámetros de Salida:
{
"payments": [
{
"transaction_uuid": Identificador de la transacción,
"currency": Tipo de moneda, puede ser CUP o CUC,
"created_at": Fecha de creación del pago,
"update_at": Fecha de actualización del pago,
"status_code": Código de estado de la transacción,
"status_denom": Denominación de estado de la transacción,
"description": Descripción del pago,
"invoice_number": Número de factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": " Nombre del Producto "
}
],
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
]
}
Obtiene los detalles de un pago realizado
Recurso: /payments/{transaction_uuid}
Método: GET
Parámetros de entrada:
transaction_uuid: Identificador de la transacción
Parámetros de Salida:
{
"transaction_uuid": Identificador de la transacción,
"currency": Tipo de moneda, puede ser CUP o CUC,
"created_at": Fecha de creación del pago,
"update_at": Fecha de actualización del pago,
"status_code": Código de estado de la transacción,
"status_denom": Denominación de estado de la transacción,
"description": Descripción del pago,
"invoice_number": Número de factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": Nombre del Producto
}
],
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Permite completar un pago
Recurso: /payments/{transaction_uuid}/complete
Método: POST
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción
Parámetros de Salida:
{
"transaction_uuid": Identificador de la transacción,
"currency": Tipo de moneda, puede ser CUP o CUC,
"created_at": Fecha de creación del pago,
"update_at": Fecha de actualización del pago,
"status_code": Código de estado de la transacción,
"status_denom": Denominación de estado de la transacción,
"description": Descripción del pago,
"invoice_number": Número de factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": Nombre del Producto
}
],
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Permite cancelar un pago
Recurso: /payments/{transaction_uuid}/cancel
Método: POST
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción
Parámetros de Salida:
{
"transaction_uuid": Identificador de la transacción,
"currency": Tipo de moneda, puede ser CUP o CUC,
"created_at": Fecha de creación del pago,
"update_at": Fecha de actualización del pago,
"status_code": Código de estado de la transacción,
"status_denom": Denominación de estado de la transacción,
"description": Descripción del pago,
"invoice_number": Número de factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": Identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": Nombre del Producto
}
],
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Permite obtener un pago
Recurso: /payments/checkout/{uuid}
Método: GET
Parámetros de entrada:
uuid: Es el identificador de la confirmación de un pago
Parámetros de Salida:
"uuid": Identificador del checkout,
"create_at": Fecha en la que se realizó el checkout,
"update_at": Fecha en la que se actualizó el checkout,
"state": Estado del Pago,
"merchant_alias": Alias del Comercio,
"merchant_name": Nombre del Comercio,
"return_url": URL de retorno,
"cancel_url": URL de cancelación,
"currency": Tipo de moneda,
"description": Descripción del pago,
"invoice_number": Número de Factura,
"merchant_op_id": Identificador de la operación del comercio,
"terminal_id": Identificador de los terminals (POS, Caja Registradora, etc),
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina
}
},
"items": [
{
"description": Descripción del Producto,
"quantity": Cantidad del Producto,
"price": Precio del Producto,
"tax": Monto de impuesto del producto,
"name": Nombre del Producto
}
],
"merchant_avatar": Imagen del Comercio,
"transaction_status_code": Código de estado de la transacción,
"list_links": {
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
}
Permite realizar la devolución de un pago
Recurso: /payments/{transaction_uuid}/refund
Método: POST
Existen dos formas en la que puedes mandar los parámetros de entradas para este
recurso.
Si mandas los parámetros de entrada de esta forma la devolución del pago será
completa.
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción, que para realizar la devolución
esta uuid tiene que ser de una transacción aceptada.
{
Si mandas los parámetros de entrada de esta forma la devolución del pago será
parcial.
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción, que para realizar la devolución
esta uuid tiene que ser de una transacción aceptada.
{
"amount": {
"total": Monto Total a devolver
},
"description": Descripción de la devolución
}
Parámetros de Salida:
{
"uuid": Identificador de la devolución,
"state": Estado de la devolución,
"transaction_status_code": Código de estado de la devolución,
"transaction_denom": Denominación de estado de la devolución,
"created_at": Fecha de creada de la devolución,
"updated_at": Fecha de actualizada de la devolución,
"parent_payment_uuid": Pago inicial,
"description": Descripción de la devolución,
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Obtiene los detalles de una devolución realizada
Recurso: /payments/refund/{transaction_uuid}
Método: GET
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción
Parámetros de Salida:
{
"uuid": Identificador de la devolución,
"state": Estado de la devolución,
"transaction_status_code": Código de estado de la devolución,
"transaction_denom": Denominación de estado de la devolución,
"created_at": Fecha de creada de la devolución,
"updated_at": Fecha de actualizada de la devolución,
"parent_payment_uuid": Identificador del pago de la devolución,
"description": Descripción de la devolución,
"links": [
{
"rel": path de la url,
"method": nombre del método,
"href": url del servicio
}
]
}
Obtiene una lista de devoluciones realizadas
Recurso: /payments/refund
Método: GET
Parámetros de entrada:
merchant_uuid: Es el identificador del comercio
limit: cantidad de datos a mostrar
offset: donde se va a empezar a mostrar los datos
status_filter: Estado de; pago
start_date_filter: Fecha inicial para filtrar los pagos
end_date_filter: Fecha final para filtrar los pagos
order_filter: para ordenar los pagos obtenidos (Ascendentemente o
descendentemente)
Parámetros de Salida:
{
"refunds": [
{
"transaction_uuid": Identificador de la transacción,
"status_code": Código de estado,
"status_denom": Denominador de estado,
"transaction_created_at": Fecha de creación de la transacción,
"transaction_updated_at": Fecha de actualización de la transacción,
"transaction_signature": Firma de la Transacción,
"amount": {
"total": Monto total a pagar,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina,
"refunded": Monto a devolver,
"total_refunded": Monto total a devolver
}
},
"currency": Tipo de moneda, puede ser CUP o CUC,
"transaction_description": descripción de la transacción,
"transaction_denom": Denominación de estado de la devolución,
"transaction_code": Código de una transacción,
"terminal_id": Identificador de los terminals (POS, Caja Registradora, etc),
"invoice_number": Número de Factura,
"username": usuario a devolverle el monto,
"name": Nombre del usuario a devolverle el monto,
"lastname": Apellido del usuario a devolverle el monto,
"avatar": Foto del comercio,
"items": [
{
"description": Descripción del producto a devolver,
"quantity": Cantidad del producto a devolver,
"price": Precio del producto a devolver,
"tax": impuesto del producto a devolver,
"name": Nombre del producto a devolver
}
]
}
]
}
Lista de devoluciones de un pago
Recurso: /payments/{transaction_uuid}/refunds
Método: GET
Parámetros de entrada:
transaction_uuid: Es el identificador de la transacción
limit: cantidad de datos a mostrar
offset: donde se va a empezar a mostrar los datos
status_filter: Estado de; pago
start_date_filter: Fecha inicial para filtrar los pagos
end_date_filter: Fecha final para filtrar los pagos
order_filter: Ordena los pagos obtenidos (Ascendentemente o descendentemente)
Parámetros de Salida:
{
"refunds": [
{
"transaction_uuid": Identificador de la transacción,
"status_code": Código de estado,
"status_denom": Denominador de estado,
"transaction_created_at": Fecha de creación de la transacción,
"transaction_updated_at": Fecha de actualización de la transacción,
"transaction_signature": Firma de la transacción,
"amount": {
"total": Monto total a devolver,
"details": {
"shipping": Monto del envío del producto,
"tax": Monto de impuesto,
"discount": Descuento del producto,
"tip": Propina,
"refunded": Monto a devolver,
"total_refunded": Monto total a devolver
}
},
"currency": Tipo de moneda, puede ser CUP o CUC,
"transaction_description": descripción de la transacción,
"transaction_denom": Denominación de estado de la devolución,
"transaction_code": Código de la transacción,
"terminal_id": Identificador de los terminals (POS, Caja Registradora, etc),
"invoice_number": Número de Factura,
"username": usuario a devolverle el monto,
"name": Nombre del usuario a devolverle el monto,
"lastname": Apellido del usuario a devolverle el monto,
"avatar": Foto del comercio,
"items": [
{
"description": Descripción del producto a devolver,
"quantity": Cantidad del producto a devolver,
"price": Precio del producto a devolver,
"tax": impuesto del producto a devolver,
"name": Nombre del producto a devolver
}
]
}
]
}
Permite crear un recieve code
Recurso: /payments/vendor/code
Método: GET
Este recurso es para crear un pago por medio de QR.
Parámetros de entrada:
{
"funding_source_uuid": La cuenta asociada al QR,
"amount": Monto del código QR a crear,
"vendor_identity_code": Código del QR creado,
"description": Descripción del Código QR,
"currency": Tipo de Moneda,
"payment_password": Contraseña de Pago
}
Parámetros de Salida:
{
"status": Estado del QR,
"mensaje": Información
}
Tabla 1. Código de estados generales y denominaciones
4002 El destino no tiene una tarjeta El destino no tiene una tarjeta activa
activa
4053 No puede poner el teléfono nulo No puede poner el teléfono vacío sin
sin tener correo configurado tener una dirección correo
configurada