Quickstart

Get your API credentials, authenticate, and send your first request.

Step 1: Get your API credentials

In order to use the PXP API, you'll need to get your client ID, create a token, and get the token's ID and value.

To get your credentials:

In the Unity Portal, go to Merchant setup > Merchant groups.
Select a merchant group.
Click the Inbound calls tab.
Copy the Client ID in the top-right corner.
Click New token.
Choose a number of days before token expiry. For example, 30.
Click Save to confirm. Your token is now created.
Copy the token ID and token value. Make sure to keep these confidential to protect the integrity of your authentication process.

As best practice, we recommend regularly generating and implementing new tokens.

Step 2: Set up webhooks

The PXP platform can automatically inform your application about events in real time using webhook notifications. This is the easiest way to keep track of transaction events, such as authorisations, captures, and cancellations.

To set up webhooks for your merchant group:

In the Unity Portal, go to Merchant setup > Merchant groups.
Select a merchant group.
Click the Webhooks tab.
Enter the URL you want PXP to send notifications to and generate a hash key.
Click Save to confirm. Your webhooks are now set up.

Step 3: Prepare your API request

Now that you have your credentials and have set up your webhooks, you'll need to prepare your API request. In this example, we'll be authorising a card for an e-commerce transaction.

To do this, you'll need to supply:

Your merchant and site identifier. These are automatically generated by PXP and supplied during onboarding.
A merchantTransactionId of your choice that represents this specific transaction. For example, ECOM_TEST001.
A merchantTransactionDate that corresponds to the date and time when the transaction is being initiated, in ISO 8601 format. For example, 2025-03-18 08:51:02.826445+00:00.

You can replace the placeholders in the following sample:

{
  "merchant": "{merchantValue}",
  "site": "{siteValue}",
  "merchantTransactionId": "{merchantTransactionId}",
  "merchantTransactionDate": "{merchantTransactionDate}",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "11",
      "expiryYear": "2028"
    }
  },
  "amounts": {
    "transaction": 20,
    "currencyCode": "GBP"
  }
}

Step 4: Generate a unique request ID and HMAC signature

Our platform uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity. This method involves creating a signature by hashing your request data with a secret key, which must then be included in the HTTP headers of your API request.

To authenticate, you'll need to:

Create a unique request ID (UUID or GUID) for each API request.
Use your token value and request details to create an HMAC signature with cryptographic functions.

Step 5: Add HTTP headers to your request

Once you've created the HMAC signature, you'll need to include it in the HTTP headers of your API request alongside other identifying information.

The following table describes how to format these headers:

Header name	Description	Format
`Authorization Header`	The HMAC signature. This is made up of the authentication scheme, (e.g., `PXP-UST1`), your `tokenId`, the timestamp, and the HMAC value.	`"Authorization: PXP-UST1 {tokenId}:{timestamp}:{hmac}"`
`X-Request-Id Header`	The unique request ID that you generated.	`"X-Request-Id: {requestId}"`
`X-Client-Id Header`	Your `clientId` , which identifies your specific client application.	`"X-Client-Id: {clientId}"`

Examples

using System;
using System.Security.Cryptography;
using System.Text;
using System.Net.Http;
using System.Net.Http.Headers;

public class ApiAuthentication
{
  private static readonly HttpClient client = new HttpClient();

  public static async void SendAuthenticatedRequest(string requestUri, string requestBody, string tokenValue, string tokenId, string clientId)
  {
    // Generating unique request ID and timestamp
    var requestId = Guid.NewGuid().ToString();
    var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();

    // Preparing the data for HMAC signature
    // Concatenating timestamp, requestId, requestPath, and requestBody for HMAC
    var requestPath = new Uri(requestUri).AbsolutePath.Trim('/');
    var hmacRequestData = $"{timestamp}{requestId}{requestPath}{requestBody}";

    // Creating HMAC signature using the concatenated data and tokenValue
    var hmac = CreateHmacSignature(hmacRequestData, tokenValue).ToUpper();

    // Constructing the authentication header with HMAC signature
    var authHeader = $"PXP-UST1 {tokenId}:{timestamp}:{hmac}";

    // Setting up the request with necessary headers
    // Authorization header includes the HMAC signature
    // X-Request-Id and X-Client-Id headers include requestId and clientId respectively
    var request = new HttpRequestMessage(HttpMethod.Post, requestUri)
    {
      Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
    };

    request.Headers.Authorization = new AuthenticationHeaderValue("Authorization", authHeader);
    request.Headers.Add("X-Request-Id", requestId);
    request.Headers.Add("X-Client-Id", clientId);

    // Sending the request and receiving the response
    var response = await client.SendAsync(request);
    var responseContent = await response.Content.ReadAsStringAsync();

    // Handle response as needed (not part of authentication steps)
  }

  // Helper method to create HMAC signature
  private static string CreateHmacSignature(string data, string key)
  {
    var encoding = new UTF8Encoding();
    byte[] keyBytes = encoding.GetBytes(key);
    byte[] messageBytes = encoding.GetBytes(data);
    using (var hmacsha256 = new HMACSHA256(keyBytes))
    {
      byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
      return BitConverter.ToString(hashmessage).Replace("-", "");
    }
  }    
}

Always ensure that the time on your client is synchronised with the server to avoid issues with timestamp validation.

Step 6: Send your first API request

You can now go ahead and send your API request.

In return, you should receive:

A 200 response containing a systemTransactionId that identifies this specific transaction. You can use this to modify your transaction later.
A webhook that matches the transaction's state. For example, an Authorisation webhook.

{
  "state": "Authorised",
  "approvalCode": "123456",
  "merchantTransactionId": "{merchantTransactionId}",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "avsResult": "noInformationAvailable",
    "cvcResult": "noInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "avsResult": "D",
      "cvcResult": "A",
      "schemeTransactionId": "TX1234567890123456",
      "paymentAccountReference": "PAR12345678901234567890",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2025-03-25T00:00:00.000Z"
    }
  }
}