Casos de Usos via SDK

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 SDK

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 pago enviando la orden, de la tarjeta, y de dirección.
  • Realizar un pago enviando los datos de orden y el token de la tarjeta tokenizada.

Realizar cobros / Venta directa

Para poder comenzar a realizar una venta o cobro directo en el ambiente Sandbox, recuerda que primero es necesario instanciar el SDK así como se muestra en instalación.

Realizar una venta directa

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

// Creación del objeto Order
const order = new Models.Order()
order.id = 'TEST-1234'
order.currency = 'HNL'
order.amount = '1'
order.customer_name = 'Jhon Doe'
order.customer_email = 'jhondow@pixel.hn'

// Creación del objeto Card
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creación del objeto Billing
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Se instancia el request de SaleTransaction que es el que realiza la transaccion
const sale = new Requests.SaleTransaction()
sale.setCard(card)
sale.setBilling(billing)
sale.setOrder(order)

// Se realiza la transacción don el método doSale
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

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

Realizar una venta directa con token de tarjeta


// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

// Creación del objeto Order
const order = new Models.Order()
order.id = 'TEST-1234'
order.currency = 'HNL'
order.amount = "1"
order.customer_name = 'Jhon Doe'
order.customer_email = 'jhondow@pixel.hn'

// Se instancia el request de SaleTransaction que es el que realiza la transaccion
const sale = new Requests.SaleTransaction()
sale.setOrder(order)

// Aqui se setea el token de la tarjeta, no es necesario enviar el objeto card ni el obejeto billing
sale.setCardToken("T-6611b606-8ca6-4097-8584-4bc816b8612b")

// Se realiza la transacción don el método doSale
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Ejemplo de respuesta exitosa

Como ejemplo se colocó el valor "1" en el campo 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": "00000394",
    "transaction_merchant": " 0000004959",
    "installment_type": null,
    "installment_months": 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 amount para así obtener diferentes respuestas según sea tu necesidad. Ver casos de prueba

Realizar una Autorización

Para poder comenzar a realizar una Autorización en el ambiente Sandbox, recuerda que primero es necesario instanciar el SDK así como se muestra en instalación.

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

// Creación del objeto Order
const order = new Models.Order()
order.id = 'TEST-1234'
order.currency = 'HNL'
order.amount = '1'
order.customer_name = 'Jhon Doe'
order.customer_email = 'jhondow@pixel.hn'

// Creación del objeto Card
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creación del objeto Billing
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Se instancia el request de AuthTransaction que es el que realiza la autorización
const auth = new Requests.AuthTransaction()
auth.setCard(card)
auth.setBilling(billing)
auth.setOrder(order)

// Se realiza la autorización con el método doAuth
service.doAuth(auth).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Ejemplo de respuesta exitosa

Como ejemplo se colocó el valor "1" en el campo 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_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": "00000394",
    "transaction_merchant": " 0000004959",
    "installment_type": null,
    "installment_months": null,
    "response_reason": "Transacción completada exitosamente",
    "payment_uuid": "PT-f01cd711-1707-4fe9-afd6-c92a87523a9f",
    "payment_hash": "22265408aab8377c33ff6b9122e59e70"
}

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

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.

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

//Se instancia el request de CaptureTransaction
const capture = new Requests.CaptureTransaction()
capture.payment_uuid = 'P-f01cd711-1707-4fe9-afd6-c92a87523a9f'
capture.transaction_approved_amount = '1'

//Se realiza la captura con el método doCapture
service.doCapture(capture).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

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 necesitas:

  • payment_uuid: el identificador único del pago
  • void_reason: texto descriptivo de la razón para anular el pago

Adicionalmente, para la autenticación de anulación necesitas:

  • auth_user: SHA-512 del correo del usuario autenticado para anular
  • void_signature: firma de autenticación para la anulación

Para realizar la autenticación de anulación en el ambiente sandbox, puedes utilizar los siguientes valores de prueba:

Nombre Valor
auth_user sandbox@pixel.hn
secret key @s4ndb0x-abcd-1234-n1l4-p1x3l

Puedes ver como generar la firma de anulación aquí.

Ejemplo una anulación

Es necesario establecer el parámetro auth_user utilizando el método setupPlatformUser del modelo Settings con el valor SHA-512 del correo electrónico del usuario autorizado para poder anular cobros.

 
// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()
settings.setupPlatformUser("aa7dc0e429aec1bdb4222680f9f0f17ace43d72c11b8d047ba207d12bb73ff2123e98fe56fd5e5b6cee103cd3e2704e60ea70ff2cafcdca43c50880b31ad8e9d")

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

//Instanciar el request de VoidTransaction
const voidTransaction = new Requests.VoidTransaction()
voidTransaction.payment_uuid = 'P-f01cd711-1707-4fe9-afd6-c92a87523a9f'
voidTransaction.void_reason = 'Transaction Test'
voidTransaction.void_signature = '8a944906...777ffae7'

//Se realiza la anulación con el método doVoid
service.doVoid(voidTransaction).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

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": "00000394",
    "transaction_merchant": " 0000004959",
    "installment_type": null,
    "installment_months": 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.

Ejemplo para tokenizar una tarjeta

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Tokenization
const service = new Services.Tokenization(settings)

//Se instancia el request de CardTokenization
const cardRequest = new Requests.CardTokenization()

// Creación del objeto Card
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creación del objeto Billing
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

cardRequest.setCard(card)
cardRequest.setBilling(billing)

// Se realiza la tokenización con el método vaultCard
service.vaultCard(cardRequest).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "status": "active",
    "mask": "411111******1111",
    "network": "visa",
    "type": "CREDIT",
    "bin": "411111",
    "last": "1111",
    "hash": "33fa2660f8e7c3556b72a3da1f375d535c3f00250b4af18777f950a40c7fcc1489d7c7879a73366f39ef23dfd210b6d74d98d1ec2db63b1797565a38e76bd239",
    "address": "Calle 1",
    "country": "HN",
    "state": "HN-CR",
    "city": "San Pedro Sula",
    "phone": "999-999999999",
    "token": "T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6"
  },
  "status": 200
}

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 solo se necesita el token de la tarjeta.

Ejemplo de como obtener la información de una tarjeta tokenizada

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Tokenization
const service = new Services.Tokenization(settings)

// Si se requiere conocer la información de una sola tarjeta
service.showCard('T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6').then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

// Si se requiere conocer la información de varias tarjetas, se puede enviar un array de tokens
const tokens = ['T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6', 'T-05c3f5ec-1c48-4818-af59-ea8da1dba000']
service.showCards(tokens).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

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

Para actualizar la información de una tarjeta, 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.

Ejemplo para actualizar la información de una tarjeta

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Tokenization
const service = new Services.Tokenization(settings)

// Se instancia el request de CardTokenization
const cardRequest = new Requests.CardTokenization()

// Creación del objeto Card
const card = new Models.Card()

// Enviar solo la propiedad que se quiere actualizar
card.number = '4111111111111111'
card.cvv2 = '999'

cardRequest.setCard(card)

// Se envia el TOKEN de la tarjeta a editar y los campos a editar
service.updateCard('T-77d49af9-132d-41a3-97ce-b38a74e608be', cardRequest).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

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 método, podremos eliminar una tarjeta utilizando el token que recibimos al momento de almacenarla.

Ejemplo del request

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Tokenization
const service = new Services.Tokenization(settings)

//Se envia el TOKEN de la tarjeta a eliminar al método deleteCard
service.deleteCard('T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6').then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "token": "T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6",
    "deleted": true
  }
}

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

Programas de lealtad

Para realizar una venta o cobro directo con financiamiento en el ambiente Sandbox, debes agregar al objeto de transacción (Sale) el método setInstallment indicando el número de meses y extra o intra como tipo de financiamiento.

Realizar una venta directa

// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

// Creación del objeto Order
const order = new Models.Order()
order.id = 'TEST-1234'
order.currency = 'HNL'
order.amount = '1'
order.customer_name = 'Jhon Doe'
order.customer_email = 'jhondow@pixel.hn'

// Creación del objeto Card
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creación del objeto Billing
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Se instancia el request de SaleTransaction que es el que realiza la transaccion
const sale = new Requests.SaleTransaction()
sale.setCard(card)
sale.setBilling(billing)
sale.setOrder(order)
// Se llama al método para indicar los meses y el tipo de financiamiento
sale.setInstallment(9, "intra");

// Se realiza la transacción don el método doSale
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

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

Realizar una venta directa con token de tarjeta


// Setear el ambiente Sandbox dentro del SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Se instancia el servicio de Transaction
const service = new Services.Transaction(settings)

// Creación del objeto Order
const order = new Models.Order()
order.id = 'TEST-1234'
order.currency = 'HNL'
order.amount = "1"
order.customer_name = 'Jhon Doe'
order.customer_email = 'jhondow@pixel.hn'

// Se instancia el request de SaleTransaction que es el que realiza la transaccion
const sale = new Requests.SaleTransaction()
sale.setOrder(order)

// Aqui se setea el token de la tarjeta, no es necesario enviar el objeto card ni el objeto billing
sale.setCardToken("T-6611b606-8ca6-4097-8584-4bc816b8612b")

// Se llama al método para indicar los meses y el tipo de financiamiento
sale.setInstallment(36, "extra");

// Se realiza la transacción don el método doSale
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Ejemplo de respuesta exitosa

Como ejemplo se colocó el valor "1" en el campo 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": "00000394",
    "transaction_merchant": " 0000004959",
    "installment_type": "extra",
    "installment_months": "36",
    "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 amount para así obtener diferentes respuestas según sea tu necesidad. Ver casos de prueba

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.