Use Cases via SDK

Intro

This section brings together all the previously mentioned scenarios showcasing the most common cases that a merchant could face using the PixelPay Sandbox.

Use Cases via SDK

Payments are a safe way to pay for goods or services using PixelPay, without being redirected to another website or having to see the payment modal.

There are two ways to make a payment:

  • By sending the order, card information, and billing address.
  • By sending the order data and the token of the tokenized card.

Create Payment / Direct Sale

In order to start making a sale or direct payment in the Sandbox environment, you must first instantiate the SDK as shown in installation.

Direct Sale

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Transaction service 
const service = new Services.Transaction(settings)

// Creating Order object
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'

// Creating Card object
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creating Billing object
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Setting request SaleTransaction which is the one that actually executes the sale.
const sale = new Requests.SaleTransaction()
sale.setCard(card)
sale.setBilling(billing)
sale.setOrder(order)

// Execution of the Sale.
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

The permitted testing cards within the Sandbox environment are 4111111111111111 and 5555555555554444.

Direct Sale with a Tokenized Card


// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting Transaction Service
const service = new Services.Transaction(settings)

// Creating Order object
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'

// Setting request SaleTransaction which is the one that actually executes the sale.
const sale = new Requests.SaleTransaction()
sale.setOrder(order)

// Setting the card token
sale.setCardToken("T-6611b606-8ca6-4097-8584-4bc816b8612b")

// Execution of the Sale.
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Succesful Response Example

For example purposes, the value "1" was assigned to the amount field, forcing a succesful response.

{
  "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"
  }
}

You can assign different amount values for testing purposes. Each amount value return a specific type of response. See Test Cases

Payment Authorization

In order to make a Payment Authorization in the Sandbox environment, you must first instantiate the SDK as shown in installation.

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting Transaction Service
const service = new Services.Transaction(settings)

// Creating Order object
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'

// Creating Card object
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creating Billing object
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Setting request AuthTransaction which is the one that actually executes the authorization of the payment.
const auth = new Requests.AuthTransaction()
auth.setCard(card)
auth.setBilling(billing)
auth.setOrder(order)

// Execute the Authorization
service.doAuth(auth).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Succesful Response Example

For example purposes, the value "1" was assigned to the amount field, forcing a succesful response.

{
  "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"
  }
}

You can assign different amount values for testing purposes. Each amount value return a specific type of response. See Test Cases

Payment Capture

To capture a payment, only the payment's UUID and the amount to be captured are needed, since the request is made to a payment that was previously authorized.

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting Transaction Service
const service = new Services.Transaction(settings)

// Setting request CaptureTransaction which is the one that actually executes the authorization of the payment.
const capture = new Requests.CaptureTransaction()
capture.payment_uuid = 'P-f01cd711-1707-4fe9-afd6-c92a87523a9f'
capture.transaction_approved_amount = '1'

// Execute the Caoture
service.doCapture(capture).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Succesful Response Example

{
  "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
}

Cancelling a Payment

To cancel a payment you need:

  • payment_uuid: the unique identifier of the payment
  • void_reason: descriptive text of the reason to void the payment

Additionally, for override authentication you need:

  • auth_user: SHA-512 of the authenticated user's email that can void payments
  • void_signature: authentication signature for voiding

To perform the void authentication in the sandbox environment, you can use the following test values:

Name Value
auth_user sandbox@pixel.hn
secret key @s4ndb0x-abcd-1234-n1l4-p1x3l

You can see how to generate the override signature here.

Your Settings Model must be correctly set up in order to cancel transactions. Read further about the Settings Model configuartion [here] (/docs/en/sdk/models#settings).

Void Transaction Example

It is necessary to set the auth_user parameter using the setupPlatformUser method of the Settings model to the SHA-512 value of the authorized user's email in order to void transactions.

 
// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()
settings.setupPlatformUser("aa7dc0e429aec1bdb4222680f9f0f17ace43d72c11b8d047ba207d12bb73ff2123e98fe56fd5e5b6cee103cd3e2704e60ea70ff2cafcdca43c50880b31ad8e9d")

// Setting Transaction Service
const service = new Services.Transaction(settings)

// Setting request voidTransaction which is the one that actually executes the cancellation of the payment.
const voidTransaction = new Requests.VoidTransaction()
voidTransaction.payment_uuid = 'P-f01cd711-1707-4fe9-afd6-c92a87523a9f'
voidTransaction.void_reason = 'Transaction Test'
voidTransaction.void_signature = '8a944906...777ffae7'

// Execute the Cancellation
service.doVoid(voidTransaction).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Success Response Example

{
  "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"
  }
}

Card Tokenization

The PixelPay Sandbox also supports transactions using a tokenized card.

Example of Card Tokenization

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting the Tokenization Service
const service = new Services.Tokenization(settings)

// Setting CardTokenization request
const cardRequest = new Requests.CardTokenization()

// Creating Card object
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creating Billing object
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)

// Executing the tokenization
service.vaultCard(cardRequest).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Success Response Example

{
  "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
}

You must save the card's token for it will not be available in the future.

Get Card Info

To retrieve a card's information, only the card's token is necessary.

Retrieving a Card's Information Example

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting the Tokenization Service
const service = new Services.Tokenization(settings)

// If only one card's information needs to be retrieved.
service.showCard('T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6').then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

// If a list of card's information needs to be retrieved
const tokens = ['T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6', 'T-05c3f5ec-1c48-4818-af59-ea8da1dba000']
service.showCards(tokens).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Successful Response Example

{
  "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"
  }
}

Update Card

In most cases, to update the information of a card, only the fields that need to be updated should be sent. However, there are a few exceptions. For example, if the CVV value must be updated, it is also necessary to send the card number. Or, if the status code must be updated, it is also necessary to send the country code.

Ejemplo para actualizar la información de una tarjeta

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting the Tokenization Service
const service = new Services.Tokenization(settings)

// Setting CardTokenization request
const cardRequest = new Requests.CardTokenization()

// Creating Card object
const card = new Models.Card()

// Set only the properties that are to be updated.
card.number = '4111111111111111'
card.cvv2 = '999'

cardRequest.setCard(card)

// Send the card token and the data to update.
service.updateCard('T-77d49af9-132d-41a3-97ce-b38a74e608be', cardRequest).then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Succesful Response Example

{
  "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"
  }
}

Delete Card

Through this method, it is possible to delete a card using the token received when first storing it.

Card Deletion Example

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting the Tokenization Service
const service = new Services.Tokenization(settings)

// Send the card token.
service.deleteCard('T-05c3f5ec-1c48-4818-af59-ea8da1dba8d6').then( response => {
  // SUCCESS
}).catch( err => {
  // ERROR
})

Succesful Response Example

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

Card tokens created in the Sandbox are automatically deleted 5 hours after being created.

Financing installments

To make a sale or direct payment with installment in the Sandbox environment, you must add to the transaction object (Sale) the setInstallment method specifying the number of months and extra or intra as the type of installment.

Direct Sale

// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Transaction service 
const service = new Services.Transaction(settings)

// Creating Order object
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'

// Creating Card object
const card = new Models.Card()
card.number = '4111111111111111'
card.cardholder = 'Jonh Doe'
card.expire_month = '12'
card.expire_year = '23'
card.cvv2 = '999'

// Creating Billing object
const billing = new Models.Billing()
billing.address = 'Ave Circunvalacion'
billing.country = 'HN'
billing.state = 'HN-CR'
billing.city = 'San Pedro Sula'
billing.phone = '99999999'

// Setting request SaleTransaction which is the one that actually executes the sale.
const sale = new Requests.SaleTransaction()
sale.setCard(card)
sale.setBilling(billing)
sale.setOrder(order)
// The method is called to indicate the months and the type of installment.
sale.setInstallment(9, "intra");

// Execution of the Sale.
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

The permitted testing cards within the Sandbox environment are 4111111111111111 and 5555555555554444.

Direct Sale with a Tokenized Card


// Setting SandBox environment within the SDK
const settings = new Models.Settings()
settings.setupSandbox()

// Setting Transaction Service
const service = new Services.Transaction(settings)

// Creating Order object
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'

// Setting request SaleTransaction which is the one that actually executes the sale.
const sale = new Requests.SaleTransaction()
sale.setOrder(order)

// Setting the card token
sale.setCardToken("T-6611b606-8ca6-4097-8584-4bc816b8612b")

// The method is called to indicate the months and the type of installment.
sale.setInstallment(9, "intra");

// Execution of the Sale.
service.doSale(sale).then(response => {
  // SUCCESS
}).catch(err => {
  // ERROR
})

Succesful Response Example

For example purposes, the value "1" was assigned to the amount field, forcing a succesful response.

{
  "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"
  }
}

You can assign different amount values for testing purposes. Each amount value return a specific type of response. See Test Cases

Countries where it is not necessary to send the Postal Code

In the countries listed below, an evaluation of the postal code format is not performed.

Angola, Bahamas, Belize, Benin, Bolivia, Botswana, Burkina Faso, Burundi, Cameroon, Comoros, Republic of Congo, Democratic Republic of Congo, North Korea, Ivory Coast, Dominica, UAE, Eritrea, Fiji, Gabon, Gambia, Ghana, Grenada, Equatorial Guinea, Guyana, Honduras, Ireland, Cook Islands, Solomon Islands, Kiribati, Malawi, Mali, Mauritania, Namibia, Nauru, Niue, Panama, Qatar, Central African Republic, Rwanda, St. Christopher and Snows, Santa Lucia, Sao Tome and Principe, Seychelles, Sierra Leone, Syria, Somalia, Suriname, Tanzania, East Timor, Togo, Tokelau, Tonga, Trinidad and Tobago, Tuvalu, Uganda, Vanuatu, Yemen, Djibouti, Zimbabwe, Bouvet Island.

All SDKs include the list of countries and states with all the necessary data. Click here for further information.