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.

EnvironmentBase URL
Staginghttps://api-services.test.pxpfinancial.com
Productionhttps://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 codeHTTP status messagePXP status messageDescription
200OKSuccessfully ProcessedThe request was processed effectively, resulting in a variable response based on the request type and data requested.
400Bad RequestRequest Interpretation ErrorThe server couldn't decipher the request due to incorrect syntax. Errors should be corrected before reattempting the request.
401UnauthorizedAuthentication NeededAccess to the resource requires valid authentication credentials (username/password).
403ForbiddenAccess DeniedAccess to the requested resource is denied due to insufficient permissions. Repeating the request is not advisable.
404Not FoundResource UnavailableThe 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.
413Payload Too LargeExcessive Request SizeThe request body exceeded the 10MB limit. Resend with a smaller payload size.
422Unprocessable EntitySemantic Request ErrorThe request is structurally correct but semantically incorrect, meaning it's readable but not understandable by the server.
500Internal Server ErrorProcessing FailureAn 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.