The PixelPay SDK allows you to simplify your PixelPay integrations in different types of environments.
The SDK contains objects and functions that provide an easy way to submit payment data and avoid redirection to the provider's website when completing the payment process.
This new version of the PixelPay SDK is a great evolution to the previous versions, it includes multiple improvements and contains all the necessary APIs standarized, and integrated in a single package.
As a good practice, all PixelPay SDK (except withAuthenticationRequest)functions should be called from the backend of the integration, sending the required data from the frontend if necessary.
One of the improvements of the SDK is that it follows a defined standard. It includes a variety of models, responses, entities, exceptions, services, and more, structured in a way that provides a frictionless experience for developers.
It is very important to know all the predefined classes and utilities included in the SDK in order to fully exploit their potential.
Models (defined as models within the SDK) provide predefined classes to facilitate interaction with PixelPay entities such as credit cards, orders, billing, delivery addresses, etc.
These include all the necessary definitions to cover most types of integration with PixelPay.
Within the models we can find:
Settings: SDK settings.Environment: values of different types of environments.Billing: billing information.Card: credit/debit cards.Item: all kinds of items for sale.Order: order data.Models are necessary, since they are the components that make up requests.
Requests are directives that take the required data from the models and convert it into a proper request that our system can interpret. An example of this would be converting an order with multiple items included to the proper JSON format.
The Requests section includes the necessary methods to create different transaction types:
SaleTransaction: Creates the request to carry out a direct sale.AuthTransaction: Creates the request to authorize a sale. Once the sale is authorized, the merchant can request the capture of the authorized funds through the SDK.CaptureTransaction: Creates the request to capture the funds from an authorized sale.VoidTransaction: Creates the request to cancel a sale.StatusTransaction: Creates the request to obtain the status of a transaction.CardTokenization: Creates the request to tokenize a credit/debit card.To use PixelPay Services, it is necessary to send the information through requests.
Services are in charge of all the communication between your integration and the PixelPay system. Services make it easy to build requests, which are then sent to the PixelPay servers for further processing.
The Services section includes:
Transaction: Allows the creation, authorization, capture, cancellation or status retrieval of all sales within the business.Tokenization: Allows the tokenization, update, deletion or retrieval of credit and debit cards within the affiliated company.Services generate the Requests to the PixelPay API, which is why they are of great importance.
Responses and entities provide additional information that can be of great aid to developers using the SDK, such as additional documentation in the form of IntelliSense (function parameter information, variables, and SDK modules).
The Responses section includes all the different types of Responses that can be obtained when making a query to the PixelPay services.
Response types can help a developer determine whether a transaction performed is succesful or not. If it is not successful, you can capture what type of error was generated. All response types are equivalent to one or more HTTP response codes.
| Response Type | HTTP Code | Description |
|---|---|---|
SuccessResponse |
200 |
Respuesta exitosa Successful response Possibly contains additional information in data. |
ErrorResponse |
400 |
General error by the client |
NoAccessResponse |
401, 403 |
Permissions and/or access error, the client does not have access to this resource. You may not have submitted the necessary credentials or your credentials have already expired. |
PaymentDeclinedResponse |
402 |
Payment was declined by the service. |
NotFoundResponse |
404, 405, 406 |
Resource not found. |
TimeoutResponse |
408 |
Server response time out. |
PreconditionalResponse |
412, 418 |
Error where the terms submitted by the client do not match the terms of service. |
InputErrorResponse |
422 |
Error in the entity sent by the client, where a validation failed in one or more sent fields. |
NetworkFailureResponse |
500 |
Communication failure with the service |
FailureResponse |
>500 or network failure |
Service Failure. |
Entities provide even more information about the type of response received from services.
All responses have a defined structure, such as a JSON format. For example, many successful transactions return a data property as a response. Entities help, depending on the type of service used, define in further detail what exactly this component contains.
The type of responses received when interacting with the PixelPay service has a defined format, depending on the type of response received from the service. Response types are defined here.
| Key | Type |
Description |
|---|---|---|
success |
boolean |
Defines if the request was executed successfully or not. |
message |
string |
Description of the response returned by the service. |
data |
object<string, any> |
Data returned by the service requests. Its content varies depending on the service requested. |
errors |
object<string, string[]> |
In case there are errors (for example, invalid values in a form), all the fields that caused the error are sent along with a descriptive error message for each field. |
Example of successful response
{
"success": true ,
"message": "Information obtained successfully" ,
"data": {
"status": "active" ,
"mask": "411111******1111" ,
"network": "visa" ,
"type": "CREDIT" ,
"bin": "4111111" ,
"last": "1111" ,
"hash": "33fa2660f8e7c3556b72a3da1f375d535c3f00250b4af18777f950a40c7fcc1489d7c7879a73366f39ef23dfd210b6d74d98d1ec2db63b1797565a38e76bd239" ,
"address": "Call 1" ,
"country": "HN" ,
"state": "HN-CR" ,
"city": "San Pedro Sula" ,
"phone": "999-999999999" ,
"token": "T-25ae86aa-d4f4-438f-8806-019575782fa0"
}
}Example of response with errors
{
"success": false ,
"message": "The number field is required." ,
"errors": {
"number": ["The number field is required."],
"cvv2": ["The cvv2 field is required."],
"expire_month": ["The expire month field is required."],
"expire_year": ["The expire year field is required."],
"cardholder": ["The cardholder field is required."],
"address": ["The address field is required."],
"country": ["The country field is required."],
"state": ["The department field is required."],
"city": ["The city field is required."],
"phone": ["The phone field is required."]
}
}The PixelPay SDK is available for different frameworks and platforms:
* Work in Progress
To use the PixelPay Sandbox with the SDK or via API, it is necessary to make an initial setup with the affiliated merchant's data, as shown below.
The necessary information to set the Sandbox up includes:
Through the SDK, you can set up different types of environments, mainly production and sandbox. The sandbox environment is useful for testing the integration with PixelPay. Once the tests are done and succesful, the environment can be changed to production.
Environment Types:
LIVE (production)SANDBOXTo use the SDK, it is necessary to extract the domain from the route (endpoint) and certain keys associated with the PixelPay platform merchant. This documentation shows how to extract this data.