Sign in

v1

latestOpenAPI 3.0.02026-07-2480677847.6 KB
Endpoints

Retrieve a single authorisation

Returns single Authorisation for the given unique ID

get/authorisations/{id}

Path parameters

idstring required

Unique system identifier of the record in our system.

Example:54321123456

The unique system id for the authorisation to retrieve.

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"
    }
  }
}