Hosted Payment Gateway – PixelPay

ℹ️ In the following link, PixelPay provides SDK's in different
technologies to facilitate merchant integration: 
https://docs.pixelpay.app/docs/en/introduction

PixelPay's Hosted Payment API is a simple way to integrate payments into Mobile and Web Apps. The method used is for redirection.

1. Requirements and Preparation
To get started, you need to have access to an account with API Settings permissions or be the account administrator.

Note that you can use this integration in any code language that supports HTTP/S queries or implement a library capable of using a Requestand Responsetype instance.

2. Key removal
In order to do this integration, you will need to obtain the Key ID from your PixelPay platform, which will be used later in the_key field.

2.1. Key ID field
TheKey ID field is a number that uniquely identifies the merchant and is a constant value, it cannot be changed.

In order to extract the Key ID value, log in to the web platform and navigate in the left side menu to Preferences 〉API Options. There you will find the field called Key ID.

Note: If you want to run it in our SandBox environment, you can find the key here.

Opciones de API.png

Image 1: Key ID in API Options. https://www.pixelpay.app/admin/settings/app

In the following links you will find more information about:
- Log in:
https://pixelpay.zendesk.com/hc/es-419/articles/360041553012
- Extract Key ID in API Options:
https://www.pixelpay.app/admin/settings/app
- Run in SandBox environment:
https://pixelpay.zendesk.com/hc/es-419/articles/360043039752-SandBox#ref-llavesSandBox

3. Field Index
All fields must be sent as parameters in the HTTPSquery in Query String format or included in the header format type content-type: x-www-form-urlencoded.

The fields to be used are:

Field	Value	Validation	Description
`_key *`	00000000	Required, alphanumeric	Merchant key (API options)
`_callback`	https://...	Optional, URL	Asynchronous URL (equivalent to the WebHook) for success (see details)
`_cancel *`	http(s)://...	Required, URL	Redirect URL for return or cancellation (see details)
`_complete *`	https://...	Required, URL	Redirect URL for successful payment (see details)
`_order_id *`	Alphanumeric	Required	Unique order or payment number or identifier
`_order_date`	dd-mm-aa hh:mm	Optional, timestamp	Date and time the order was generated
`_order_content`	base64-json	Optional, array of objects	Codification of a JSON String a base64 (see structure content)
`_order_extras`	base64-json	Optional, array objects	Codification of a JSON String a base64
`_currency`	USD/HNL	Optional, size:3, uppercase	Currency in which the payment will be made
`_tax_amount`	0.00	Optional, double	Total tax amount in currency
`_shipping_amount`	0.00	Optional, double	Total shipping value amount in currency
`_amount *`	0.00	Required, double	Total charge amount in currency
`_first_name *`	Texto corto	Required, min:3, max:120	Customer name
`_last_name *`	Texto corto	Required, min:2, max:120	Last name of the customer
`_email *`	usuario@dominio.com	Required, email	Customer's email address
`_address`	Texto corto	Optional	Primary address of the customer (first line)
`_address_alt`	Texto corto	Optional	Alternate address of the customer (second line)
`_zip`	00000	Optional	ZIP address code
`_city`	Texto corto	Optional, min:3, max:120	City name of the customer
`_state`	Texto corto	Optional, min:3, max:120	Name or code of the state/department of the customer
`_country`	Texto corto	Optional, min:3, max:120	Name or code of the country of the customer
`expired_at`	yyyy/mm/dd hh:mm	Optional, date	Payment expiration date
`json`	true/false	Optional, booleano	Include in case of switching to JSON mode in responses

*Campos requeridos

3.1. Route details
Route for sending parameters:
https://{endpoint}/api/v2/transaction/hosted/other GET/POST

Route for sending parameters in a SandBox environment:
https://{endpoint}/api/v2/transaction/hosted/sandbox GET/POST

Where do I find the DOMAIN that corresponds to me?

It is highly recommended to use the POST method to send parameters to this route. There are two types of request responses: JSONand HTML.

HTML responses (default) visually respond to all content in case of a validation error. Otherwise, a redirection will be made to the collection generated ready to be paid.

The JSON responses will return the status in the successkey and the errors in the errors:{}key. If there is no error, the Collection URL will be returned in the url key.

Example • Success response

{
  "success": true,
  "url": "https://www.pixelpay.app/.../checkout"
}

Example • Error response

{
  "success": false,
  "errors" : {
    "_first_name": [
      "El campo first name es obligatorio."
    ],
    ...
  }

The link explains in detail how to find the domain that corresponds to you:
https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles#ref-domain

3.2. References
3.2.1. Base64-JSON element
In order to encode a JSON value (single quotes or unquoted keys are not allowed), it must be converted to astring. As an example we will take this structure:

[{
  "nombre":"Pedro Perez",
  "nro_cliente" : "719827834",
  "nro_id" : "0501-1988-00237",
  "ciudad" : "San Pedro Sula"
}]

After converting these values to string, they must be encoded to Base64 to obtain a result like this:

ew0KCSJub21icmUiOiJQZWRybyBQZXJleiIsDQoJIm5yb19jbGllbnRlIiA6ICI3MTk4Mjc4MzQiLA0KCSJucm9faWQiIDogIjA1MDEtMTk4OC0wMDIzNyIsDQoJImNpdWRhZCIgOiAiU2FuIFBl ZHJvIFN1bGEiDQp9

Many times this string of characters contains values that do not fit with a correct encoding in a URL, so it is advisable to URL encode it.

Example • PHP

$obj_array = array(
  "nombre" => "Pedro Perez",
  "nro_cliente" => "719827834",
  "nro_id" => "0501-1988-00237",
  "ciudad" => "San Pedro Sula"
);
$json = json_encode($obj_array);
$base64 = base64_encode($json);
$order_extras = urlencode($base64);

Example • Javascript

var obj_array = {
  "nombre":"Pedro Perez",
  "nro_cliente" : "719827834",
  "nro_id" : "0501-1988-00237",
  "ciudad" : "San Pedro Sula"
};
var json = JSON.stringify(obj_array);
var base64 = window.btoa(json);
var order_extras = encodeURI(base64);

3.3._contentfield structure
The_contentfield contains a detailed arrangement of each element of the order. Below we will show the fields of each element:

Campo	Valor	Validación	Descripción
`title *`	Texto corto	required, min:3, max:60	Product/invoice title
`code`	[A-z][0-9]	optional	Product/invoice code or number
`price *`	0.00	required, double	Unit price
`qty *`	1 ... n	required, int, unsigned	Quantity of items
`tax`	0.00	optional, double	Tax amount per item unit
`total *`	0.00	required, double	Total before tax for the product x quantity in currency

*Campos requeridos

Example • Elements of an order

[
  {
    "code" : "0000123",
    "title" : "Camiseta Roja",
    "description" : "Talla: XS",
    "tax" : 9.99,
    "price" : 99.99,
    "qty" : 1,
    "total" : 9.99
  },
  {
    "code" : "0000123",
    "title" : "Jeans Pepe",
    "description" : "Talla: 32",
    "tax" : 0.00,
    "price" : 123.99,
    "qty" : 1,
    "total" : 123.99
  },
  ...
]

3.4. URL details_complete

The_completefield URL will be executed (redirect) when the end customer has successfully made the payment. The request is of type GET.

The URL when executed will contain one more parameter called paymentHash, which will allow the origin of the transaction to be compared and validated. The content of this parameter is an md5hash.

Example of a _complete URL:

https://myshop.com/orden/finalizar

Example of the same _complete URL running:

https://myshop.com/orden/finalizar?paymentHash=d2e16e6ef52a45b7468f1da56bba1953

The paymentHash parameter will be concatenated with the current URL. If the URL already contains parameters, it will be processed before being executed and there will be no conflict.

3.4.1. Comparison of paymentHashlocally and remotely
In order to compare thepaymentHashand verify that the transaction is real we will need 3 elements:_order_id, Key ID y Secret Key hashed with MD5 (extract keys).

We will concatenate the 3 elements with the symbol |between each one in the following order: _order_id|Key ID|Secret Key Hashed with MD5. Below we will see an example of the result:

"00000123|7812290000|82722502afb99875524ca8e9b1fb871a"

To finish the validation, we will convert the concatenated value to an md5 hash and proceed to compare it with the paymentHash parameter. If both hashes are the same, (hash remoto == hash local) URLs_complete is valid.

3.5._callbackURL details

The_callbackfield URL will be executed asynchronously each time a charge has been successfully paid. The request is of type POST and its content is content-type: application/json.

The remote URL should return a code 200 response to indicate that the content was captured.

In case of a different response code, or no response from the remote URL, the data sending will be rescheduled with a delay of 5 min. and a maximum of 3 attempts per shipment.

Example •_callbackJSON response:

{
  "ref": "00012101-AB-2021-01-13",
  "uuid": "q1AW67ODkz",
  "status": "paid",
  "description": "Pago de Orden #AB-2021-01-13",
  "note": null,
  "category": "other",
  "currency": "HNL",
  "tax_amount": 0,
  "amount": 1,
  "items": [
    {
      "title": "Pago de Orden AB20210113",
      "tax": 0,
      "price": 1,
      "qty": 1,
      "total": 1
    }
  ],
  "customer_name": "John Doe",
  "customer_email": "carlos@pixel.hn",
  "customer_phone": "99999999",
  "client_ip": null,
  "client_device": "mac",
  "order": "AB-2021-01-13",
  "payment_hash": "3e04fad9a503607a3ebf77532b1af94a",
  "billing_address": "Ave Circunvalacion",
  "billing_state": "CR",
  "billing_city": "San Pedro Sula",
  "billing_country": "HN",
  "billing_zip": "",
  "created_at": "2021-01-13 11:01:14",
  "paid_at": "2021-01-13 11:01:18",
  "transaction_id": "6105591372046292904011",
  "card_account": "4234 •••• •••• 1234",
  "card_brand": "visa",
  "card_type": "CREDIT",
  "company_name": "My Company,
  "company_slug": "my-company",
  "company_key": "2212294583",
  "is_overdue": false,
  "payment_url": "https://www.pixelpay.app/my_company/1dab5ed0/checkout",
  "attach_url": null,
  "extra": { 
      "codigoCliente" : "4782164", 
      "codigoNegocio" : "ATGSH-6712", 
  }
}

If the transaction was carried out with a financing plan or points, the response will include three additional fields:

{
 ...
 "installment_type": "extra",
 "installment_months": "12",
 "points_redeem_amount": "100"
}

3.6._cancelURL details
The URL of the_cancel field will be executed (redirect) every time the end client clicks on the "cancel order and return" link, the request is of typeGET.

4. Route domain:
Log in to your PixelPay account and at the top, in the search bar, you will find the domain.

As we will see in the following image, our domain in this case is: pixelpay.app.

Image 2: Obtain domain.

Related articles