Key Concepts

Method of Communication

Messages sent to and received from the Paynetworx Gateway are constructed with JSON. The messages are transmitted through TLS 1.2+ URLs.

These URLs are different depending upon whether you are working with the test environment or the production environment.

KSUIDs

The Paynetworx Payment API uses KSUIDs (K-Sortable Unique Identifiers) for all IDs. All KSUIDs are 27 character string implementations to remain HTTP compliant.

For details about creating KSUID values, review the documentation in the repository available through this link: KSUID Repository

Request-ID Header

This is a unique identifier provided by the merchant. This identifier is mandatory for each request.

It should be a newly generated KSUID, so that new KSUID is unrelated to other KSUIDs such as the Entity, Device and Parent Entity KSUIDs provided by Paynetworx.

The Request ID is used to identify the origination of the transaction on the merchant side. The Request-ID assists with the process of transaction research for merchant technical failures that occur while transactions are in progress.

NOTE

*While this identifier is unique to each request, it should be repeated in the event that they have an error, and are repeating the event as a whole*.

Content-Type Header

This must be 'application/json'.

TransactionID

TransactionID is generated by Paynetworx, and it uniquely identifies a 'transaction', so an AUTH and then a CAPTURE and then a REFUND might all have the same TransactionID, because they are referring to the same transaction. This is the only permitted way to identify an AUTH that you want to CAPTURE for example.

EventID

EventID's are like Request-ID's, except that they are generated by Paynetworx. In the above example, the AUTH, the CAPTURE, and the REFUND will all have unique EventIDs, but the same TransactionID. There may be future events that are reported on which do not originate from the merchant. (Such as settlement events, chargebacks, that kind of thing).

Authentication with the Paynetworx Gateway

HTTP Basic Authentication

The Paynetworx Payment API uses HTTP Basic Auth for all requests. Authentication tokens are generated at the time of merchant onboarding, usually relayed as an Access Token User and Access Token Password.

Authorization Header

Syntax:

Authorization: Basic {{authorization-parameter}}

The authorization-parameter is a Base64 encoded concatenation of the following:

{{`Access Token User`}}:{{`Access Token Password`}}.

Authorization header with an Access Token User of 1fHfjpw86udrDQHRMKabypEmhY4 and an Access Token Password of 1fHfkJrOs7iVBnC07HDxCPZuPsK

Authorizaton: Basic MWZIZmpwdzg2dWRyRFFIUk1LYWJ5cEVtaFk0OjFmSGZrSnJPczdpVkJuQzA3SER4Q1BadVBzSw==

Example Encoding (Javascript)

const accessTokenUser = "1fHfjpw86udrDQHRMKabypEmhY4"; // Replace with your access token
const accessTokenPassword = "1fHfkJrOs7iVBnC07HDxCPZuPsK"; // Replace with your access token password
const authorizationParameter = `${accessTokenUser}:${accessTokenPassword}`; // Join accessTokenUser and accessTokenPassword strings
const encodedAuthorizationParameter = btoa(authorizationParameter); // Encode authorizationParameter into base64 (result: MWZIZmpwdzg2dWRyRFFIUk1LYWJ5cEVtaFk0OjFmSGZrSnJPczdpVkJuQzA3SER4Q1BadVBzSw==)