Integrated Payment Server - Payment API 2.1.1

Integration Guide

For more information on how to integrate into this API, refer to https://developer.worldpay.com/docs/ipc/integration-direct.

Servers

wss://{host}:{port}/ipc-app/payment/{paypointId} stomp 1.2

On-premise installation of IPS.

host: The IP address or domain name of the host running IPS.
DEFAULT: <machine-hostname>
port: The port on which the IPS application is listening.
DEFAULT: 7080
paypointId: Identifier for the paypoint on which the action should be performed on. The Paypoint ID must be between 1 and 100 characters. Valid characters are A-Z, a-z, 0-9, - (hyphen) and _ (underscore).

Operations

Pub /v1/pos/registration

Register a new Point of Sale device, by sending a message to the STOMP destination /v1/pos/registration.

Each request must be made in a new web socket connection.

Accepts the following message:

POS Registration Request Message POSRegistrationRequestMessage

The message to register a new Point of Sale.

Payload
object

The message to register a new Point of Sale.

pointOfSaleId
required
string
length <= 6 length >= 6 must match ^[a-zA-Z0-9]{6}$

A unique identifier for the Point of Sale.

pointOfSaleReference
required
string
length <= 15 length >= 1 must match ^[a-zA-Z0-9]{1,15}$

A reference provided by the merchant for the Point of Sale.

pointOfSaleActivationCode
required
string
length <= 8 length >= 8 must match ^[a-zA-Z0-9]{8}$

A unique code to allow a Point of Sale to be activated.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Point of Sale Registration

Examples

POSRegistrationRequestMessage
Payload
{
  "pointOfSaleId": "D45FGT",
  "pointOfSaleReference": "POS123",
  "pointOfSaleActivationCode": "AV46HTR3"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/pos/registration

Receive confirmation of the Point of Sale's registration.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/pos/registration

Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

POS Registration Response Message POSRegistrationResponseMessage

The message confirming the registration of a new Point of Sale.

Payload
object

The message confirming the refresh of a Point of Sale registration.

pointOfSaleLicenseKey
required
string
length <= 2000 length >= 1 must match ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$

A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Point of Sale Registration

Examples

POSRegistrationResponseMessage
Payload
{
  "pointOfSaleLicenseKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/pos/registration/refresh

Refresh the Point of Sale device's registration, by sending a message to the STOMP destination /v1/pos/registration/refresh.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

POS Registration Refresh Request Message POSRegistrationRefreshRequestMessage

The message to refresh a Point of Sale registration.

Payload
object

The message to refresh a Point of Sale registration.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Point of Sale Registration

Examples

POSRegistrationRefreshRequestMessage
Payload
{}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/pos/registration/refresh

Receive confirmation of the Point of Sale's registration refesh.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/pos/registration/refresh

Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

POS Registration Refresh Response Message POSRegistrationRefreshResponseMessage

The message confirming the refresh of a Point of Sale registration.

Payload
object

The message confirming the refresh of a Point of Sale registration.

pointOfSaleLicenseKey
required
string
length <= 2000 length >= 1 must match ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$

A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Point of Sale Registration

Examples

POSRegistrationRefreshResponseMessage
Payload
{
  "pointOfSaleLicenseKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment

Initiate a new payment, by sending a message to the STOMP destination /v1/payment.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Start Message PaymentStartMessage

The message to initiate a new payment.

Payload
object

Message to start a new payment.

paymentType
required
string

The type of payment.

  • sale - Authorise and settle a payment from a customer for goods/services.
  • refund - Authorise and settle a payment to a customer for the return of goods/services.
  • pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.
  • check-card - Check and retrieve details of the customer's card, without taking a payment.
  • check-card-payment - Check and retrieve details of the customer's card, and wait for the payment request on this card.
Enum: "sale" "refund" "pre-auth" "check-card" "check-card-payment"
merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

instruction
required
object

The instruction to start the payment.

value
required
object

The monetary value of the payment

amount
required
integer
int64 >= 0 <= 999999999

The amount for the payment requested by the merchant in minor currency units.

Additional properties are allowed.

narrative
object

A description of the payment to appear in customer's transaction statements.

Currently only supported for Alipay payments and requires an alphanumeric value.

line1
required
string
length <= 256 length >= 1

First line of the narrative.

Additional properties are allowed.

originalTransactionReference
string
length <= 256 length >= 1 must match ^[0-9a-zA-Z\!#\$%\(\)\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$

For cross-channel refunds, provide the transaction reference from the original sale being refunded.

Must contain only alpha numeric, or these special characters:

! # $ % ( ) * + , - . / : ; = ? @ [ \ ] _ ` { } ~

originalMerchantCode
string
length <= 30 length >= 1 must match ^[0-9a-zA-Z]{1,30}$

For cross-channel refunds, provide the merchant code used in the original sale being refunded.

originalGatewayTransactionReference
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

For refunding card sales, optionally provide the Payment Gateway Transaction Reference of the original sale being refunded.

For refunding Alipay sales, the original Gateway Transaction Reference is mandatory.

paymentInstrument
required
oneOf

The method by which the payment should be made.

0
object

Details for a payment instrument captured by a payment device.

This payment instrument is supported for sale, refund, pre-auth, check-card and check-card-payment payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/present" "card/keyed" "card/not-present"
isHandledOnline
boolean

Indicates whether the payment should be performed online or not. Defaults to true if omitted on a payment where it is applicable.

Currently, an online/offline choice is only applicable to the check-card and check-card-payment payment types, online/offline processing is determined automatically for all other payments regardless of this indicator.

Additional properties are allowed.

1
object

Details for keying card details into the payment device for a pre-approved referral transaction.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/keyed-recovery"
authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code for the payment obtained through a prior voice authorisation.

Optional for sale payments, not required for refund payments.

If omitted from a sale payment, the authorisation code will be requested via the voice-authorisation payment action request.

Additional properties are allowed.

2
object

Details for a token-based payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/token"
tokenId
required
string
length <= 21 length >= 15 must match ^[0-9a-zA-Z]{15,21}$

A token representing a card used in a payment. This will be returned in the result of a card payment if tokenisation is enabled, and can be sent in the request for payment with a card/token payment instrument.

The following token formats are supported:

  • Alphanumeric token – this token uses an alternating sequence of upper case letters and numbers, and is always 15 digits long. The letters I and O are never used due to their similarity with numbers. Useful if you do not require a numeric token, and prefer the token to be clearly distinguished from card numbers.
  • Wrapped luhn fail token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will not pass through luhn (modulus 10) checks. Useful if you want to avoid possible issues with regard to PCI DSS compliance checks, because tokens will not be mistaken for a card number.
  • Wrapped luhn pass token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will pass through luhn (modulus 10) checks. Useful if you have system validation that requires your token to be similar to a card number.
  • Format preserving token – this token uses a part of the card number used to create it, and is always 20 digits long. The first two digits are always 99. The next six digits are the first six numbers on the card used. The final four digits are the last four numbers on the card used.

Additional properties are allowed.

3
object

Details for a Alipay barcode payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "alipay/barcode"
barcode
required
string
length <= 24 length >= 16 must match ^[0-9]{16,24}$

The barcode value generated by the customer's Alipay app and scanned by the merchant.

sendAttempt
number
int32 >= 1

An incrementing count of the number of attempts to send this barcode for this payment.

Defaults to 1 if not provided.

quantity
number
int32 >= 1

Quantity of the commodity in the payment. This value is shown in the consumer's transaction records list from Alipay.

Defaults to 1 if not provided.

Additional properties are allowed.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentStartMessage
Payload
{
  "paymentType": "sale",
  "merchantTransactionReference": "MS_123-A54B3DF",
  "instruction": {
    "value": {
      "amount": 1099
    },
    "narrative": {
      "line1": "Transaction description"
    },
    "originalTransactionReference": "98765ABCDEF123456",
    "originalMerchantCode": "M123456",
    "originalGatewayTransactionReference": "1234567890AB",
    "paymentInstrument": {
      "type": "card/present",
      "isHandledOnline": true
    }
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/notification

Receive real-time status updates for an in-flight payment, by subscribing to the STOMP destination /client/v1/payment/notification.

Subscribing to this destination requires an authenticated connection.

Clients will receive multiple replies on this destination in response to publishing on the following destinations:

  • /v1/payment

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the payment.

Accepts the following message:

Payment Status Message PaymentStatusMessage

The message to communicate the real-time status of an in-flight payment.

Payload
object

Message with a notification about the payment flow which requires no action to be taken.

These can be displayed to the member of staff to inform them of the payment's progress.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

notificationText
required
string
length <= 256 length >= 1

Text describing an event occurring in the payment flow.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentStatusMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "notificationText": "PLEASE INSERT CARD"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/action

Receive a request to take an action in order to proceed with in-flight payment, by subscribing to the STOMP destination /client/v1/payment/action.

Subscribing to this destination requires an authenticated connection.

Clients could receive multiple replies on this destination (if multiple actions are required) in response to publishing on the following destinations:

  • /v1/payment

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the payment.

Accepts the following message:

Payment Action Request Message PaymentActionRequestMessage

The message to request an action to proceed with the payment.

Payload
object

Message with details of an action to completed by the merchant.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

data
required
oneOf

Description of the action required for the payment.

0
object

The merchant is required to perform voice authorisation.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "voice-authorisation"
merchant
required
object

Merchant identifiers to complete voice authorisation for this payment.

merchantId
required
string
length <= 10 length >= 8

The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.

referralContacts
required
array<object>

Referral contact details to complete voice authorisation for this payment.

Items:

0
object
method
required
string

The method of contact.

Enum: "phone-number"
value
required
string
length <= 255 length >= 1

The value contact method, e.g. the phone number.

Additional properties are allowed.

Additional items are allowed.

Additional properties are allowed.

1
object

Merchant is required to confirm the customer's signature.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "signature-verification"

Additional properties are allowed.

2
object

The merchant is required to approve the transaction based on AVS check results.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "avs-confirmation"
avsResults
required
object

Results of the payment's AVS check to be approved by the merchant.

isCvvMatch
required
string

Indicates if the CVV of the card matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"
isAddressLineMatch
required
string

Indicates if the cardholder address line(s) matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"
isPostalCodeMatch
required
string

Indicates if the cardholder postal code matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"

Additional properties are allowed.

Additional properties are allowed.

3
object

Merchant is required provide a cashback amount.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "cashback-amount"
maximumCashbackAmount
required
integer
int64 >= 0 <= 999999999

The maximum allowed amount of cash back available for the payment, in minor currency units.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentActionRequestMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "data": {
    "action": "voice-authorisation",
    "merchant": {
      "merchantId": "12345678"
    },
    "referralContacts": [
      {
        "method": "phone-number",
        "value": "02011112222"
      }
    ]
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/action

Confirm the action taken for an in-flight payment, by sending a message to the STOMP destination /v1/payment/action.

Publishing to this destination requires an authenticated connection.

Clients should send a single message on this destination, and in the same session, for each message received on the client/v1/payment/action destination. The content of the message received on that destination describes the required action details to be sent on this destination.

Accepts the following message:

Payment Action Complete Message PaymentActionCompleteMessage

The message to confirm the action for the payment has been completed.

Payload
object

Message with details of the action completed by the merchant.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

data
required
oneOf

The action taken by the POS to proceed with the payment.

0
object

Voice authorisation data.

action
string

The action which has been performed to continue the payment.

Enum: "voice-authorisation"
authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code provided by the issuer, omitted if the transaction is not authorised.

Additional properties are allowed.

1
object

Signatured verfication data.

action
required
string

The action which has been performed to continue the payment.

Enum: "signature-verification"
isSignatureVerified
required
boolean

Whether the signature was verified.

Additional properties are allowed.

2
object

AVS confirmation data.

action
required
string

The action which has been performed to continue the payment.

Enum: "avs-confirmation"
isAvsConfirmed
required
boolean

Whether AVS results are confirmed.

Additional properties are allowed.

3
object

Cashback data.

action
required
string

The action which has been performed to continue the payment.

Enum: "cashback-amount"
cashbackAmount
required
integer
int64 >= 0 <= 999999999

The amount of cash back to be included in the payment, in minor currency units.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentActionCompleteMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "data": {
    "action": "voice-authorisation",
    "authorisationCode": "12345"
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/abort

Abort a check card payment request, by sending a message to the STOMP destination /v1/payment/abort.

Publishing to this destination requires an authenticated connection.

Clients should send a this message in the same session as the original check-card-payment payment request to indicate that they no longer wish to initiate a payment after the card has been checked.

Accepts the following message:

Payment Abort Message PaymentAbortMessage

The message to abort a check card payment.

Payload
object

Message to abort a check card payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentAbortMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/receipt

Receive the content of the receipt(s) for the payment, by subscribing to the STOMP destination /client/v1/payment/receipt.

Subscribing to this destination requires an authenticated connection.

Clients will receive multiple replies (one per receipt type) on this destination in response to publishing on the following destinations:

  • /v1/payment
  • /v1/payment/cancel
  • /v1/payment/query/receipt

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the payment.

Accepts the following message:

Payment Receipt Message PaymentReceiptMessage

The message to receive a payment receipt.

Payload
object

Message with a receipt for a payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

type
required
string

The type of receipt.

  • customer - Customer copy of a receipt.
  • merchant - Merchant copy of a receipt.
Enum: "customer" "merchant"
content
required
string

Base64 representation of the UTF-8 encoded content of the receipt.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments Manage Existing Payments

Examples

PaymentReceiptMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "type": "customer",
  "content": "RVhBTVBMRSBSRUNFSVBUIENPTlRFTlQ="
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/result

Receive the result of a completed payment, by subscribing to the STOMP destination /client/v1/payment/result.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/payment
  • /v1/payment/settle
  • /v1/payment/cancel
  • /v1/payment/query/result

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the payment.

Accepts the following message:

Payment Result Message PaymentResultMessage

The message to communicate the result of a completed payment.

Payload
object

Message with payment results.

payments
required
array<object>

The list of completed payments, typically 1 payment but will be multiple in the case of a split payment done on the payment device.

Items:

0
object

Full details of a completed payment.

paymentType
required
string

The type of payment that was requested.

  • sale - Authorise and settle a payment from a customer for goods/services.
  • refund - Authorise and settle a payment to a customer for the return of goods/services.
  • pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.
  • check-card - Check and retrieve details of the customer's card, without taking a payment.
  • check-card-payment - Check and retrieve details of the customer's card, and wait for the payment request on this card.
  • cancel - The cancellation of a previously requested sale, refund, or pre-auth.
  • settle - The settlement of a previously requested pre-auth.
Enum: "sale" "refund" "pre-auth" "check-card" "check-card-payment" "cancel" "settle"
transactionDateTime
required
string
date-time

The date-time at which the transaction was processed. Represented as a date-time according to RFC 3339, section 5.6, including the relevant time zone.

outcome
required
string

The outcome of the payment request.

  • succeeded - The request was processed successfully.
  • refused - The payment request was refused by the payment device, acquirer or issuer.
  • pending - The final outcome of the request is not yet known.
  • failed - The request could not be processed.
Enum: "succeeded" "refused" "pending" "failed"
result
required
string

The code representing the result of payment request.

Succeeded

  • authorised-online - The payment was authorised by card issuer, payment scheme or your acquirer.
  • authorised-offline - The payment was accepted locally by IPS.
  • authorised-referral - The payment was accepted locally by IPS on entry of a referral code by the POS attendant.
  • keyed-recovery-success - The keyed recovery payment was successfully stored by the Integrated POS gateway and will be submitted for settlement to your acquirer.
  • pre-auth-completed - The previously authorised transaction has been successfully flagged for settlement and will be submitted to your acquirer.
  • succeeded - The abort, cancel or settle request was processed successfully.

Refused

  • refused-online - The payment was refused by card issuer, payment scheme or your acquirer.
  • refused-offline - The payment was refused locally by IPS.
  • refused-online-capture-card - The payment was refused by card issuer, payment scheme or your acquirer and the card should be kept by the merchant.
  • refused-avs-required - The payment was refused by card issuer, payment scheme or your acquirer because AVS was required but not provided.

Pending

  • started - The payment process has started.
  • in-progress - The payment authorisation is in progress.
  • auth-completed - The payment authorisation process has completed. At this stage the payment record may not yet be saved to the Integrated POS gateway.

Failed

  • cancelled - The request process was cancelled by the merchant or customer.
  • aborted - The request was has been aborted unexpectedly.
  • aborted-device-unavailable - The request been aborted because the payment device is unavailable.
  • aborted-busy - The request been aborted because the system is currently busy.
  • rejected-pre-auth - The pre-authorisation request was rejected.
  • rejected-card-number-not-matched - The request was rejected because the card number did not match the expected value.
  • rejected-card-expiry-date-not-matched - The request was rejected because the card expiry date did not match the expected value.
  • rejected-card-not-accepted - The request was rejected because the card use is not accepted by the system.
  • invalid-transaction-state - The request cannot be performed on the transaction in its current state.
  • invalid-operation - The requested operation is not supported.
  • invalid-gateway-transactions-reference - The request cannot be processed because the gateway transaction reference is not recognised.
  • invalid-merchant - The request cannot be processed as the configured merchant details are invalid.
  • invalid-terminal - The request cannot be processed as the configured terminal details are invalid.
  • invalid-merchant-status - The request cannot be processed as merchant is not active.
  • invalid-card-number - The request cannot be processed as the card number is invalid.
  • invalid-expired-card - The request cannot be processed as the card has expired.
  • invalid-issue-number - The request cannot be processed as the card issuer number is invalid.
  • invalid-card-expiry-date - The request cannot be processed as the card expiry date is invalid.
  • invalid-amount - The requested sale or refund amount is not valid.
  • denied-transaction - The transaction was denied.
  • denied-cashback - The request for cashback was denied.
  • pre-valid-card - The request cannot be processed as the card is not yet valid.
  • failed - The request could not be processed.
Enum: "authorised-online" "authorised-offline" "authorised-referral" "keyed-recovery-success" "pre-auth-completed" "succeeded" "refused-online" "refused-offline" "refused-online-capture-card" "refused-avs-required" "started" "in-progress" "auth-completed" "cancelled" "aborted" "aborted-device-unavailable" "aborted-busy" "rejected-pre-auth" "rejected-card-number-not-matched" "rejected-card-expiry-date-not-matched" "rejected-card-not-accepted" "invalid-transaction-state" "invalid-operation" "invalid-gateway-transactions-reference" "invalid-merchant" "invalid-terminal" "invalid-merchant-status" "invalid-card-number" "invalid-expired-card" "invalid-issue-number" "invalid-card-expiry-date" "invalid-amount" "denied-transaction" "denied-cashback" "pre-valid-card" "failed"
merchant
allOf

Details of the merchant.

0
object

Identifies the merchant that originates the payment.

merchantId
required
string
length <= 10 length >= 8

The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.

1
object

Full details of the merchant.

name
required
string
length <= 40 length >= 1

The merchant's name.

address
required
object

The merchant's address.

line1
string
length <= 140 length >= 1

Line 1 of the address

line2
string
length <= 140 length >= 1

Line 2 of the address

line3
string
length <= 140 length >= 1

Line 3 of the address

city
string
length <= 140 length >= 1

City of the address

state
string
length <= 140 length >= 1

State/County/Region of the address

postalCode
string
length <= 8 length >= 1

Postal code (Post/Zip code) of the address

countryCode
string
length <= 2 length >= 2

The 2-letter ISO-3166-1 country code of the address

Additional properties are allowed.

Additional properties are allowed.

paypoint
required
object

The paypoint the request has been performed on.

paypointId
required
string
length <= 12 length >= 1

The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
length <= 10 length >= 8

The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.

value
object

The monetary value of the payment.

amount
required
integer
int64 >= 0 <= 999999999

The full amount the customer's card has been charged or refunded including any gratuity, donations or cash back, in minor currency units.

currencyCode
required
string
length <= 3 length >= 3

The 3-letter ISO 4217 currency code which amounts are specified in.

cashbackAmount
integer
int64 >= 0 <= 999999999

The amount of cash back included in the payment, in minor currency units.

gratuityAmount
integer
int64 >= 0 <= 999999999

The amount of gratuity included in the payment, in minor currency units.

donationAmount
integer
int64 >= 0 <= 999999999

The amount of donation included in the payment, in minor currency units.

dcc
object

Data for Dynamic Currency Conversion if relevant to the payment.

convertedCurrencyCode
required
string
length <= 3 length >= 3

The 3-letter ISO 4217 currency code which the amount was converted to.

convertedAmount
required
integer
int64 >= 0 <= 999999999

The amount of the payment converted into the currency in minor currency units.

conversionRate
required
number
double >= 0

The conversion rate from the merchant's currency to the cardholder's local currency.

Additional properties are allowed.

Additional properties are allowed.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

gatewayTransactionReference
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

The transaction reference generated by the payment gateway to uniquely identify the payment. This will be available for any payment which has been processed online.

eftSequenceNumber
integer
int64 >= 1

The transaction sequence number.

retrievalReferenceNumber
integer
int64 >= 1 <= 9999999999

The retrieval reference number for the transaction.

receiptNumber
integer
int64 >= 1 <= 9999999999

The number of the receipt to be issued.

receiptRetentionReminder
string
length <= 50 length >= 1

A retention reminder to include on receipts.

receiptCustomerDeclaration
string
length <= 50 length >= 1

A customer declaration to include on receipts.

taxFreeVoucher
string

Base64 representation of the UTF-8 encoded content of the voucher.

The first 2 characters of each line a print command, followed by the text to print.

The print commands are:

  • 01 - Print the Premier taxfree logo bitmap
  • 02 - Print large bold text, followed by a carriage return
  • 03 - Print large underlined text, followed by a carriage return
  • 04 - Print normal underlined text, followed by a carriage return
  • 05 - Print normal text, followed by a carriage return
  • 06 - Print normal sized bold text, followed by a carriage return
  • 07 - Print normal sized wide text, followed by a carriage return
  • 08 - Print normal right aligned text, followed by a carriage return
  • 09 - Print normal centre aligned text, followed by a carriage return
  • 10 - Print large bold centered text, followed by a carriage return
  • 11 - Print the data as a 'Interleaved 2 of 5' barcode
  • 12 - Print carriage return
  • 13 - Auto cut paper
  • 50 - Load another voucher
  • 51 - Print copy
  • 61 - The remainder of the text after the print code is encrypted and base64 encoded. Decrypt it and then print normal text, followed by a carriage return
paymentInstrument
oneOf

The method by which the payment was made.

0
object

Details for a card-based payment instrument.

This payment instrument is supported for sale, refund, pre-auth, check-card and check-card-payment payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/present" "card/keyed" "card/not-present" "card/token"
card
object

Data for the card used in the payment.

tokenId
string
length <= 21 length >= 15 must match ^[0-9a-zA-Z]{15,21}$

A token representing a card used in a payment. This will be returned in the result of a card payment if tokenisation is enabled, and can be sent in the request for payment with a card/token payment instrument.

The following token formats are supported:

  • Alphanumeric token – this token uses an alternating sequence of upper case letters and numbers, and is always 15 digits long. The letters I and O are never used due to their similarity with numbers. Useful if you do not require a numeric token, and prefer the token to be clearly distinguished from card numbers.
  • Wrapped luhn fail token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will not pass through luhn (modulus 10) checks. Useful if you want to avoid possible issues with regard to PCI DSS compliance checks, because tokens will not be mistaken for a card number.
  • Wrapped luhn pass token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will pass through luhn (modulus 10) checks. Useful if you have system validation that requires your token to be similar to a card number.
  • Format preserving token – this token uses a part of the card number used to create it, and is always 20 digits long. The first two digits are always 99. The next six digits are the first six numbers on the card used. The final four digits are the last four numbers on the card used.
cardNumber
string
length <= 19 length >= 13 must match ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$

The Primary Account Number of the card. For whitelisted cards the full card number can be returned, for all other cards the number is masked. The first 6 digits and last 4 digits are returned, the middle digits are replaced by X.

expiryDate
object

The expiry date of the card. Omitted if the card does not have an expiry date.

month
required
integer
int32 >= 1 <= 12
year
required
integer
int32 >= 0 <= 99

Additional properties are allowed.

track2Data
string
length <= 40 length >= 7 must match ^\;([0-9]{1,19})\=([0-9]{4}|\=)([0-9]{3}|\=)([^\?]+)\?$

The Track 2 data of the card as defined by ISO 7813. Available for whitelisted BIN ranges for check-card and check-card-payment transactions.

type
string

Indicator for the type of card. This field is omitted if the card type is unknown.

  • fuel - The card used was a fuel card.
  • debit - The card used was a debit card.
  • credit - The card used was a credit card.
Enum: "fuel" "debit" "credit"
issuerCode
string
length <= 256 length >= 1 must match ^[a-zA-Z0-9\-]{1,256}$

A reference which can be used to identify the issuer of card.

Major card schemes
  • amex - Amex
  • bank-of-america - Bank of America
  • dankort - DANKORT
  • diners - Diners Club International
  • discover - Discover
  • jcb - JCB
  • maestro-uk - UK Maestro
  • maestro - Maestro
  • mastercard-debit - Debit Mastercard
  • mastercard-purchasing - Mastercard Purchasing
  • mastercard - Mastercard
  • us-debit - US Debit
  • visa-debit - VISA DEBIT
  • visa-electron-uk - UK Electron
  • visa-purchasing - Visa Purchasing
  • visa - Visa
  • visa-atm - VISA ATM
Store cards and gift cards
  • arval-phh - ARVAL PHH
  • flexecash-love-2-reward - Flexecash Love 2 Reward
  • harvey-nichols - HN PLCC
  • harvey-nichols-mastercard - HN Mastercard
  • newday-mastercard - Newday MasterCard
  • newday-staff - Newday Staff Card
  • newday-store - Newday Store PLC
  • newday-temporary - Newday Temporary
  • pps-gift - PPS Gift Card
  • tesco-clubcard - Tesco Clubcard

New values may be added without a software release.

countryCode
string
length <= 3 length >= 3 must match ^[0-9]{3}$

The 3-digit numeric ISO 3166 code for the country the card was issued in.

panSequenceNumber
string
length <= 2 length >= 2 must match ^[0-9]{2}$

The PAN Sequence number for ICC payments, and the card's issue number for swiped UK Maestro/Solo card payments.

applicationLabel
string
length <= 16 length >= 1

The mnemonic associated with the application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

applicationIdentifier
string
length <= 32 length >= 10 must match ^[A-Z0-9]{10,32}$

The application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

Note – For VISA Contactless Cards, truncated EMV Card Data Element Application Identifier (AID) will be received instead Extended AID.

applicationEffectiveDate
string
date

The date from which the application can be used. Represented as a full-date according to RFC 3339, section 5.6.

Additional properties are allowed.

posEntryMode
string
must match ^[a-zA-Z0-9\-]{1,50}$

The method of reading the card. The current possible values are:

  • keyed
  • magstripe
  • integrated-circuit-chip
  • contactless-chip
  • contactless-magstripe
  • contactless-on-device
  • cardholder-not-present

New values may be added in future without a software release.

cardVerificationMethod
string
must match ^[a-zA-Z0-9\-]{1,50}$

The verification method used for the cardholder. The current possible values are:

  • signature
  • pin-or-consumer-device
  • pin-and-signature
  • cardholder-not-present
  • none
  • unknown

New values may be added in future without a software release.

isHandledOnline
boolean

Indicates whether the payment request was handled online or not.

Currently, this is only applicable to check-card and check-card-payment payment types.

authorisation
object

Data for the authorisation of the payment.

authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code generated by the issuer for an authorised payment.

cvvResponseData
string
length <= 6 length >= 6 must match ^[0-9A-F]{6}$

Additional response data containing the CVV response.

Additional properties are allowed.

debug
object
transactionStatusInfo
string
length <= 4 length >= 1 must match ^[0-9A-F]{1,4}$

Transaction Status Information (TSI), present only in case of an ICC payment. Used for debug purpose only.

transactionVerificationResults
string
length <= 10 length >= 1 must match ^[0-9A-F]{1,10}$

Transaction Verification Results (TVR), present only in case of an ICC payment. Used for debug purpose only.

Additional properties are allowed.

Additional properties are allowed.

1
object

Details for a Alipay barcode payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "alipay/barcode"
barcode
required
string
length <= 24 length >= 16 must match ^[0-9]{16,24}$

The barcode value generated by the customer's Alipay app and scanned by the merchant.

Additional properties are allowed.

Additional properties are allowed.

Additional items are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentResultMessage
Payload
{
  "payments": [
    {
      "paymentType": "sale",
      "transactionDateTime": "2019-08-24T14:15:22Z",
      "outcome": "succeeded",
      "result": "authorised-online",
      "merchant": {
        "merchantId": "12345678",
        "name": "Worldpay",
        "address": {
          "line1": "Worldpay",
          "line2": "The Walbrook Building",
          "line3": "25, Walbrook",
          "city": "City of London",
          "state": "Greater London",
          "postalCode": "EC4N 8AF",
          "countryCode": "GB"
        }
      },
      "paypoint": {
        "paypointId": "INST001",
        "terminalId": "987654321"
      },
      "value": {
        "amount": 3000,
        "currencyCode": "GBP",
        "cashbackAmount": 2000,
        "gratuityAmount": 450,
        "donationAmount": 54,
        "dcc": {
          "convertedCurrencyCode": "EUR",
          "convertedAmount": 3349,
          "conversionRate": 1.11647
        }
      },
      "merchantTransactionReference": "MS_123-A54B3DF",
      "gatewayTransactionReference": "1234567890AB",
      "eftSequenceNumber": 1,
      "retrievalReferenceNumber": 1,
      "receiptNumber": 1,
      "receiptRetentionReminder": "PLEASE KEEP THIS RECEIPT FOR YOUR RECORDS",
      "receiptCustomerDeclaration": "PLEASE DEBIT MY ACCOUNT",
      "taxFreeVoucher": "MDEKMDJWT1VDSEVSCjEyCjA2RVhBTVBMRSBDT05URU5UCjEz",
      "paymentInstrument": {
        "type": "card/present",
        "card": {
          "tokenId": "532931432DB44ABB5",
          "cardNumber": "492949XXXXXX0002",
          "expiryDate": {
            "month": 12,
            "year": 20
          },
          "track2Data": ";1234567890123445=99011200XXXX00000000?*",
          "type": "debit",
          "issuerCode": "visa-debit",
          "countryCode": "826",
          "panSequenceNumber": "01",
          "applicationLabel": "VISA BARCLAYCARD",
          "applicationIdentifier": "A0000000031010",
          "applicationEffectiveDate": "2019-08-24"
        },
        "posEntryMode": "contactless-chip",
        "cardVerificationMethod": "pin-or-consumer-device",
        "isHandledOnline": true,
        "authorisation": {
          "authorisationCode": "12345",
          "cvvResponseData": "422800"
        },
        "debug": {
          "transactionStatusInfo": "F800",
          "transactionVerificationResults": "4000008000"
        }
      }
    }
  ]
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/complete

Receive confirmation that the payment process has completed, by subscribing to the STOMP destination /client/v1/payment/complete.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/payment
  • /v1/payment/settle
  • /v1/payment/cancel

Once received the client must disconnect from the web socket connection.

Accepts the following message:

Payment Complete Message PaymentCompleteMessage

The message communicate that the payment process is complete.

Payload
object

Message confirming the payment process has completed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentCompleteMessage
Payload
{}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/settle

Settle a previous pre-authorised payment, by sending a message to the STOMP destination /v1/payment/settle.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Settle Message PaymentSettleMessage

The message to settle a pre-authorised payment.

Payload
object

Message to settle a previously requested pre-auth payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The Merchant Transaction Reference of the pre-auth payment to settle.

gatewayTransactionReference
required
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

The Payment Gateway Transaction Reference (PGTR) of the pre-auth payment to settle.

value
required
object

The final monetary value to settle, may be different to the original pre-auth payment.

amount
required
integer
int64 >= 1 <= 999999999

The amount for the payment requested to be settled by the merchant in minor currency units.

Additional properties are allowed.

paymentInstrument
required
object

The method by which the original payment was made.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

All card payment instruments (card/present, card/keyed, card/not-present, card/token) are covered.

Enum: "card"
cardNumber
required
string
length <= 19 length >= 13 must match ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$

The masked card number of the card used in the original payment to check against.

cardExpiryDate
required
object

The expiry date of the card used in the original payment to check against.

month
required
integer
int32 >= 1 <= 12
year
required
integer
int32 >= 0 <= 99

Additional properties are allowed.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentSettleMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "gatewayTransactionReference": "1234567890AB",
  "value": {
    "amount": 1099
  },
  "paymentInstrument": {
    "type": "card",
    "cardNumber": "492949XXXXXX0002",
    "cardExpiryDate": {
      "month": 12,
      "year": 20
    }
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/cancel

Cancel a previous payment, by sending a message to the STOMP destination /v1/payment/cancel.

Publishing to this destination requires an authenticated connection.

Cancelling a card payment prevents it from being sent for settlement, however the authorisation is not reversed. This means the funds ring-fenced in the customers account will not be released immediately. Funds will be released according to the card issuer's policy, typically 3 to 5 days.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Cancel Message PaymentCancelMessage

The message to cancel a previous payment.

Payload
object

Message to cancel a payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The Merchant Transaction Reference of the payment to cancel.

gatewayTransactionReference
required
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

The Payment Gateway Transaction Reference (PGTR) of the payment to cancel. This must be provided for any payment which has been assigned a PGTR.

paymentInstrument
required
oneOf

The method by which the original payment was made.

0
object

Details to validate against a previous card-based payment instrument.

This payment instrument is supported for sale, refund and pre-auth payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

All card payment instruments (card/present, card/keyed, card/not-present, card/token) are covered.

Enum: "card"
cardNumber
required
string
length <= 19 length >= 13 must match ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$

The masked card number of the card used in the original payment to check against.

cardExpiryDate
required
object

The expiry date of the card used in the original payment to check against.

month
required
integer
int32 >= 1 <= 12
year
required
integer
int32 >= 0 <= 99

Additional properties are allowed.

Additional properties are allowed.

1
object

Details for a Alipay barcode payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "alipay/barcode"
barcode
required
string
length <= 24 length >= 16 must match ^[0-9]{16,24}$

The barcode value generated by the customer's Alipay app and scanned by the merchant.

sendAttempt
number
int32 >= 1

An incrementing count of the number of attempts to send this barcode for this payment.

Defaults to 1 if not provided.

quantity
number
int32 >= 1

Quantity of the commodity in the payment. This value is shown in the consumer's transaction records list from Alipay.

Defaults to 1 if not provided.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentCancelMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "gatewayTransactionReference": "1234567890AB",
  "paymentInstrument": {
    "type": "card",
    "cardNumber": "492949XXXXXX0002",
    "cardExpiryDate": {
      "month": 12,
      "year": 20
    }
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/query/result

Query the result of the last payment, by sending a message to the STOMP destination /v1/payment/query/result.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Query Result Message PaymentQueryResultMessage

The message to query the result of the last payment.

Payload
object

Message to query the last payment result.

Note that the transaction reference is required here to ensure that the expected payment result is returned.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentQueryResultMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/query/receipt

Query the receipt of the last payment, by sending a message to the STOMP destination /v1/payment/query/receipt.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Query Receipt Message PaymentQueryReceiptMessage

The message to query the receipt of the last payment.

Payload
object

Message to query the receipt for the last payment.

Note that the transaction reference is required here to ensure that the expected payment receipt is returned.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

type
required
string

The type of receipt.

  • customer - Customer copy of a receipt.
  • merchant - Merchant copy of a receipt.
Enum: "customer" "merchant"

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payments

Examples

PaymentQueryReceiptMessage
Payload
{
  "merchantTransactionReference": "MS_123-A54B3DF",
  "type": "customer"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/report/batch

Request an X or Z Report for the current batch, by sending a message to the STOMP destination /v1/payment/report/batch.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Report Batch Request Message PaymentReportBatchRequestMessage

The message to request an X or Z Report for the transactions in the current batch.

Payload
object

The message to request an X or Z Report for the transactions in the current batch.

closeBatch
required
boolean

Whether the close the current batch once the report is generated.

Keeping the batch open is also known as an "X Report".

Closing the batch is also known as a "Z Report".

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payment Reports

Examples

PaymentReportBatchRequestMessage
Payload
{
  "closeBatch": false
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/report/batch

Receive the X or Z Report for the current batch, by subscribing to the STOMP destination /client/v1/payment/report/batch.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/payment/report/batch

Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

Payment Report Batch Response Message PaymentReportBatchResponseMessage

The message to receive an X or Z Report for the transactions in the current batch.

Payload
object

The message to receive a report for the transactions in the current batch.

paypoint
required
object

The paypoint associated with the batch.

paypointId
required
string
length <= 12 length >= 1

The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
length <= 10 length >= 8

The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.

batchNumber
required
integer
int64 >= 0 <= 99999999

The current batch number.

currencyCode
required
string
length <= 3 length >= 3

The 3-letter ISO 4217 currency code which amounts are specified in.

saleCount
required
integer
int64 >= 0

The total number of sales in the batch.

refundCount
required
integer
int64 >= 0

The total number of sales in the batch.

saleTotalAmount
required
integer
int64 >= 0 <= 999999999

The total value of all sales in the batch in minor currency units.

refundTotalAmount
required
integer
int64 >= 0 <= 999999999

The total value of all refunds in the batch in minor currency units.

batchReport
required
object

A report for the current batch.

fcr
required
integer
int64 >= 0 <= 99999999

The current batch number.

reportDate
required
string
date-time

The date-time at which report was generated. Represented as a date-time according to RFC 3339, section 5.6, including the relevant time zone.

report
required
array<object>

A breakdown of the report by card scheme.

Items:

0
object

A report of the transactions for a specific card scheme in the batch.

cardScheme
required
string
length <= 256 length >= 1

The card scheme.

creditCount
required
integer
int64 >= 0

The total number of credit transactions.

creditTotals
required
integer
int64 >= 0 <= 999999999

The total value of all credit transactions in minor currency units.

debitCount
required
integer
int64 >= 0

The total number of debit transactions.

debitTotals
required
integer
int64 >= 0 <= 999999999

The total value of all credit transactions in minor currency units.

Additional properties are allowed.

Additional items are allowed.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payment Reports

Examples

PaymentReportBatchResponseMessage
Payload
{
  "paypoint": {
    "paypointId": "INST001",
    "terminalId": "987654321"
  },
  "batchNumber": 541505,
  "currencyCode": "GBP",
  "saleCount": 71,
  "refundCount": 8,
  "saleTotalAmount": 24509900,
  "refundTotalAmount": 4795900,
  "batchReport": {
    "fcr": 541505,
    "reportDate": "2019-08-24T14:15:22Z",
    "report": [
      {
        "cardScheme": "Visa",
        "creditCount": 7,
        "creditTotals": 4726400,
        "debitCount": 33,
        "debitTotals": 20372600
      }
    ]
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/payment/report/offline

Request details of stored offline transactions, by sending a message to the STOMP destination /v1/payment/report/offline.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Report Offline Request Message PaymentReportOfflineRequestMessage

The message to request details of stored offline transactions.

Payload
object

The message to request details for offline stored transactions.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payment Reports

Examples

PaymentReportOfflineRequestMessage
Payload
{}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/payment/report/offline

Receive the details of stored offline transactions, by subscribing to the STOMP destination /client/v1/payment/report/offline.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/payment/report/offline

Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

Payment Report Offline Response Message PaymentReportOfflineResponseMessage

The message to receive details of stored offline transactions.

Payload
object

The message to receive details for offline stored transactions.

paypoint
required
object

The paypoint associated the stored transactions.

paypointId
required
string
length <= 12 length >= 1

The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
length <= 10 length >= 8

The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.

count
required
integer
int64 >= 0

The total number transactions currently stored offline.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Payment Reports

Examples

PaymentReportOfflineResponseMessage
Payload
{
  "paypoint": {
    "paypointId": "INST001",
    "terminalId": "987654321"
  },
  "count": 5
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/device/status

Receive the latest status of the connected payment device, by subscribing to the STOMP destination /client/v1/device/status.

Subscribing to this destination requires an authenticated connection.

Clients will receive a message on this destination to confirm the current status of the payment device. Once received the client should disconnect from the web socket connection.

Accepts the following message:

Payment Device Status Message PaymentDeviceStatusMessage

The message to receive the status of the connected payment device.

Payload
object

Message confirming the status of the connected payment device.

status
required
string

The current status of the payment device.

Enum: "connected" "disconnected" "busy"
paypoint
object

The paypoint that the payment device is connected to.

paypointId
required
string
length <= 12 length >= 1

The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
length <= 10 length >= 8

The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.

paymentDevice

The connected payment device.

serialNumber
required
string
length <= 256 length >= 1

The serial number of the payment device.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Monitoring

Examples

PaymentDeviceStatusMessage
Payload
{
  "status": "connected",
  "paypoint": {
    "paypointId": "INST001",
    "terminalId": "987654321"
  },
  "paymentDevice": {
    "serialNumber": "A123-4567890"
  }
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/service/status

Receive the latest status of the payment service, by subscribing to the STOMP destination /client/v1/service/status.

Subscribing to this destination requires an authenticated connection.

Clients will receive a message on this destination to confirm the current status of the payment service. Once received the client must disconnect from the web socket connection.

Accepts the following message:

Payment Service Status Message PaymentServiceStatusMessage

The message to receive the status of the payment service.

Payload
object

Message confirming the status of the payment service.

status
required
string

The current status of the payment service.

Enum: "not-busy" "busy"

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Monitoring

Examples

PaymentServiceStatusMessage
Payload
{
  "status": "not-busy"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Pub /v1/device/restart

Request the restart of the payment device, by sending a message to the STOMP destination /v1/device/restart.

Publishing to this destination requires an authenticated connection.

Each request must be made in a new web socket connection.

Accepts the following message:

Payment Device Restart Request Message PaymentDeviceRestartRequestMessage

The message to request the restart of connected payment device.

Payload
object

The message to request the restart of connected payment device.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Monitoring

Examples

PaymentDeviceRestartRequestMessage
Payload
{}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/device/restart

Receive the details the device restart request, by subscribing to the STOMP destination /client/v1/device/restart.

Subscribing to this destination requires an authenticated connection.

Clients will receive a single reply on this destination in response to publishing on the following destinations:

  • /v1/device/restart

Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

Payment Device Restart Response Message PaymentDeviceRestartResponseMessage

The message to receive the result of the payment device restart request.

Payload
object

The message to receive the result of the payment device restart request.

result
required
string

The result of the request to restart the payment device.

Enum: "initiated" "restarted" "device-unavailable" "device-busy" "failed"

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Monitoring

Examples

PaymentDeviceRestartResponseMessage
Payload
{
  "result": "initiated"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Sub /client/v1/error

Receive errors that have occurring during processing a request, by subscribing to the STOMP destination /client/v1/error.

All errors indicate the end of the request processing, and can be received in response to any request. Once received the client must disconnect from the web socket connection.

Replies are always sent to the same client session that sent the original request, so connections must remain active for the duration of the request.

Accepts the following message:

Error Message ErrorMessage

The message to receive errors that occur while processing a request.

Payload
object

Message to communicate an error has occurred while processing the request.

code
required
string
length <= 20 length >= 1 must match ^[a-zA-Z0-9_\-]{1,20}$

A specific error code identifying the error scenario.

message
required
string
length <= 1000 length >= 1

A short message describing cause of error.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

Error Reporting

Examples

ErrorMessage
Payload
{
  "code": "10001",
  "message": "The required field 'paymentInstrument.type' is missing"
}
This example has been generated automatically.
Headers
{
  "x-wp-correlation-id": "e2c3ee97-e8c6-4850-a43f-23f40c2d6c77",
  "x-wp-message-id": "2bb6fd10-731f-4367-8a40-8f66007a4935",
  "x-wp-publisher-id": "bd2a863a-c86d-4218-8fe6-83514976c2fe"
}
This example has been generated automatically.

Messages

#1 POS Registration Request Message POSRegistrationRequestMessage

The message to register a new Point of Sale.

Payload
object

The message to register a new Point of Sale.

pointOfSaleId
required
string
length <= 6 length >= 6 must match ^[a-zA-Z0-9]{6}$

A unique identifier for the Point of Sale.

pointOfSaleReference
required
string
length <= 15 length >= 1 must match ^[a-zA-Z0-9]{1,15}$

A reference provided by the merchant for the Point of Sale.

pointOfSaleActivationCode
required
string
length <= 8 length >= 8 must match ^[a-zA-Z0-9]{8}$

A unique code to allow a Point of Sale to be activated.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#2 POS Registration Response Message POSRegistrationResponseMessage

The message confirming the registration of a new Point of Sale.

Payload
object

The message confirming the refresh of a Point of Sale registration.

pointOfSaleLicenseKey
required
string
length <= 2000 length >= 1 must match ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$

A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#3 POS Registration Refresh Request Message POSRegistrationRefreshRequestMessage

The message to refresh a Point of Sale registration.

Payload
object

The message to refresh a Point of Sale registration.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#4 POS Registration Refresh Response Message POSRegistrationRefreshResponseMessage

The message confirming the refresh of a Point of Sale registration.

Payload
object

The message confirming the refresh of a Point of Sale registration.

pointOfSaleLicenseKey
required
string
length <= 2000 length >= 1 must match ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$

A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#5 Payment Start Message PaymentStartMessage

The message to initiate a new payment.

Payload
object

Message to start a new payment.

paymentType
required
string

The type of payment.

  • sale - Authorise and settle a payment from a customer for goods/services.
  • refund - Authorise and settle a payment to a customer for the return of goods/services.
  • pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.
  • check-card - Check and retrieve details of the customer's card, without taking a payment.
  • check-card-payment - Check and retrieve details of the customer's card, and wait for the payment request on this card.
Enum: "sale" "refund" "pre-auth" "check-card" "check-card-payment"
merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

instruction
required
object

The instruction to start the payment.

value
required
object

The monetary value of the payment

amount
required
integer
int64 >= 0 <= 999999999

The amount for the payment requested by the merchant in minor currency units.

Additional properties are allowed.

narrative
object

A description of the payment to appear in customer's transaction statements.

Currently only supported for Alipay payments and requires an alphanumeric value.

line1
required
string
length <= 256 length >= 1

First line of the narrative.

Additional properties are allowed.

originalTransactionReference
string
length <= 256 length >= 1 must match ^[0-9a-zA-Z\!#\$%\(\)\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$

For cross-channel refunds, provide the transaction reference from the original sale being refunded.

Must contain only alpha numeric, or these special characters:

! # $ % ( ) * + , - . / : ; = ? @ [ \ ] _ ` { } ~

originalMerchantCode
string
length <= 30 length >= 1 must match ^[0-9a-zA-Z]{1,30}$

For cross-channel refunds, provide the merchant code used in the original sale being refunded.

originalGatewayTransactionReference
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

For refunding card sales, optionally provide the Payment Gateway Transaction Reference of the original sale being refunded.

For refunding Alipay sales, the original Gateway Transaction Reference is mandatory.

paymentInstrument
required
oneOf

The method by which the payment should be made.

0
object

Details for a payment instrument captured by a payment device.

This payment instrument is supported for sale, refund, pre-auth, check-card and check-card-payment payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/present" "card/keyed" "card/not-present"
isHandledOnline
boolean

Indicates whether the payment should be performed online or not. Defaults to true if omitted on a payment where it is applicable.

Currently, an online/offline choice is only applicable to the check-card and check-card-payment payment types, online/offline processing is determined automatically for all other payments regardless of this indicator.

Additional properties are allowed.

1
object

Details for keying card details into the payment device for a pre-approved referral transaction.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/keyed-recovery"
authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code for the payment obtained through a prior voice authorisation.

Optional for sale payments, not required for refund payments.

If omitted from a sale payment, the authorisation code will be requested via the voice-authorisation payment action request.

Additional properties are allowed.

2
object

Details for a token-based payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/token"
tokenId
required
string
length <= 21 length >= 15 must match ^[0-9a-zA-Z]{15,21}$

A token representing a card used in a payment. This will be returned in the result of a card payment if tokenisation is enabled, and can be sent in the request for payment with a card/token payment instrument.

The following token formats are supported:

  • Alphanumeric token – this token uses an alternating sequence of upper case letters and numbers, and is always 15 digits long. The letters I and O are never used due to their similarity with numbers. Useful if you do not require a numeric token, and prefer the token to be clearly distinguished from card numbers.
  • Wrapped luhn fail token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will not pass through luhn (modulus 10) checks. Useful if you want to avoid possible issues with regard to PCI DSS compliance checks, because tokens will not be mistaken for a card number.
  • Wrapped luhn pass token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will pass through luhn (modulus 10) checks. Useful if you have system validation that requires your token to be similar to a card number.
  • Format preserving token – this token uses a part of the card number used to create it, and is always 20 digits long. The first two digits are always 99. The next six digits are the first six numbers on the card used. The final four digits are the last four numbers on the card used.

Additional properties are allowed.

3
object

Details for a Alipay barcode payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "alipay/barcode"
barcode
required
string
length <= 24 length >= 16 must match ^[0-9]{16,24}$

The barcode value generated by the customer's Alipay app and scanned by the merchant.

sendAttempt
number
int32 >= 1

An incrementing count of the number of attempts to send this barcode for this payment.

Defaults to 1 if not provided.

quantity
number
int32 >= 1

Quantity of the commodity in the payment. This value is shown in the consumer's transaction records list from Alipay.

Defaults to 1 if not provided.

Additional properties are allowed.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#6 Payment Status Message PaymentStatusMessage

The message to communicate the real-time status of an in-flight payment.

Payload
object

Message with a notification about the payment flow which requires no action to be taken.

These can be displayed to the member of staff to inform them of the payment's progress.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

notificationText
required
string
length <= 256 length >= 1

Text describing an event occurring in the payment flow.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#7 Payment Action Request Message PaymentActionRequestMessage

The message to request an action to proceed with the payment.

Payload
object

Message with details of an action to completed by the merchant.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

data
required
oneOf

Description of the action required for the payment.

0
object

The merchant is required to perform voice authorisation.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "voice-authorisation"
merchant
required
object

Merchant identifiers to complete voice authorisation for this payment.

merchantId
required
string
length <= 10 length >= 8

The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.

referralContacts
required
array<object>

Referral contact details to complete voice authorisation for this payment.

Items:

0
object
method
required
string

The method of contact.

Enum: "phone-number"
value
required
string
length <= 255 length >= 1

The value contact method, e.g. the phone number.

Additional properties are allowed.

Additional items are allowed.

Additional properties are allowed.

1
object

Merchant is required to confirm the customer's signature.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "signature-verification"

Additional properties are allowed.

2
object

The merchant is required to approve the transaction based on AVS check results.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "avs-confirmation"
avsResults
required
object

Results of the payment's AVS check to be approved by the merchant.

isCvvMatch
required
string

Indicates if the CVV of the card matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"
isAddressLineMatch
required
string

Indicates if the cardholder address line(s) matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"
isPostalCodeMatch
required
string

Indicates if the cardholder postal code matched during the AVS check.

Enum: "matched" "not-matched" "not-checked"

Additional properties are allowed.

Additional properties are allowed.

3
object

Merchant is required provide a cashback amount.

action
required
string

The action which is required to be performed to continue the payment.

Enum: "cashback-amount"
maximumCashbackAmount
required
integer
int64 >= 0 <= 999999999

The maximum allowed amount of cash back available for the payment, in minor currency units.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#8 Payment Action Complete Message PaymentActionCompleteMessage

The message to confirm the action for the payment has been completed.

Payload
object

Message with details of the action completed by the merchant.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

data
required
oneOf

The action taken by the POS to proceed with the payment.

0
object

Voice authorisation data.

action
string

The action which has been performed to continue the payment.

Enum: "voice-authorisation"
authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code provided by the issuer, omitted if the transaction is not authorised.

Additional properties are allowed.

1
object

Signatured verfication data.

action
required
string

The action which has been performed to continue the payment.

Enum: "signature-verification"
isSignatureVerified
required
boolean

Whether the signature was verified.

Additional properties are allowed.

2
object

AVS confirmation data.

action
required
string

The action which has been performed to continue the payment.

Enum: "avs-confirmation"
isAvsConfirmed
required
boolean

Whether AVS results are confirmed.

Additional properties are allowed.

3
object

Cashback data.

action
required
string

The action which has been performed to continue the payment.

Enum: "cashback-amount"
cashbackAmount
required
integer
int64 >= 0 <= 999999999

The amount of cash back to be included in the payment, in minor currency units.

Additional properties are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#9 Payment Abort Message PaymentAbortMessage

The message to abort a check card payment.

Payload
object

Message to abort a check card payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#10 Payment Receipt Message PaymentReceiptMessage

The message to receive a payment receipt.

Payload
object

Message with a receipt for a payment.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

type
required
string

The type of receipt.

  • customer - Customer copy of a receipt.
  • merchant - Merchant copy of a receipt.
Enum: "customer" "merchant"
content
required
string

Base64 representation of the UTF-8 encoded content of the receipt.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#11 Payment Result Message PaymentResultMessage

The message to communicate the result of a completed payment.

Payload
object

Message with payment results.

payments
required
array<object>

The list of completed payments, typically 1 payment but will be multiple in the case of a split payment done on the payment device.

Items:

0
object

Full details of a completed payment.

paymentType
required
string

The type of payment that was requested.

  • sale - Authorise and settle a payment from a customer for goods/services.
  • refund - Authorise and settle a payment to a customer for the return of goods/services.
  • pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.
  • check-card - Check and retrieve details of the customer's card, without taking a payment.
  • check-card-payment - Check and retrieve details of the customer's card, and wait for the payment request on this card.
  • cancel - The cancellation of a previously requested sale, refund, or pre-auth.
  • settle - The settlement of a previously requested pre-auth.
Enum: "sale" "refund" "pre-auth" "check-card" "check-card-payment" "cancel" "settle"
transactionDateTime
required
string
date-time

The date-time at which the transaction was processed. Represented as a date-time according to RFC 3339, section 5.6, including the relevant time zone.

outcome
required
string

The outcome of the payment request.

  • succeeded - The request was processed successfully.
  • refused - The payment request was refused by the payment device, acquirer or issuer.
  • pending - The final outcome of the request is not yet known.
  • failed - The request could not be processed.
Enum: "succeeded" "refused" "pending" "failed"
result
required
string

The code representing the result of payment request.

Succeeded

  • authorised-online - The payment was authorised by card issuer, payment scheme or your acquirer.
  • authorised-offline - The payment was accepted locally by IPS.
  • authorised-referral - The payment was accepted locally by IPS on entry of a referral code by the POS attendant.
  • keyed-recovery-success - The keyed recovery payment was successfully stored by the Integrated POS gateway and will be submitted for settlement to your acquirer.
  • pre-auth-completed - The previously authorised transaction has been successfully flagged for settlement and will be submitted to your acquirer.
  • succeeded - The abort, cancel or settle request was processed successfully.

Refused

  • refused-online - The payment was refused by card issuer, payment scheme or your acquirer.
  • refused-offline - The payment was refused locally by IPS.
  • refused-online-capture-card - The payment was refused by card issuer, payment scheme or your acquirer and the card should be kept by the merchant.
  • refused-avs-required - The payment was refused by card issuer, payment scheme or your acquirer because AVS was required but not provided.

Pending

  • started - The payment process has started.
  • in-progress - The payment authorisation is in progress.
  • auth-completed - The payment authorisation process has completed. At this stage the payment record may not yet be saved to the Integrated POS gateway.

Failed

  • cancelled - The request process was cancelled by the merchant or customer.
  • aborted - The request was has been aborted unexpectedly.
  • aborted-device-unavailable - The request been aborted because the payment device is unavailable.
  • aborted-busy - The request been aborted because the system is currently busy.
  • rejected-pre-auth - The pre-authorisation request was rejected.
  • rejected-card-number-not-matched - The request was rejected because the card number did not match the expected value.
  • rejected-card-expiry-date-not-matched - The request was rejected because the card expiry date did not match the expected value.
  • rejected-card-not-accepted - The request was rejected because the card use is not accepted by the system.
  • invalid-transaction-state - The request cannot be performed on the transaction in its current state.
  • invalid-operation - The requested operation is not supported.
  • invalid-gateway-transactions-reference - The request cannot be processed because the gateway transaction reference is not recognised.
  • invalid-merchant - The request cannot be processed as the configured merchant details are invalid.
  • invalid-terminal - The request cannot be processed as the configured terminal details are invalid.
  • invalid-merchant-status - The request cannot be processed as merchant is not active.
  • invalid-card-number - The request cannot be processed as the card number is invalid.
  • invalid-expired-card - The request cannot be processed as the card has expired.
  • invalid-issue-number - The request cannot be processed as the card issuer number is invalid.
  • invalid-card-expiry-date - The request cannot be processed as the card expiry date is invalid.
  • invalid-amount - The requested sale or refund amount is not valid.
  • denied-transaction - The transaction was denied.
  • denied-cashback - The request for cashback was denied.
  • pre-valid-card - The request cannot be processed as the card is not yet valid.
  • failed - The request could not be processed.
Enum: "authorised-online" "authorised-offline" "authorised-referral" "keyed-recovery-success" "pre-auth-completed" "succeeded" "refused-online" "refused-offline" "refused-online-capture-card" "refused-avs-required" "started" "in-progress" "auth-completed" "cancelled" "aborted" "aborted-device-unavailable" "aborted-busy" "rejected-pre-auth" "rejected-card-number-not-matched" "rejected-card-expiry-date-not-matched" "rejected-card-not-accepted" "invalid-transaction-state" "invalid-operation" "invalid-gateway-transactions-reference" "invalid-merchant" "invalid-terminal" "invalid-merchant-status" "invalid-card-number" "invalid-expired-card" "invalid-issue-number" "invalid-card-expiry-date" "invalid-amount" "denied-transaction" "denied-cashback" "pre-valid-card" "failed"
merchant
allOf

Details of the merchant.

0
object

Identifies the merchant that originates the payment.

merchantId
required
string
length <= 10 length >= 8

The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.

1
object

Full details of the merchant.

name
required
string
length <= 40 length >= 1

The merchant's name.

address
required
object

The merchant's address.

line1
string
length <= 140 length >= 1

Line 1 of the address

line2
string
length <= 140 length >= 1

Line 2 of the address

line3
string
length <= 140 length >= 1

Line 3 of the address

city
string
length <= 140 length >= 1

City of the address

state
string
length <= 140 length >= 1

State/County/Region of the address

postalCode
string
length <= 8 length >= 1

Postal code (Post/Zip code) of the address

countryCode
string
length <= 2 length >= 2

The 2-letter ISO-3166-1 country code of the address

Additional properties are allowed.

Additional properties are allowed.

paypoint
required
object

The paypoint the request has been performed on.

paypointId
required
string
length <= 12 length >= 1

The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
length <= 10 length >= 8

The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.

value
object

The monetary value of the payment.

amount
required
integer
int64 >= 0 <= 999999999

The full amount the customer's card has been charged or refunded including any gratuity, donations or cash back, in minor currency units.

currencyCode
required
string
length <= 3 length >= 3

The 3-letter ISO 4217 currency code which amounts are specified in.

cashbackAmount
integer
int64 >= 0 <= 999999999

The amount of cash back included in the payment, in minor currency units.

gratuityAmount
integer
int64 >= 0 <= 999999999

The amount of gratuity included in the payment, in minor currency units.

donationAmount
integer
int64 >= 0 <= 999999999

The amount of donation included in the payment, in minor currency units.

dcc
object

Data for Dynamic Currency Conversion if relevant to the payment.

convertedCurrencyCode
required
string
length <= 3 length >= 3

The 3-letter ISO 4217 currency code which the amount was converted to.

convertedAmount
required
integer
int64 >= 0 <= 999999999

The amount of the payment converted into the currency in minor currency units.

conversionRate
required
number
double >= 0

The conversion rate from the merchant's currency to the cardholder's local currency.

Additional properties are allowed.

Additional properties are allowed.

merchantTransactionReference
required
string
length <= 30 length >= 1 must match ^[a-zA-Z0-9_\\-]{1,30}$

The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric, hypen (-) and underscore (_) characters.

gatewayTransactionReference
string
length <= 22 length >= 12 must match ^[a-zA-Z0-9]{12,22}$

The transaction reference generated by the payment gateway to uniquely identify the payment. This will be available for any payment which has been processed online.

eftSequenceNumber
integer
int64 >= 1

The transaction sequence number.

retrievalReferenceNumber
integer
int64 >= 1 <= 9999999999

The retrieval reference number for the transaction.

receiptNumber
integer
int64 >= 1 <= 9999999999

The number of the receipt to be issued.

receiptRetentionReminder
string
length <= 50 length >= 1

A retention reminder to include on receipts.

receiptCustomerDeclaration
string
length <= 50 length >= 1

A customer declaration to include on receipts.

taxFreeVoucher
string

Base64 representation of the UTF-8 encoded content of the voucher.

The first 2 characters of each line a print command, followed by the text to print.

The print commands are:

  • 01 - Print the Premier taxfree logo bitmap
  • 02 - Print large bold text, followed by a carriage return
  • 03 - Print large underlined text, followed by a carriage return
  • 04 - Print normal underlined text, followed by a carriage return
  • 05 - Print normal text, followed by a carriage return
  • 06 - Print normal sized bold text, followed by a carriage return
  • 07 - Print normal sized wide text, followed by a carriage return
  • 08 - Print normal right aligned text, followed by a carriage return
  • 09 - Print normal centre aligned text, followed by a carriage return
  • 10 - Print large bold centered text, followed by a carriage return
  • 11 - Print the data as a 'Interleaved 2 of 5' barcode
  • 12 - Print carriage return
  • 13 - Auto cut paper
  • 50 - Load another voucher
  • 51 - Print copy
  • 61 - The remainder of the text after the print code is encrypted and base64 encoded. Decrypt it and then print normal text, followed by a carriage return
paymentInstrument
oneOf

The method by which the payment was made.

0
object

Details for a card-based payment instrument.

This payment instrument is supported for sale, refund, pre-auth, check-card and check-card-payment payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "card/present" "card/keyed" "card/not-present" "card/token"
card
object

Data for the card used in the payment.

tokenId
string
length <= 21 length >= 15 must match ^[0-9a-zA-Z]{15,21}$

A token representing a card used in a payment. This will be returned in the result of a card payment if tokenisation is enabled, and can be sent in the request for payment with a card/token payment instrument.

The following token formats are supported:

  • Alphanumeric token – this token uses an alternating sequence of upper case letters and numbers, and is always 15 digits long. The letters I and O are never used due to their similarity with numbers. Useful if you do not require a numeric token, and prefer the token to be clearly distinguished from card numbers.
  • Wrapped luhn fail token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will not pass through luhn (modulus 10) checks. Useful if you want to avoid possible issues with regard to PCI DSS compliance checks, because tokens will not be mistaken for a card number.
  • Wrapped luhn pass token – this token consists of between 16 and 21 digits, and the first two digits are always 99. These tokens will pass through luhn (modulus 10) checks. Useful if you have system validation that requires your token to be similar to a card number.
  • Format preserving token – this token uses a part of the card number used to create it, and is always 20 digits long. The first two digits are always 99. The next six digits are the first six numbers on the card used. The final four digits are the last four numbers on the card used.
cardNumber
string
length <= 19 length >= 13 must match ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$

The Primary Account Number of the card. For whitelisted cards the full card number can be returned, for all other cards the number is masked. The first 6 digits and last 4 digits are returned, the middle digits are replaced by X.

expiryDate
object

The expiry date of the card. Omitted if the card does not have an expiry date.

month
required
integer
int32 >= 1 <= 12
year
required
integer
int32 >= 0 <= 99

Additional properties are allowed.

track2Data
string
length <= 40 length >= 7 must match ^\;([0-9]{1,19})\=([0-9]{4}|\=)([0-9]{3}|\=)([^\?]+)\?$

The Track 2 data of the card as defined by ISO 7813. Available for whitelisted BIN ranges for check-card and check-card-payment transactions.

type
string

Indicator for the type of card. This field is omitted if the card type is unknown.

  • fuel - The card used was a fuel card.
  • debit - The card used was a debit card.
  • credit - The card used was a credit card.
Enum: "fuel" "debit" "credit"
issuerCode
string
length <= 256 length >= 1 must match ^[a-zA-Z0-9\-]{1,256}$

A reference which can be used to identify the issuer of card.

Major card schemes
  • amex - Amex
  • bank-of-america - Bank of America
  • dankort - DANKORT
  • diners - Diners Club International
  • discover - Discover
  • jcb - JCB
  • maestro-uk - UK Maestro
  • maestro - Maestro
  • mastercard-debit - Debit Mastercard
  • mastercard-purchasing - Mastercard Purchasing
  • mastercard - Mastercard
  • us-debit - US Debit
  • visa-debit - VISA DEBIT
  • visa-electron-uk - UK Electron
  • visa-purchasing - Visa Purchasing
  • visa - Visa
  • visa-atm - VISA ATM
Store cards and gift cards
  • arval-phh - ARVAL PHH
  • flexecash-love-2-reward - Flexecash Love 2 Reward
  • harvey-nichols - HN PLCC
  • harvey-nichols-mastercard - HN Mastercard
  • newday-mastercard - Newday MasterCard
  • newday-staff - Newday Staff Card
  • newday-store - Newday Store PLC
  • newday-temporary - Newday Temporary
  • pps-gift - PPS Gift Card
  • tesco-clubcard - Tesco Clubcard

New values may be added without a software release.

countryCode
string
length <= 3 length >= 3 must match ^[0-9]{3}$

The 3-digit numeric ISO 3166 code for the country the card was issued in.

panSequenceNumber
string
length <= 2 length >= 2 must match ^[0-9]{2}$

The PAN Sequence number for ICC payments, and the card's issue number for swiped UK Maestro/Solo card payments.

applicationLabel
string
length <= 16 length >= 1

The mnemonic associated with the application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

applicationIdentifier
string
length <= 32 length >= 10 must match ^[A-Z0-9]{10,32}$

The application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

Note – For VISA Contactless Cards, truncated EMV Card Data Element Application Identifier (AID) will be received instead Extended AID.

applicationEffectiveDate
string
date

The date from which the application can be used. Represented as a full-date according to RFC 3339, section 5.6.

Additional properties are allowed.

posEntryMode
string
must match ^[a-zA-Z0-9\-]{1,50}$

The method of reading the card. The current possible values are:

  • keyed
  • magstripe
  • integrated-circuit-chip
  • contactless-chip
  • contactless-magstripe
  • contactless-on-device
  • cardholder-not-present

New values may be added in future without a software release.

cardVerificationMethod
string
must match ^[a-zA-Z0-9\-]{1,50}$

The verification method used for the cardholder. The current possible values are:

  • signature
  • pin-or-consumer-device
  • pin-and-signature
  • cardholder-not-present
  • none
  • unknown

New values may be added in future without a software release.

isHandledOnline
boolean

Indicates whether the payment request was handled online or not.

Currently, this is only applicable to check-card and check-card-payment payment types.

authorisation
object

Data for the authorisation of the payment.

authorisationCode
string
length <= 6 length >= 2 must match ^[0-9a-zA-Z]{2,6}$

The authorisation code generated by the issuer for an authorised payment.

cvvResponseData
string
length <= 6 length >= 6 must match ^[0-9A-F]{6}$

Additional response data containing the CVV response.

Additional properties are allowed.

debug
object
transactionStatusInfo
string
length <= 4 length >= 1 must match ^[0-9A-F]{1,4}$

Transaction Status Information (TSI), present only in case of an ICC payment. Used for debug purpose only.

transactionVerificationResults
string
length <= 10 length >= 1 must match ^[0-9A-F]{1,10}$

Transaction Verification Results (TVR), present only in case of an ICC payment. Used for debug purpose only.

Additional properties are allowed.

Additional properties are allowed.

1
object

Details for a Alipay barcode payment instrument.

This payment instrument is supported for sale and refund payment types.

type
required
string

The type of payment instrument. This will also dictate which other payment instrument fields are required to fulfil the payment.

Enum: "alipay/barcode"
barcode
required
string
length <= 24 length >= 16 must match ^[0-9]{16,24}$

The barcode value generated by the customer's Alipay app and scanned by the merchant.

Additional properties are allowed.

Additional properties are allowed.

Additional items are allowed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid

A UUID that identifies the message. Can be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
length <= 256 length >= 1

A unique ID that identifies the sender of the message. This should be a UUID generated by the POS application or a MAC address of the POS to maximise uniqueness.

Additional properties are allowed.

#12 Payment Complete Message PaymentCompleteMessage

The message communicate that the payment process is complete.

Payload
object

Message confirming the payment process has completed.

Additional properties are allowed.

Headers
object
x-wp-correlation-id
string
uuid

A UUID that links reply messages with their original request. Multiple replies may be linked to a single request.

x-wp-message-id
string
uuid