Use Cases via API

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 API

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

Route to send parameters for a Direct Sale

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

The request must include the headers specified in Installation

Field Index

All fields must be sent as parameters in the https query in Query String format or include content-type: x-www-form-urlencoded in the header.

Field Value Validation Description
order_id Alphanumeric Required Number or unique identifier of the order or payment
order_currency USD/HNL/NIO Required, 3 characters, uppercase Currency in which the payment will be made
order_amount 0.00 required, double Total amount of the collection in currency, within the sandbox the amount works to choose the type of transaction that you want to execute, see use cases
customer_name Short text Required, min:3, max:120 Client's full name
customer_email user@domain.com Required Client's main address
billing_address Short text Required Client's main address
billing_state Short text Required State code according to ISO 3166 ALPHA-2 standard
billing_country Short text Required, min: 3, max: 15 Cardholder country code
billing_zip Short text Not required The postal code field is not required, however, if it is sent, an evaluation will be carried out to confirm the format of the postal code corresponding to the Country. Check the list of countries where the format evaluation does not apply by clicking here.
billing_phone Numeric Required Customer phone
card_number Numeric Required, min:16 max: 16 Card number.
card_holder Short text Required, min:3, max:120 Cardholder name
card_cvv Numeric Required, min: 3, max: 4 Card cvv number
card_expire Numeric Required, min: 4, max: 4 Card expiration date in YY/MM format
card_token UUID Optional Token of a tokenized card
order_callback https://... Optional, URL Asynchronous URL (equivalent to WebHook) success
env Alphanumeric Optional Required field within the sandbox environment, the value must be: sandbox
lang es or en Optional Language code that the sandbox will use, by default es for Spanish

Request Example

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

// Data sent in POST request

// Example sending the card's data
{
  "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"
}

// Example using a tokenized card
{
  "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"
}

Request example using Postman

Example sale Postman

Remember that the cards allowed in the Sandbox are numbers 4111111111111111 and 5555555555554444.

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

To authorize a payment,the same steps as a direct sale must be followed. The required fields are the same, with the exception that the request will be sent to a different URL.

Similar to a direct sale, an authorization transaction can be executed with a credit / debit card or with a tokenized card.

Route to send parameters for a Payment Authorization

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

The request must include the headers specified in Installation

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_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
}

Save the payment_uuid, since it is needed to perform the Payment Capture.

Payment Capture

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

Route to send parameters for a Payment Capture

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

The request must include the headers specified in Installation

Field Index

Field Value Validation Description
transaction_approved_amount Numeric Required Amount of the transaction that will be captured, in case of Sandbox, the amount is 1.
payment_uuid UUID Required Unique identifier of the payment.
env Alphanumeric Optional Required field within the sandbox environment, the value must be: sandbox.

Request Example

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

// Data sent
{
  "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
  "transaction_approved_amount": 1,
  "env":"sandbox"
}

Request example using Postman

Example capture Postman

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
}

Void 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.

Route to send parameters for a Void Payment

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

The request must be made with the Headers specified in installation. It is also necessary to add the x-auth-user header with the SHA-512 value of the authorized user's email to void transactions.

Field Index

Field Value Validation Description
void_reason Text Required Reason or reason for cancellation of payment
payment_uuid UUID Required Unique identifier of the payment
env Alphanumeric Optional Required field within the sandbox environment, the value must be: sandbox

Request Example

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

// Data sent on headers
x-auth-user: aa7dc0e429aec1bdb4222680f9f0f17ace43d72c11b8d047ba207d12bb73ff2123e98fe56fd5e5b6cee103cd3e2704e60ea70ff2cafcdca43c50880b31ad8e9d

// Data sent on body
{
  "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
  "env": "sandbox",
  "void_reason": "Test de anulación",
  "void_signature": "8a944906...777ffae7"
}

Request example using Postman

Example void transaction Postman

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

Checking a Payment's Status

To check payment's status you need:

  • payment_uuid: Unique identifier of the payment

Route to send parameters for payment status check

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

The request must be made with the Headers specified in installation.

Field Index

Field Value Validation Description
payment_uuid UUID Required Unique identifier of the payment
env Alphanumeric Optional Required field within the sandbox environment, the value must be: sandbox

Request Example

// Request Route
// https://pixel-pay.com/api/v2/transaction/status

// Data sent on body
{
  "payment_uuid": "P-64e99e48-c695-4f7d-abbc-000000000000",
  "env": "sandbox"
}

Request example using Postman

Example check payment status Postman

Succesful Response Example

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
      "status": "paid",
      "attemps": 1,
      "history": {
        "2024-09-10": [
          {
              "time": "2024-09-10 21:17:11",
              "label": "El cobro fue creado",
              "color": "teal"
          },
          {
              "time": "2024-09-10 21:17:11",
              "label": "Pago procesado",
              "color": "success",
              "fields": [
                  {
                      "title": "Card",
                      "description": "411111 •••••• 1111",
                      "icon": "icon-card-visa"
                  },
                  {
                      "title": "Device",
                      "description": "Mac OS X 10.15.7, Safari 537.36",
                      "icon": "mac"
                  }
              ]
          }
        ]
      }
  }
}

Card Tokenization

You can also safely store card via Tokenization and use them in Sandbox.

Route to send parameters for a Card Tokenization

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

The request must include the headers specified in Installation

Field Index

Field Required Value Description
cvv2 Yes 3-digit numeric Security code found on the back of the card and contains 3 or 4 digits
number Yes 15 or 16 digit numeric 15 or 16 numbers from the front of the card
expire_month Yes 2-digit numeric Card expiration month
expire_year Yes 4-digit numeric Card expiration year
cardholder Yes String Cardholder name
address Yes String Cardholder Address
city Yes String Cardholder City
country Yes String(2) ISO 3166 ALPHA-2 Cardholder country code
state Yes Country code and state code eg. HN-CR Cardholder Status
zip No 5-digit numeric Cardholder ZIP Code
phone Yes 7 to 15 digits numeric Cardholder number
client No Token Token obtained when creating a customer
email No Alphanumeric Mailing address
env No Alphanumeric Required field within the sandbox environment, the value must be: sandbox
lang es or en Optional Language code that the sandbox will use, by default es for Spanish

Request Example

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

// Data sent
{
  "cvv2": "123",
  "number": 5555555555554444,
  "expire_month": "12",
  "expire_year": "2020",
  "cardholder": "Juan Perez",
  "address": "Holstein 109-57",
  "country": "HN",
  "city": "San Pedro Sula",
  "state": "CR",
  "zip": "21102",
  "phone": "95852921",
  "lang": "es",
  "env":"sandbox"
}

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

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

Get Card Info

Route to send parameters for a Card Information Retrieval

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

The request must include the headers specified in Installation

Field Index

Field Required Value Description
token Yes Alphanumeric It is the token that was obtained by tokenizing a card previously
env Yes Alphanumeric Required field within the sandbox environment, the value must be: sandbox

Request Example

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

// Data sent

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

{
  "env": "sandbox"
}

Request example using Postman

Example get tokenization card Postman

Succesful 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

Through this request the information of a card can be updated using the same fields that were used when storing it. The card's token must be included in the Request Route as shown below.

Route to send parameters for a Card Information Update

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

The request must include the headers specified in Installation

Field Index

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.

Request Example

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

// Data Sent

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

Request example using Postman

Example update card Postman

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

It is possible to delete a card using the token received when first storing it.

Route to send parameters for a Card Deletion

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

The request must include the headers specified in Installation

Request Example

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

// Data Sent

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

{
  "env": "sandbox"
}

Request example using Postman

Example delete card Postman

Succesful Response Example

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

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

Financing installments

Route to send parameters for a Direct Sale

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

The request must include the headers specified in Installation

Field Index

All fields must be sent as parameters in the https query in Query String format or include content-type: x-www-form-urlencoded in the header.

Field Value Validation Description
order_id Alphanumeric Required Number or unique identifier of the order or payment
order_currency USD/HNL/NIO Required, 3 characters, uppercase Currency in which the payment will be made
order_amount 0.00 required, double Total amount of the collection in currency, within the sandbox the amount works to choose the type of transaction that you want to execute, see use cases
customer_name Short text Required, min:3, max:120 Client's full name
customer_email user@domain.com Required Client's main address
billing_address Short text Required Client's main address
billing_state Short text Required State code according to ISO 3166 ALPHA-2 standard
billing_country Short text Required, min: 3, max: 15 Cardholder country code
billing_zip Short text Not required The postal code field is not required, however, if it is sent, an evaluation will be carried out to confirm the format of the postal code corresponding to the Country. Check the list of countries where the format evaluation does not apply by clicking here.
billing_phone Numeric Required Customer phone
card_number Numeric Required, min:16 max: 16 Card number.
card_holder Short text Required, min:3, max:120 Cardholder name
card_cvv Numeric Required, min: 3, max: 4 Card cvv number
card_expire Numeric Required, min: 4, max: 4 Card expiration date in YY/MM format
card_token UUID Optional Token of a tokenized card
installment_type intra or extra Required Installment type
installment_months Numeric Required Number of months of installment
order_callback https://... Optional, URL Asynchronous URL (equivalent to WebHook) success
env Alphanumeric Optional Required field within the sandbox environment, the value must be: sandbox
lang es or en Optional Language code that the sandbox will use, by default es for Spanish

Request Example

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

// Data sent in POST request

// Example sending the card's data
{
  "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",
  "installment_type": "intra",
  "installment_months": "3",
  "env": "sandbox",
  "lang": "es"
}

// Example using a tokenized card
{
  "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",
  "installment_type": "intra",
  "installment_months": "3",
  "env": "sandbox",
  "lang": "es"
}

Request example using Postman

Example sale Postman

Remember that the cards allowed in the Sandbox are numbers 4111111111111111 and 5555555555554444.

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_redeemed_points": 0,
    "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": "0823",
    "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": "intra",
    "installment_months": "3",
    "response_reason": "Transacción completada exitosamente",
    "payment_uuid": "S-6a48a4c4-8e3b-409a-aa72-fdf5b9aac57b",
    "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.