API overview
Learn about the key features of the PXP API before you start integrating.
Introduction
The PXP API is a REST API that uses HTTP methods (POST
, GET
, etc.), returns standard HTTP status codes, communicates using JSON, and uses resource-based URLs.
Authentication
Each request to the PXP API must be authenticated using a Hash-Based Message Authentication Code (HMAC) with SHA-256. By using a shared secret key to create a unique hash of your message, HMAC-256 ensures that requests haven't been tampered with during transmission and confirms they genuinely came from an authorised sender.
Base URLs
When integrating with the PXP API, you'll work with two environments:
- A staging environment for application development and testing purposes.
- A production environment for live operations.
Each environment has its own base URL, which you'll need to specify in the endpoint URL when you send a request.
Environment | Base URL |
---|---|
Staging | https://api-services.test.pxpfinancial.com |
Production | https://api-services.pxpfinancial.com |
HTTP status codes
When you send a request to the PXP API, we return a response confirming that it was received and processed. The associated HTTP status code and message describe the outcome of this processing.
HTTP status code | HTTP status message | PXP status message | Description |
---|---|---|---|
200 | OK | Successfully Processed | The request was processed effectively, resulting in a variable response based on the request type and data requested. |
400 | Bad Request | Request Interpretation Error | The server couldn't decipher the request due to incorrect syntax. Errors should be corrected before reattempting the request. |
401 | Unauthorized | Authentication Needed | Access to the resource requires valid authentication credentials (username/password). |
403 | Forbidden | Access Denied | Access to the requested resource is denied due to insufficient permissions. Repeating the request is not advisable. |
404 | Not Found | Resource Unavailable | The requested resource was not found at the specified location and may or may not be available later. Often due to an incorrect URL. Subsequent attempts may be made. |
413 | Payload Too Large | Excessive Request Size | The request body exceeded the 10MB limit. Resend with a smaller payload size. |
422 | Unprocessable Entity | Semantic Request Error | The request is structurally correct but semantically incorrect, meaning it's readable but not understandable by the server. |
500 | Internal Server Error | Processing Failure | An unexpected issue on the server prevented request fulfillment. This may also occur due to incorrect request formatting, such as missing mandatory fields. |
Idempotency
Idempotency is a safety feature that prevents duplicate transactions from being processed when the same request is sent multiple times. For example, if you lose your network connection after sending a transaction request and retry as soon as you're reconnected. PXP will recognise the merchantTransactionId
and only process one of your requests. This means you can safely retry a transaction, without any risk of the customer being charged twice. The API will then either return the result of the original successful transaction or process the request if it truly failed the first time.
Merchant setups
During onboarding, we'll create a merchant group for you. The merchant group represents your legal entity and sits at the top level of your organisation's hierarchy.
Below the merchant group, you can create one or more merchants. For example, ACME UK.
For each merchant, you can have one or more sites. These can represent both physical or online locations. For example, the ACME London shop or acme.co.uk.
We'll automatically create merchant
and site
values that you'll need to supply for certain requests, such as initiating a transaction. You can find these in the Unity Portal in the General information tab of the relevant merchant or site.
Service catalogue
PXP offers a service catalogue that allows you to integrate with the specific services that best meet your business needs, whether used individually or in combination.
By default, all services are configured at the merchant group level. Some services allow you to override the merchant group settings at the merchant or site level.
Service name | Description | Merchant-level override | Site-level override |
---|---|---|---|
Basic service | Fundamental payment processing capabilities. | ||
BIN lookup service | Tool to identify and verify card issuer information based on bank identification numbers (BINs). | ||
Card service | Payment card processing and transaction management capabilities. | ||
POS service | Point of sale (POS) transaction processing and management functionality. | ||
ThreeD Secure (standalone) service | Additional security layer for online card transactions using the 3D Secure protocol. | ||
Token vault service | Secure storage and management of tokenised payment card data. |
Versioning
Each PXP API endpoint URL includes the version number for easy identification.
For example, version 1 of the Transactions API endpoint ishttps://api.pxpfinancial.net/api/v1/transactions
.
We aim to continuously improve our API and typically add new features without you needing to make any updates to your integration. These are known as non-breaking changes.
However, we sometimes need to introduce major changes that aren't backwards compatible. These are known as breaking changes. When this happens, we'll publish a new major version while maintaining support for the previous one. Your existing integration will continue to work without any disruptions, so you can perform an upgrade when suitable.
Webhooks
Webhook overrides
By default, webhooks are configured at the merchant group level. However, you can override these at the merchant level if needed.
Webhook retries
Occasionally, a webhook notification might fail to deliver. This could be because of a connection timeout occurring or a response taking too long. When this happens, we'll automatically retry the notification up to another 10 times in the 10 seconds following the initial delivery attempt.
IP addresses
Depending on your network and security requirements, you might need to add our network to your firewall's allowlist to receive webhook events from us.
To make sure you can communicate with our network, you can either:
- Use a domain allowlist: if your network configuration allows domain allowlisting, include our domain
out.pxpfinancial.com
. - Systematically resolve our IP addresses: perform a DNS lookup for
out.pxpfinancial.com
. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.
We don't provide a list of IP addresses because these can change over time. For example, due to ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded.
Updated about 1 month ago