Sign in

v1

latestOpenAPI 3.0.02026-07-2480677847.6 KB
Endpoints

List Authorisations

Return a list of all authorisations, restricted by your allianceCode, partnerCode or merchant ID (as appropriate) for the given datetime range.

get/authorisations

Query parameters

createdAfterstring date

Filter authorisations on the created field from the given date value in ISO 8601 format yyyy-MM-dd, anything from the time 00:00:00 on the given day would match.

Default: Current day

createdBeforestring date

Filter authorisations on the created field up to and including the given date value in ISO 8601 format yyyy-MM-dd, anything up the the time 23:59:59 on the given day would match.

Default: Current day

limitinteger

Number of elements to be returned in a single query.

Can be used for page/offset or cursor based pagination

offsetinteger

Starting point to start retrieving the elements from. It is "0" based i.e. value "0" signifies the first page.

This can be used with "limit".

Can be used for page/offset based pagination.

sortstring

Specifies the sequence of elements and order to sort the payload by

Defines how to sort the records returned. Must be specified in the syntax '+' (ascending) or '-' (descending) followed by the field name.

For example: +created would sort by the 'created' field ascending.

Allowed fields: created

Default: +created (oldest first)

storeIdstring
Example:678901234

For use by an alliance, partner or merchant when there is a need to filter on a specific store within their scope. May be restricted based on the API key.

terminalIdstring
Example:890123456

Filter for records made on a specific terminal by ID.

orderIdstring
Example:890123456

Filter for records linked by the order ID from our payment gateway.

Headers

Partner-Codestring
Example:DIGI_PAYMENTS

For use by an alliance when there is a need to filter on a specific partner within their scope. May be restricted based on the API key.

Merchant-Idstring
Example:1234567890

For use by an alliance or partner when there is a need to filter on a specific merchant within their scope. May be restricted based on the API key.

Response

OK

idstring required

Unique system identifier of the record in our system.

createdstring date-time required

Date and time the authorisation was processed (in ISO 8601 format yyyy-MM-ddTHH:mm:ssZ). Determined on the basis of the merchants location.

status'APPROVED' | 'DECLINED' | 'PENDING' required

A flag indicating the status of the authorisation and whether it has been approved.

codestring

6-digit code returned by the issuer responsible for approving the authorisation in the event that it is approved. Can be used along with other metadata to reference the authorisation, such as in the case of a dispute.

channel'ECOMMERCE' | 'POINT_OF_SALE' | 'PAY_BY_LINK' | 'MAIL_ORDER' | 'TELEPHONE_ORDER' required

A categorisation for the system which generated the transaction record. The most common being point of sale (such as an in-store card payment) or ecommerce (via an online store), but also includes channels like pay by link, mail order and telephone order.

transactionType'PURCHASE' | 'PAYMENT' | 'CASH_ADVANCE' | 'REFUND' | 'PURCHASE_WITH_CASHBACK' | 'CARD_VERIFICATION' | 'PREPAID_LOAD' | 'BALANCE_ENQUIRY' | 'CHECK_VERIFICATION' | 'CHECK_GUARANTEE' | 'PURCHASE_ADJUSTMENT' | 'MOBILE_TOPUP' | 'PURCHASE_WITH_TIP' | 'ADMIN' | 'ACCOUNT_FUNDING_TRANSACTION' | 'ORIGINAL_CREDIT' | 'MONEY_TRANSFER' required

The nature of the transaction, which often signifies how it is processed. The most common type is a purchase (the transfer of money for goods or services), but may refer to things like a refund or card verification.

transactionSubtype'PRE_AUTH' | 'PRE_AUTH_INCREMENT' | 'PRE_AUTH_DECREMENT' | 'COMPLETION' | 'CANCEL' | 'OTHER' nullable

Optional subtype for the authorisation, used to indicate whether it was part of a pre-auth sequence.

Most authorisations are known as a 'purchase' or 'sale', which involves both the pre-auth and completion in one (in which case this field would be null).

However for purchases like a pay-at-pump petrol transaction, a pre-auth may occur first for a fixed amount, before a completion finalises the transaction. In which case there would be two authorisation records in our system.

messageTypestring required

ISO 8583 code determining type of transaction message being submitted, for example 0110 is an authorisation request response. Each digit has a specific meaning following the format below:

  • 0xxx - version of ISO 8583 (0 = 1987 version)
  • x1xx - class of the message (1 = authorisation message)
  • xx1x - function of the message (1 = response)
  • xxx0 - who began the communication (0 = acquirer)

Example response

[
  {
    "id": "54321123456",
    "created": "2021-08-16T14:12:43Z",
    "status": "APPROVED",
    "code": "454903",
    "channel": "ECOMMERCE",
    "messageType": "0110",
    "merchant": {
      "id": "520334547514337",
      "name": "Matt's Bicycles Ltd",
      "countryCode": "GBR",
      "mcc": "0742",
      "allianceCode": "FISV",
      "partnerCode": "DIGI_PMNTS",
      "storeId": "1108707593"
    },
    "meta": {
      "orderId": "54321123456",
      "referenceId": "8900000395354000",
      "GUID": "adaeeb64-aa26-48b4-95c5-3e79ff68f176",
      "retrievalReferenceNumber": "130237163512",
      "merchantReference1": "GGIC-FK-432432-AB",
      "merchantReference2": "AB-432342-CS-43",
      "reservationNumber": "2432-354353-0002423-243231",
      "customerIPAddress": "8.18.18.25",
      "products": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      ]
    },
    "paymentInstrument": {
      "brand": "VISA",
      "number": "446998******2153",
      "expiryDate": "2501",
      "subType": "N2",
      "token": "123abc456def"
    },
    "financial": {
      "amounts": {
        "currencyCode": "GBP",
        "authorised": "20.99",
        "cashback": "20.99",
        "tip": "20.99"
      },
      "dcc": {
        "currencyCode": "GBP"
      },
      "instalment": {
        "totalNumber": 24,
        "totalAmount": "20.99",
        "deferredPeriod": 2,
        "first": "20.99"
      }
    },
    "transactionAttributes": {
      "issuerResponseCode": "00",
      "avsResponse": "A"
    },
    "captureEnvironment": {
      "platform": "IPG",
      "captureMethod": "CHIP_CONTACTLESS",
      "terminal": {
        "workstationId": "520334508707619",
        "serialNumber": "1359875623",
        "pinCaptureCapability": 4
      }
    },
    "_links": {
      "transactions": {
        "href": "/transactions?postedAfter=2021-08-16&postedBefore=2021-08-18&orderId=123456"
      }
    }
  }
]