Casos de Usos via API


Introducción

En esta sección unimos todo lo anterior para exponer ejemplos más concretos de los casos más comunes que se podrían tener como un comercio utilizando el Sandbox de PixelPay.

Casos de uso via API

Los cobros son una forma segura de pagar usando PixelPay sin ser redirigidos a otro sitio web o ver el modal de pago.

Existen dos maneras de realizar un pago:

  • Realizar un request enviando los datos de orden, de la tarjeta, y de dirección.
  • Realizar un request enviando los datos de orden y el token de la tarjeta tokenizada.

Realizar cobros / Venta directa

Ruta de envío de parámetros para una venta directa

POST https://pixel-pay.com/api/v2/transaction/sale

El request se tiene que realizar con los Headers vistos en instalación

Indice de campos

Todos los campos deberán ser enviados como parámetros en la consulta https en formato Query String o incluir en el header tipo de formato content-type: x-www-form-urlencoded.

Campo Valor Validación Descripción
order_id Alfanumérico Requerido Número o identificador único de la orden o pago
order_currency USD/HNL/NIO Requerido, 3 caracteres, mayúscula Moneda en la cual se realizara el cobro
order_amount 0.00 Requerido, double Cantidad total del cobro en moneda, dentro del sandbox el monto funciona para elegir el tipo de transacción que se quiere ejecutar (Ver tabla Casos de Prueba.)
customer_name Texto corto Requerido, min:3, max:120 Nombre completo del cliente
customer_email usuario@dominio.com Requerido Dirección principal del cliente
billing_address Texto corto Requerido Dirección principal del cliente
billing_state Texto corto Requerido Código del estado según estándar ISO 3166 ALPHA-2
billing_country Texto corto Requerido, min: 3, max:15 Código del país del titular de la tarjeta
billing_zip Texto corto No requerido El campo de código postal no es requerido, sin embargo, si es enviado se realizara una evaluación para confirmar el formato del código postal correspondiente al País. Revisa la lista de países donde la evaluación del formato no aplica dando clic aquí.
billing_phone Numérico Requerido Teléfono del cliente
card_number Numérico Requerido, min:16 max: 16 Número de Tarjeta.
card_holder Texto corto Requerido, min:3, max:120 Nombre del titular de la tarjeta
card_cvv Numérico Requerido, min: 3, max: 4 Número cvv de la tarjeta
card_expire Numérico Requerido, min: 4, max: 4 Fecha de expiración de la tarjeta en formato YY/MM
card_token UUID Opcional Token de una tarjeta tokenizada
order_callback https://... Opcional, URL URL asincrónica (equivalente al WebHook) de éxito
env Alfanumérico Requerido Campo necesario dentro del ambiente sandbox, el valor debe ser: sandbox
lang es o en Opcional Código de lenguaje que usará el sandbox, por defecto es para español

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/transaction/sale

// DATOS ENVIADOS EN LA PETICIÓN "POST"

// Ejemplo enviando los datos de la tarjeta
{
  "customer_name": "Jonh Doe",
  "card_number": "4111111111111111",
  "card_holder": "Jonh Doe",
  "card_expire": "2512",
  "card_cvv": "999",
  "customer_email": "yourmail@pixel.hn",
  "billing_address": "Calle 1",
  "billing_city": "Sula",
  "billing_country": "HN",
  "billing_state": "HN-CR",
  "billing_phone": "5581998855",
  "order_id": "9999",
  "order_currency": "HNL",
  "order_amount": "1",
  "env": "sandbox",
  "lang": "es"
}

// Ejemplo enviando el token de la tarjeta
{
  "customer_name": "Jonh Doe",
  "card_token": "T-146cf971-3e2e-43f2-9f55-e29144619bc7",
  "customer_email": "yourmail@pixel.hn",
  "order_id": "9999",
  "order_currency": "HNL",
  "order_amount": "1",
  "env": "sandbox",
  "lang": "es"
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Recuerda que las tarjetas permitidas dentro del Sandbox son la 4111111111111111 y la 5555555555554444.


Ejemplo de respuesta exitosa

Como ejemplo se colocó el valor "1" en la propiedad order_amount, se recibirá siguiente respuesta que será exitosa:

{
  "success": true,
  "message": "Transacción completada exitosamente",
  "data": {
    "transaction_type": "sale"
    "transaction_approved_amount": 1,
    "transaction_amount": 1,
    "response_cvn": "M",
    "response_avs": "U",
    "response_cavv": "2",
    "transaction_id": "1f694eee-4715-45b8-a545-000000000000",
    "transaction_time": "110932",
    "transaction_date": "1221",
    "response_approved": true,
    "response_incomplete": false,
    "response_code": "00",
    "response_time": "2.463",
    "transaction_auth": "123456",
    "transaction_reference": "123456789012",
    "transaction_terminal": null,
    "transaction_merchant": null,
    "response_reason": "Transacción completada exitosamente",
    "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
    "payment_hash": "22265408aab8377c33ff6b9122e59e70"
}

Que puedes enviar diferente cantidad en el campo order_amount para así obtener diferentes respuestas según sea tu necesidad. Ver casos de prueba


Realizar una Autorización

Para enviar una transacción de tipo autorización, seguimos los mismos pasos de una venta directa donde los campos requeridos son los mismos, con la excepción de que el request será enviado a una URL diferente.

De igual manera que una venta directa, podemos realizar una transacción de autorización con una tarjeta de crédito / débito o con una tarjeta tokenizada.

Ruta para envío de parámetros para una Autorización

POST https://pixel-pay.com/api/v2/transaction/auth

El request se tiene que realizar con los Headers vistos en instalación


Ejemplo de respuesta exitosa

Como ejemplo se colocó el valor "1" en la propiedad order_amount, se recibirá siguiente respuesta que será exitosa:

{
  "success": true,
  "message": "La transacción ha sido autorizada con éxito por la cantidad de L 1",
  "data": {
    "transaction_type": "auth",
    "transaction_amount": "1",
    "transaction_auth": "831000",
    "response_cvn": "M",
    "response_avs": "Y",
    "transaction_id": "6353798475916248604012",
    "transaction_time": "061048",
    "transaction_date":"1027",
    "response_approved":true,
    "response_incomplete":false,
    "response_code": "100",
    "response_time":"1.037",
    "response_reason":"Transacción completada exitosamente.",
    "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
    "payment_hash": "87d77b9dfbafe12811710c2b29c15756"
  },
  "status": 200
}

Guardar el payment_uuid porque es el que se utilizará para capturar el pago.


Realizar una Captura de un pago

Para realizar una captura de un pago, solo se necesita el UUID del cobro y la cantidad que se desea capturar, ya que la petición se realiza a un cobro que previamente fue autorizado.

Ruta para envío de parámetros para una captura de pago

POST https://pixel-pay.com/api/v2/transaction/capture

El request se tiene que realizar con los Headers vistos en instalación

Índice de campos

Campo Valor Validación Descripción
transaction_approved_amount Numérico Requerido Cantidad de la transacción que será capturada, en caso de sandbox la cantidad es 1
payment_uuid UUID Requerido Identificador único del pago
env Alfanumérico Requerido Campo necesario dentro del ambiente sandbox, el valor debe ser: sandbox

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/transaction/capture

// DATOS ENVIADOS EN LA PETICIÓN "POST"
{
  "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
  "transaction_approved_amount": 1,
  "env":"sandbox"
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "La transacción ha sido pagada con éxito",
  "data": {
    "transaction_type": "capture",
    "transaction_approved_amount": null,
    "transaction_amount": "1.00",
    "transaction_auth": "null",
    "transaction_id": "6354304898006449603007",
    "transaction_time": "061048",
    "transaction_date":"1027",
    "response_approved":true,
    "response_incomplete":false,
    "response_code": "100",
    "response_time":"1.037",
    "response_reason":"Successful transaction.",
  },
  "status": 200
}

Realizar una Anulación de un pago

Para realizar una anulación de un pago, solo se necesita enviar un payment_uuid, void_reason, order_amount y la variable env.

Ruta para envío de parámetros para una anulación de pago

POST https://pixel-pay.com/api/v2/transaction/void

El request se tiene que realizar con los Headers vistos en instalación

Índice de campos

Campo Valor Validación Descripción
void_reason Texto Requerido Razón o motivo de la anulación del pago
payment_uuid UUID Requerido Identificador único del pago
order_amount Numérico Requerido Cantidad del cobro
env Texto Requerido Campo necesario dentro del ambiente sandbox, el valor debe ser: sandbox

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/transaction/void

// DATOS ENVIADOS EN LA PETICIÓN "POST"
{
  "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
  "env":"sandbox",
  "void_reason":"Test de anulación",
  "order_amount": 1
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Transacción anulada exitosamente",
  "data": {
    "transaction_type": "void",
    "transaction_approved_amount": 0,
    "transaction_amount": 1,
    "response_cvn": "M",
    "response_avs": "U",
    "response_cavv": "2",
    "transaction_id": "1f694eee-4715-45b8-a545-000000000000",
    "transaction_time": "110932",
    "transaction_date": "1221",
    "response_approved": true,
    "response_incomplete": false,
    "response_code": "00",
    "response_time": "2.463",
    "transaction_auth": "123456",
    "transaction_reference": "123456789012",
    "transaction_terminal": null,
    "transaction_merchant": null,
    "response_reason": "Transacción completada exitosamente",
    "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
    "payment_hash": "f86b7a87db4ca7f14699aa7d5a55de6a"
  }
}

Tokenizar una tarjeta

Para realizar una transacción en el Sandbox, también puedes realizarla con un token de tarjeta tokenizada.

Para crear una tarjeta, se debe enviar el request a esta URL:

Ruta de envío de parámetros para tokenizar una tarjeta

POST https://pixel-pay.com/api/v2/tokenization/card

El request se tiene que realizar con los Headers vistos en instalación

Índice de campos

Campo Requerido Valor Descripción
cvv2 Si Numérico de 3 dígitos Código de seguridad que se encuentra al reverso de la tarjeta y contiene 3 o 4 dígitos
number Si Numérico de 15 o 16 dígitos 15 o 16 números del frente de la tarjeta
expire_month Si Numérico de 2 dígitos Mes de expiración de la tarjeta
expire_year Si Numérico de 4 dígitos Año de expiración de la tarjeta
cardholder Si String Nombre del titular de la tarjeta
address Si String Dirección del titular de la tarjeta
city Si String Ciudad del titular de la tarjeta
country Si String(2) ISO 3166 ALPHA-2 Código del país del titular de la tarjeta
state Si Código del país y código del estado ej. HN-CR Estado del titular de la tarjeta
zip No Numérico de 5 dígitos Código postal del titular de la tarjeta
phone Si Numérico 7 - 15 digitos Número del titular de la tarjeta
customer No Token Token obtenido al crear un customer
email No Alfanumérico Dirección de correo
env Alfanumérico Requerido Campo necesario dentro del ambiente sandbox, el valor debe ser: sandbox
lang es o en Opcional Código de lenguaje que usará el sandbox, por defecto es para español

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/tokenization/card

// DATOS ENVIADOS EN LA PETICIÓN "POST"
{
  "cvv2": "123",
  "number": 5555555555554444,
  "expire_month": "12",
  "expire_year": "2020",
  "cardholder": "Fulanito de Tal",
  "address": "Holstein 109-57",
  "country": "HN",
  "city": "San Pedro Sula",
  "state": "CR",
  "zip": "21102",
  "phone": "95852921",
  "lang": "es",
  "env":"sandbox"
}

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "token": "T-77d49af9-132d-41a3-97ce-b38a74e608be",
    "status": "active",
    "mask": "555555******4444",
    "network": "mastercard",
    "type": "CREDIT",
    "bin": "555555",
    "last": "4444",
    "hash": "2570d25703ee578289eb6d6d1cbf4e311c34ecb2602c9241f937993899d9d9be6b5c3c33bb63a9242277f64ea79cde356540e500f514a0583394d795f8fb23c7",
    "address": "Holstein 109-57",
    "country": "HN",
    "state": "HN-CR",
    "city": "San Pedro Sula",
    "zip": "21102",
    "phone": "95852921"
  }
}

Guardar el token de la tarjeta porque ya no podras volver a obtenerlo, a menos que se tokenice otra tarjeta.


Obtener información de una tarjeta

Para obtener información de una tarjeta se debe enviar el request a esta URL:

Ruta de envío de parámetros para obtener información de una tarjeta

GET https://pixel-pay.com/api/v2/tokenization/card/{token}

El request se tiene que realizar con los Headers vistos en instalación

Índice de campos

Campo Requerido Valor Descripción
token Si Alfanumérico Es el token que se obtuvo al tokenizar una tarjeta previamente
env Texto Requerido Campo necesario dentro del ambiente sandbox, el valor debe ser: sandbox

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/tokenization/card/{token}

// DATOS ENVIADOS EN LA PETICIÓN "GET"

// https://pixel-pay.com/api/v2/tokenization/card/T-77d49af9-132d-41a3-97ce-b38a74e608be

{
  "env": "sandbox"
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "token": "T-77d49af9-132d-41a3-97ce-b38a74e608be",
    "status": "active",
    "mask": "555555******4444",
    "network": "mastercard",
    "type": "CREDIT",
    "bin": "555555",
    "last": "4444",
    "hash": "2570d25703ee578289eb6d6d1cbf4e311c34ecb2602c9241f937993899d9d9be6b5c3c33bb63a9242277f64ea79cde356540e500f514a0583394d795f8fb23c7",
    "address": "Holstein 109-57",
    "country": "HN",
    "state": "HN-CR",
    "city": "San Pedro Sula",
    "zip": "21102",
    "phone": "95852921"
  }
}

Actualizar información de una tarjeta

Por medio de este request podemos actualizar la información de una tarjeta utilizando los mismos campos que utilizamos al almacenarla y en la URL de la petición el token de la tarjeta que obtuvimos en la respuesta al momento de almacenarla. Los datos enviados serán reemplazados por los anteriores.

Ruta de envío de parámetros para actualizar la información de una tarjeta

PUT https://pixel-pay.com/api/v2/tokenization/card/{token}

El request se tiene que realizar con los Headers vistos en instalación

Índice de campos

En el request solo se enviarán los campos que se quieren actualizar, pero existen sus excepciones, por ejemplo si se quiere actualizar el CVV, es necesario también enviar el número de tarjeta, o si se quiere actualizar el código de estado, es necesario enviar también el código del país como se muestra en el índice de campos al crear una tarjeta.


Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/tokenization/card/{token}

// DATOS ENVIADOS EN LA PETICIÓN "PUT"

{
  "cvv2": "123",
  "number": "4111111111111111",
  "env": "sandbox"
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "token": "T-77d49af9-132d-41a3-97ce-b38a74e608be",
    "status": "active",
    "mask": "411111******1111",
    "network": "visa",
    "type": "CREDIT",
    "bin": "411111",
    "last": "1111",
    "hash": "2570d25703ee578289eb6d6d1cbf4e311c34ecb2602c9241f937993899d9d9be6b5c3c33bb63a9242277f64ea79cde356540e500f514a0583394d795f8fb23c7",
    "address": "Holstein 109-57",
    "country": "HN",
    "state": "HN-CR",
    "city": "San Pedro Sula",
    "zip": "21102",
    "phone": "95852921"
  }
}

Eliminar una tarjeta

Por medio de este request podremos eliminar una tarjeta utilizando el token que recibimos al momento de almacenarla y enviarlo en la URL de la petición.

Ruta de envío de parámetros para eliminar una tarjeta

DELETE https://pixel-pay.com/api/v2/tokenization/card/{token}

El request se tiene que realizar con los Headers vistos en instalación


Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/tokenization/card/{token}

// DATOS ENVIADOS EN LA PETICIÓN "DELETE"

// https://pixel-pay.com/api/v2/tokenization/card/T-77d49af9-132d-41a3-97ce-b38a74e608be"

{
  "env": "sandbox"
}

Ejemplo de request utilizando POSTMAN

Headers con Postman


Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "token": "T-77d49af9-132d-41a3-97ce-b38a74e608be",
    "deleted": true
  }
}

Los tokens de tarjeta creados en el Sandbox, se eliminan automáticamente 5 horas después de haberse creado.


Países donde no es necesario enviar el Código postal

En los países listados a continuación no se realiza una evaluación del formato del código postal.

Angola, Bahamas, Belice, Benín, Bolivia, Botsuana, Burkina Faso, Burundi, Camerún, Comoras, República del Congo, República Democrática del Congo, Corea del Norte, Costa de Marfil, Dominica, Emiratos Árabes Unidos, Eritrea, Fiyi, Gabón, Gambia, Ghana, Granada, Guinea Ecuatorial, Guyana, Honduras, Irlanda, Islas Cook, Islas Salomón, Kiribati, Malawi, Mali, Mauritania, Namibia, Nauru, Niue, Panamá, Qatar, República Centroafricana, Ruanda, San Cristóbal y Nieves, Santa Lucía, Santo Tomé y Príncipe, Seychelles, Sierra Leona, Siria, Somalia, Surinám, Tanzania, Timor Oriental, Togo, Tokelau, Tonga, Trinidad y Tobago, Tuvalu, Uganda, Vanuatu, Yemen, Yibuti, Zimbabue, Isla Bouvet.

Todos los SDKs incluyen el listado de países y estados con todos los datos necesarios, puedes revisar aquí para más información.