Integrated Payment Server - Payment API 4.0.1 documentation

Integrated Payment Server - Payment API 4.0.1

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

#Point of Sale Registration
#Payments
#Payment Reports
#Monitoring
#Error Reporting

Servers

wss://{host}:{port}/ipc-app/payment/{paypointId}stomp 1.2on-premise
On-premise installation of IPS.
host
required
string
The IP address or domain name of the host running IPS.

Default value:"<machine-hostname>"
port
required
string
The port on which the IPS application is listening.

Default value:"7080"
paypointId
required
string
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).

Examples values:
"INST001"

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.
- #Point of Sale Registration
Accepts the following message:
POS Registration Request MessagePOSRegistrationRequestMessage
application/json
The message to register a new Point of Sale.

object
The message to register a new Point of Sale.

pointOfSaleId
required
string
must match: ^[a-zA-Z0-9]{6}$6 characters
A unique identifier for the Point of Sale.

pointOfSaleReference
required
string
must match: ^[a-zA-Z0-9]{1,15}$[ 1 .. 15 ] characters
A reference provided by the merchant for the Point of Sale.

pointOfSaleActivationCode
required
string
must match: ^[a-zA-Z0-9]{8}$8 characters
A unique code to allow a Point of Sale to be activated.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "pointOfSaleId": "D45FGT", "pointOfSaleReference": "POS123", "pointOfSaleActivationCode": "AV46HTR3" }

This example has been generated automatically.
{ "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.
- #Point of Sale Registration
Accepts the following message:
POS Registration Response MessagePOSRegistrationResponseMessage
application/json
The message confirming the registration of a new Point of Sale.

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

pointOfSaleLicenseKey
required
string
must match: ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$[ 1 .. 2000 ] characters
A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "pointOfSaleLicenseKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }

This example has been generated automatically.
{ "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.
- #Point of Sale Registration
Accepts the following message:
POS Registration Refresh Request MessagePOSRegistrationRefreshRequestMessage
application/json
The message to refresh a Point of Sale registration.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{}

This example has been generated automatically.
{ "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.
- #Point of Sale Registration
Accepts the following message:
POS Registration Refresh Response MessagePOSRegistrationRefreshResponseMessage
application/json
The message confirming the refresh of a Point of Sale registration.

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

pointOfSaleLicenseKey
required
string
must match: ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$[ 1 .. 2000 ] characters
A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "pointOfSaleLicenseKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }

This example has been generated automatically.
{ "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.

Examples:

Card present sale

Account verification request, storing the card on file for a future recurring payment

Card token sale

Card keyed recovery sale

Card present refund

Card present check card only

Card present check card, wait for payment

Card present pre-authorisation
- #Payments
Accepts the following message:
Payment Start MessagePaymentStartMessage
application/json
The message to initiate a new payment.

object
Message to start a new payment.

Examples values:
{"paymentType":"sale","merchantTransactionReference":"MS1231000001","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000001","instruction":{"value":{"amount":0},"paymentInstrument":{"type":"card/present","tokenPurpose":"recurring"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000002","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/token","tokenId":"A1B2C3D4E5F6G7H"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000004","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/keyed-recovery","authCode":"1234AA"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"check-card","merchantTransactionReference":"MS1231000007","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present","isHandledOnline":true}}}
{"paymentType":"check-card-payment","merchantTransactionReference":"MS1231000008","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present","isHandledOnline":true}}}
{"paymentType":"pre-auth","merchantTransactionReference":"MS1231000009","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
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.

Allowed values:
"sale"
"refund"
"pre-auth"
"check-card"
"check-card-payment"
merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

required
object
The instruction to start the payment.

required
object
The monetary value of the payment

amount
required
integer
format: int64[ 0 .. 999999999 ]
The amount for the payment requested by the merchant in minor currency units.

Additional properties are allowed.
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
[ 1 .. 256 ] characters
First line of the narrative.

Additional properties are allowed.
originalTransactionReference
string
must match: ^[0-9a-zA-Z\!#\$%\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$[ 1 .. 256 ] characters
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
must match: ^[0-9a-zA-Z]{1,30}$[ 1 .. 30 ] characters
For cross-channel refunds, provide the merchant code used in the original sale being refunded.

originalGatewayTransactionReference
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
The PGTR is relevant only for refunds with the Union Pay and Alipay. It has no effect except when used as follows –

For refunding Union Pay or Alipay sales, the original Gateway Transaction Reference is mandatory. If original Gateway Transaction Reference is not provided, then transaction will be declined.

For refund a token the PGTR may be provided as a reference to the original Sale. When the PGTR is provided in this way then the original amount is checked, and the refund is allowed if the refund amount is less than or equal to the sale amount. If the refund amount is greater than the sale amount, then the refund is declined.

The PGTR is optional for token refund. If it is not provided, then the refund amount is accepted without any reference to previous transaction.

required
oneOf
The method by which the payment should be made.

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.

For card/not-present payment instrument for sale transaction card details requested by the PED are PAN, Expiry date, CVC and AVS details as configured for the Paypoint (House number and/or numeric part of postcode).

For card/not-present payment instrument for refund transaction card details requested by the PED are PAN and Expiry date.

Allowed values:
"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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
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.

Allowed values:
"card/keyed-recovery"
authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
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.

Allowed values:
"card/token"
tokenId
required
string
must match: ^[0-9a-zA-Z]{15,21}$[ 15 .. 21 ] characters
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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
#1 Example
{ "paymentType": "sale", "merchantTransactionReference": "MS1231000001", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/present" } } }

#2 Example
{ "paymentType": "sale", "merchantTransactionReference": "MS1231000001", "instruction": { "value": { "amount": 0 }, "paymentInstrument": { "type": "card/present", "tokenPurpose": "recurring" } } }

#3 Example
{ "paymentType": "sale", "merchantTransactionReference": "MS1231000002", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/token", "tokenId": "A1B2C3D4E5F6G7H" } } }

#4 Example
{ "paymentType": "sale", "merchantTransactionReference": "MS1231000004", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/keyed-recovery", "authCode": "1234AA" } } }

#5 Example
{ "paymentType": "refund", "merchantTransactionReference": "MS1231000005", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/present" } } }

#6 Example
{ "paymentType": "check-card", "merchantTransactionReference": "MS1231000007", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/present", "isHandledOnline": true } } }

#7 Example
{ "paymentType": "check-card-payment", "merchantTransactionReference": "MS1231000008", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/present", "isHandledOnline": true } } }

#8 Example
{ "paymentType": "pre-auth", "merchantTransactionReference": "MS1231000009", "instruction": { "value": { "amount": 1099 }, "paymentInstrument": { "type": "card/present" } } }

{ "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.
- #Payments
Accepts the following message:
Payment Status MessagePaymentStatusMessage
application/json
The message to communicate the real-time status of an in-flight payment.

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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

notificationText
required
string
[ 1 .. 256 ] characters
Text describing an event occurring in the payment flow.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "notificationText": "PLEASE INSERT CARD" }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Action Request MessagePaymentActionRequestMessage
application/json
The message to request an action to proceed with the payment.

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

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

required
oneOf
Description of the action required for the payment.

object
The merchant is required to perform voice authorisation.

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

Allowed values:
"voice-authorisation"
required
object
Merchant identifiers to complete voice authorisation for this payment.

merchantId
required
string
[ 8 .. 10 ] characters
The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.
required
array<object>
Referral contact details to complete voice authorisation for this payment.

method
required
string
The method of contact.

Allowed values:
"phone-number"
value
required
string
[ 1 .. 255 ] characters
The value contact method, e.g. the phone number.

Additional properties are allowed.
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.

Allowed values:
"signature-verification"
Additional properties are allowed.
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.

Allowed values:
"avs-confirmation"
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.

Allowed values:
"matched"
"not-matched"
"not-checked"
isAddressLineMatch
required
string
Indicates if the cardholder address line(s) matched during the AVS check.

Allowed values:
"matched"
"not-matched"
"not-checked"
isPostalCodeMatch
required
string
Indicates if the cardholder postal code matched during the AVS check.

Allowed values:
"matched"
"not-matched"
"not-checked"
Additional properties are allowed.
Additional properties are allowed.
object
Merchant is required provide a cashback amount.

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

Allowed values:
"cashback-amount"
maximumCashbackAmount
required
integer
format: 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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "data": { "action": "voice-authorisation", "merchant": { "merchantId": "12345678" }, "referralContacts": [ { "method": "phone-number", "value": "02011112222" } ] } }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Action Complete MessagePaymentActionCompleteMessage
application/json
The message to confirm the action for the payment has been completed.

object
Message with details of the action completed by the merchant.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

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

object
Voice authorisation data.

action
string
The action which has been performed to continue the payment.

Allowed values:
"voice-authorisation"
authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
The authorisation code provided by the issuer, omitted if the transaction is not authorised.

Additional properties are allowed.
object
Signatured verfication data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"signature-verification"
isSignatureVerified
required
boolean
Whether the signature was verified.

Additional properties are allowed.
object
AVS confirmation data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"avs-confirmation"
isAvsConfirmed
required
boolean
Whether AVS results are confirmed.

Additional properties are allowed.
object
Cashback data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"cashback-amount"
cashbackAmount
required
integer
format: 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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "data": { "action": "voice-authorisation", "authorisationCode": "12345" } }

This example has been generated automatically.
{ "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 sale, refund or 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 sale, refund or check card payment request to cancel the transaction before starting any card interaction with the Pinpad.
- #Payments
Accepts the following message:
Payment Abort MessagePaymentAbortMessage
application/json
The message to abort a check card payment.

object
Message to abort a check card payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF" }

This example has been generated automatically.
{ "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.
- #Payments
- #Manage Existing Payments
Accepts the following message:
Payment Receipt MessagePaymentReceiptMessage
application/json
The message to receive a payment receipt.

object
Message with a receipt for a payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

type
required
string
The type of receipt.

customer - Customer copy of a receipt.

merchant - Merchant copy of a receipt.

Allowed values:
"customer"
"merchant"
content
required
string
Base64 representation of the UTF-8 encoded content of the receipt.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "type": "customer", "content": "RVhBTVBMRSBSRUNFSVBUIENPTlRFTlQ=" }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Result MessagePaymentResultMessage
application/json
The message to communicate the result of a completed payment.

object
Message with payment results.

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.

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.

Allowed values:
"sale"
"refund"
"pre-auth"
"check-card"
"check-card-payment"
"cancel"
"settle"
transactionDateTime
required
string
format: 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.

Allowed values:
"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.

refused-do-not-reattempt - The payment was refused and no further attempts should be made with the card. 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.

Allowed values:
"authorised-online"
"authorised-offline"
"authorised-referral"
"keyed-recovery-success"
"pre-auth-completed"
"succeeded"
"refused-online"
"refused-offline"
"refused-online-capture-card"
"refused-avs-required"
"refused-do-not-reattempt"
"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"
allOf
Details of the merchant.

object
Identifies the merchant that originates the payment.

merchantId
required
string
[ 8 .. 10 ] characters
The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.
object
Full details of the merchant.

name
required
string
[ 1 .. 40 ] characters
The merchant's name.

required
object
The merchant's address.

line1
string
[ 1 .. 140 ] characters
Line 1 of the address

line2
string
[ 1 .. 140 ] characters
Line 2 of the address

line3
string
[ 1 .. 140 ] characters
Line 3 of the address

city
string
[ 1 .. 140 ] characters
City of the address

state
string
[ 1 .. 140 ] characters
State/County/Region of the address

postalCode
string
[ 1 .. 8 ] characters
Postal code (Post/Zip code) of the address

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

Additional properties are allowed.
Additional properties are allowed.
required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
object
The monetary value of the payment.

amount
required
integer
format: 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
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

cashbackAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of cash back included in the payment, in minor currency units.

gratuityAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of gratuity included in the payment, in minor currency units.

donationAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of donation included in the payment, in minor currency units.

object
Data for Dynamic Currency Conversion if relevant to the payment.

convertedCurrencyCode
required
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

convertedAmount
required
integer
format: int64[ 0 .. 999999999 ]
The amount of the payment converted into the currency in minor currency units.

conversionRate
required
number
format: 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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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
format: int64>= 1
The transaction sequence number.

retrievalReferenceNumber
integer
format: int64[ 1 .. 9999999999 ]
The retrieval reference number for the transaction.

receiptNumber
integer
format: int64[ 1 .. 9999999999 ]
The number of the receipt to be issued.

receiptRetentionReminder
string
[ 1 .. 50 ] characters
A retention reminder to include on receipts.

receiptCustomerDeclaration
string
[ 1 .. 50 ] characters
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

oneOf
The method by which the payment was made.

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.

Allowed values:
"card/present"
"card/keyed"
"card/not-present"
"card/token"
object
Data for the card used in the payment.

tokenId
string
must match: ^[0-9a-zA-Z]{15,21}$[ 15 .. 21 ] characters
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
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
track2Data
string
must match: ^\;([0-9]{1,19})\=([0-9]{4}|\=)([0-9]{3}|\=)([^\?]+)\?$[ 7 .. 40 ] characters
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.

Allowed values:
"fuel"
"debit"
"credit"
issuerCode
string
must match: ^[a-zA-Z0-9\-]{1,256}$[ 1 .. 256 ] characters
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
must match: ^[0-9]{3}$3 characters
The 3-digit numeric ISO 3166 code for the country the card was issued in.

panSequenceNumber
string
must match: ^[0-9]{2}$2 characters
The PAN Sequence number for ICC payments, and the card's issue number for swiped UK Maestro/Solo card payments.

applicationLabel
string
[ 1 .. 16 ] characters
The mnemonic associated with the application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

applicationIdentifier
string
must match: ^[A-Z0-9]{10,32}$[ 10 .. 32 ] characters
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
format: 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.

object
The balance of the card/account.

formattedAmount
string
[ 1 .. 100 ] characters
The balance amount formatted for display.

Additional properties are allowed.
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.

object
Data for the authorisation of the payment.

authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
The authorisation code generated by the issuer for an authorised payment.

cvvResponseData
string
must match: ^[0-9A-F]{6}$6 characters
Additional response data containing the CVV response.

Additional properties are allowed.
object
transactionStatusInfo
string
must match: ^[0-9A-F]{1,4}$[ 1 .. 4 ] characters
Transaction Status Information (TSI), present only in case of an ICC payment. Used for debug purpose only.

transactionVerificationResults
string
must match: ^[0-9A-F]{1,10}$[ 1 .. 10 ] characters
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.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "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": "GBP", "convertedAmount": 3349, "conversionRate": 1.11647 } }, "merchantTransactionReference": "MS123A54B3DF", "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", "balance": { "formattedAmount": "£25.00" }, "isHandledOnline": true, "authorisation": { "authorisationCode": "12345", "cvvResponseData": "422800" }, "debug": { "transactionStatusInfo": "F800", "transactionVerificationResults": "4000008000" } } } ] }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Complete MessagePaymentCompleteMessage
application/json
The message communicate that the payment process is complete.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{}

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Settle MessagePaymentSettleMessage
application/json
The message to settle a pre-authorised payment.

object
Message to settle a previously requested pre-auth payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
required
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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.

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

amount
required
integer
format: int64[ 1 .. 999999999 ]
The amount for the payment requested to be settled by the merchant in minor currency units.

Additional properties are allowed.
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.

Allowed values:
"card"
cardNumber
required
string
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "gatewayTransactionReference": "1234567890AB", "value": { "amount": 1099 }, "paymentInstrument": { "type": "card", "cardNumber": "492949XXXXXX0002", "cardExpiryDate": { "month": 12, "year": 20 } } }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Cancel MessagePaymentCancelMessage
application/json
The message to cancel a previous payment.

object
Message to cancel a payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
required
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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.

required
oneOf
The method by which the original payment was made.

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.

Allowed values:
"card"
cardNumber
required
string
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "gatewayTransactionReference": "1234567890AB", "paymentInstrument": { "type": "card", "cardNumber": "492949XXXXXX0002", "cardExpiryDate": { "month": 12, "year": 20 } } }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Query Result MessagePaymentQueryResultMessage
application/json
The message to query the result of the last payment.

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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF" }

This example has been generated automatically.
{ "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.
- #Payments
Accepts the following message:
Payment Query Receipt MessagePaymentQueryReceiptMessage
application/json
The message to query the receipt of the last payment.

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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

type
required
string
The type of receipt.

customer - Customer copy of a receipt.

merchant - Merchant copy of a receipt.

Allowed values:
"customer"
"merchant"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "merchantTransactionReference": "MS123A54B3DF", "type": "customer" }

This example has been generated automatically.
{ "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.
- #Payment Reports
Accepts the following message:
Payment Report Batch Request MessagePaymentReportBatchRequestMessage
application/json
The message to request an X or Z Report for the transactions in the current batch.

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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "closeBatch": false }

This example has been generated automatically.
{ "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.
- #Payment Reports
Accepts the following message:
Payment Report Batch Response MessagePaymentReportBatchResponseMessage
application/json
The message to receive an X or Z Report for the transactions in the current batch.

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

required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
batchNumber
required
integer
format: int64[ 0 .. 99999999 ]
The current batch number.

currencyCode
required
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

saleCount
required
integer
format: int64>= 0
The total number of sales in the batch.

refundCount
required
integer
format: int64>= 0
The total number of sales in the batch.

saleTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all sales in the batch in minor currency units.

refundTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all refunds in the batch in minor currency units.

required
object
A report for the current batch.

fcr
required
integer
format: int64[ 0 .. 99999999 ]
The current batch number.

reportDate
required
string
format: 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.

required
array<object>
A breakdown of the report by card scheme.

cardScheme
required
string
[ 1 .. 256 ] characters
The card scheme.

creditCount
required
integer
format: int64>= 0
The total number of credit transactions.

creditTotals
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all credit transactions in minor currency units.

debitCount
required
integer
format: int64>= 0
The total number of debit transactions.

debitTotals
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all credit transactions in minor currency units.

Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "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.
{ "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.
- #Payment Reports
Accepts the following message:
Payment Report Offline Request MessagePaymentReportOfflineRequestMessage
application/json
The message to request details of stored offline transactions.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{}

This example has been generated automatically.
{ "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.
- #Payment Reports
Accepts the following message:
Payment Report Offline Response MessagePaymentReportOfflineResponseMessage
application/json
The message to receive details of stored offline transactions.

object
The message to receive details for offline stored transactions.

required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
count
required
integer
format: int64>= 0
The total number transactions currently stored offline.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "paypoint": { "paypointId": "INST001", "terminalId": "987654321" }, "count": 5 }

This example has been generated automatically.
{ "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.
- #Monitoring
Accepts the following message:
Payment Device Status MessagePaymentDeviceStatusMessage
application/json
The message to receive the status of the connected payment device.

object
Message confirming the status of the connected payment device.

status
required
string
The current status of the payment device.

Allowed values:
"connected"
"disconnected"
"busy"
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
restricted any
The connected payment device.

serialNumber
required
string
[ 1 .. 256 ] characters
The serial number of the payment device.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "status": "connected", "paypoint": { "paypointId": "INST001", "terminalId": "987654321" }, "paymentDevice": { "serialNumber": "A123-4567890" } }

This example has been generated automatically.
{ "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.
- #Monitoring
Accepts the following message:
Payment Service Status MessagePaymentServiceStatusMessage
application/json
The message to receive the status of the payment service.

object
Message confirming the status of the payment service.

status
required
string
The current status of the payment service.

Allowed values:
"not-busy"
"busy"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "status": "not-busy" }

This example has been generated automatically.
{ "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.
- #Monitoring
Accepts the following message:
Payment Device Restart Request MessagePaymentDeviceRestartRequestMessage
application/json
The message to request the restart of connected payment device.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{}

This example has been generated automatically.
{ "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.
- #Monitoring
Accepts the following message:
Payment Device Restart Response MessagePaymentDeviceRestartResponseMessage
application/json
The message to receive the result of the payment device restart request.

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.

Allowed values:
"initiated"
"restarted"
"device-unavailable"
"device-busy"
"failed"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "result": "initiated" }

This example has been generated automatically.
{ "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.

For more information on the errors that may be returned, see https://developer.worldpay.com/docs/ipc/integration-direct#errors.

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.
- #Error Reporting
Accepts the following message:
Error MessageErrorMessage
application/json
The message to receive errors that occur while processing a request.

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

code
required
string
must match: ^[a-zA-Z0-9_\-]{1,20}$[ 1 .. 20 ] characters
A specific error code identifying the error scenario.

message
required
string
[ 1 .. 1000 ] characters
A short message describing cause of error.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
Examples
{ "code": "10001", "message": "The required field 'paymentInstrument.type' is missing" }

This example has been generated automatically.
{ "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

#1POS Registration Request MessagePOSRegistrationRequestMessage
- application/json
The message to register a new Point of Sale.

object
The message to register a new Point of Sale.

pointOfSaleId
required
string
must match: ^[a-zA-Z0-9]{6}$6 characters
A unique identifier for the Point of Sale.

pointOfSaleReference
required
string
must match: ^[a-zA-Z0-9]{1,15}$[ 1 .. 15 ] characters
A reference provided by the merchant for the Point of Sale.

pointOfSaleActivationCode
required
string
must match: ^[a-zA-Z0-9]{8}$8 characters
A unique code to allow a Point of Sale to be activated.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#2POS Registration Response MessagePOSRegistrationResponseMessage
- application/json
The message confirming the registration of a new Point of Sale.

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

pointOfSaleLicenseKey
required
string
must match: ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$[ 1 .. 2000 ] characters
A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#3POS Registration Refresh Request MessagePOSRegistrationRefreshRequestMessage
- application/json
The message to refresh a Point of Sale registration.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#4POS Registration Refresh Response MessagePOSRegistrationRefreshResponseMessage
- application/json
The message confirming the refresh of a Point of Sale registration.

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

pointOfSaleLicenseKey
required
string
must match: ^[a-zA-Z0-9\-\.\+/_=]{1,2000}$[ 1 .. 2000 ] characters
A unique key assigned to the POS to allow it to perform authenticated operations.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#5Payment Start MessagePaymentStartMessage
- application/json
The message to initiate a new payment.
object
Message to start a new payment.

Examples values:
{"paymentType":"sale","merchantTransactionReference":"MS1231000001","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000001","instruction":{"value":{"amount":0},"paymentInstrument":{"type":"card/present","tokenPurpose":"recurring"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000002","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/token","tokenId":"A1B2C3D4E5F6G7H"}}}
{"paymentType":"sale","merchantTransactionReference":"MS1231000004","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/keyed-recovery","authCode":"1234AA"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"check-card","merchantTransactionReference":"MS1231000007","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present","isHandledOnline":true}}}
{"paymentType":"check-card-payment","merchantTransactionReference":"MS1231000008","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present","isHandledOnline":true}}}
{"paymentType":"pre-auth","merchantTransactionReference":"MS1231000009","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
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.

Allowed values:
"sale"
"refund"
"pre-auth"
"check-card"
"check-card-payment"
merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

required
object
The instruction to start the payment.

required
object
The monetary value of the payment

amount
required
integer
format: int64[ 0 .. 999999999 ]
The amount for the payment requested by the merchant in minor currency units.

Additional properties are allowed.
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
[ 1 .. 256 ] characters
First line of the narrative.

Additional properties are allowed.
originalTransactionReference
string
must match: ^[0-9a-zA-Z\!#\$%\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$[ 1 .. 256 ] characters
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
must match: ^[0-9a-zA-Z]{1,30}$[ 1 .. 30 ] characters
For cross-channel refunds, provide the merchant code used in the original sale being refunded.

originalGatewayTransactionReference
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
The PGTR is relevant only for refunds with the Union Pay and Alipay. It has no effect except when used as follows –

For refunding Union Pay or Alipay sales, the original Gateway Transaction Reference is mandatory. If original Gateway Transaction Reference is not provided, then transaction will be declined.

For refund a token the PGTR may be provided as a reference to the original Sale. When the PGTR is provided in this way then the original amount is checked, and the refund is allowed if the refund amount is less than or equal to the sale amount. If the refund amount is greater than the sale amount, then the refund is declined.

The PGTR is optional for token refund. If it is not provided, then the refund amount is accepted without any reference to previous transaction.

required
oneOf
The method by which the payment should be made.

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.

For card/not-present payment instrument for sale transaction card details requested by the PED are PAN, Expiry date, CVC and AVS details as configured for the Paypoint (House number and/or numeric part of postcode).

For card/not-present payment instrument for refund transaction card details requested by the PED are PAN and Expiry date.

Allowed values:
"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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
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.

Allowed values:
"card/keyed-recovery"
authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
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.

Allowed values:
"card/token"
tokenId
required
string
must match: ^[0-9a-zA-Z]{15,21}$[ 15 .. 21 ] characters
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.

tokenPurpose
string
Indicates the purpose of the card-on-file token generated for the card used in this payment.

This is applicable when a payment card is used in this request that will be used for a future merchant initiated transaction using the card-on-file token.

If a purpose is not provided, then the token can only be used to identify a card, it cannot be used to initiate a payment.

Supported values are:

recurring - The card-on-file will be used for recurring payments.

unscheduled - the card-on-file will be used for a one-off payment.

Allowed values:
"recurring"
"unscheduled"
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#6Payment Status MessagePaymentStatusMessage
- application/json
The message to communicate the real-time status of an in-flight payment.

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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

notificationText
required
string
[ 1 .. 256 ] characters
Text describing an event occurring in the payment flow.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#7Payment Action Request MessagePaymentActionRequestMessage
- application/json
The message to request an action to proceed with the payment.
object
Message with details of an action to completed by the merchant.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

required
oneOf
Description of the action required for the payment.

object
The merchant is required to perform voice authorisation.

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

Allowed values:
"voice-authorisation"
required
object
Merchant identifiers to complete voice authorisation for this payment.

merchantId
required
string
[ 8 .. 10 ] characters
The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.
required
array<object>
Referral contact details to complete voice authorisation for this payment.

method
required
string
The method of contact.

Allowed values:
"phone-number"
value
required
string
[ 1 .. 255 ] characters
The value contact method, e.g. the phone number.

Additional properties are allowed.
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.

Allowed values:
"signature-verification"
Additional properties are allowed.
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.

Allowed values:
"avs-confirmation"
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.

Allowed values:
"matched"
"not-matched"
"not-checked"
isAddressLineMatch
required
string
Indicates if the cardholder address line(s) matched during the AVS check.

Allowed values:
"matched"
"not-matched"
"not-checked"
isPostalCodeMatch
required
string
Indicates if the cardholder postal code matched during the AVS check.

Allowed values:
"matched"
"not-matched"
"not-checked"
Additional properties are allowed.
Additional properties are allowed.
object
Merchant is required provide a cashback amount.

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

Allowed values:
"cashback-amount"
maximumCashbackAmount
required
integer
format: 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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#8Payment Action Complete MessagePaymentActionCompleteMessage
- application/json
The message to confirm the action for the payment has been completed.
object
Message with details of the action completed by the merchant.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

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

object
Voice authorisation data.

action
string
The action which has been performed to continue the payment.

Allowed values:
"voice-authorisation"
authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
The authorisation code provided by the issuer, omitted if the transaction is not authorised.

Additional properties are allowed.
object
Signatured verfication data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"signature-verification"
isSignatureVerified
required
boolean
Whether the signature was verified.

Additional properties are allowed.
object
AVS confirmation data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"avs-confirmation"
isAvsConfirmed
required
boolean
Whether AVS results are confirmed.

Additional properties are allowed.
object
Cashback data.

action
required
string
The action which has been performed to continue the payment.

Allowed values:
"cashback-amount"
cashbackAmount
required
integer
format: 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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#9Payment Abort MessagePaymentAbortMessage
- application/json
The message to abort a check card payment.

object
Message to abort a check card payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#10Payment Receipt MessagePaymentReceiptMessage
- application/json
The message to receive a payment receipt.
object
Message with a receipt for a payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

type
required
string
The type of receipt.

customer - Customer copy of a receipt.

merchant - Merchant copy of a receipt.

Allowed values:
"customer"
"merchant"
content
required
string
Base64 representation of the UTF-8 encoded content of the receipt.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#11Payment Result MessagePaymentResultMessage
- application/json
The message to communicate the result of a completed payment.
object
Message with payment results.

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.

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.

Allowed values:
"sale"
"refund"
"pre-auth"
"check-card"
"check-card-payment"
"cancel"
"settle"
transactionDateTime
required
string
format: 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.

Allowed values:
"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.

refused-do-not-reattempt - The payment was refused and no further attempts should be made with the card. 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.

Allowed values:
"authorised-online"
"authorised-offline"
"authorised-referral"
"keyed-recovery-success"
"pre-auth-completed"
"succeeded"
"refused-online"
"refused-offline"
"refused-online-capture-card"
"refused-avs-required"
"refused-do-not-reattempt"
"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"
allOf
Details of the merchant.

object
Identifies the merchant that originates the payment.

merchantId
required
string
[ 8 .. 10 ] characters
The payment gateway's merchant ID to identify the merchant.

Additional properties are allowed.
object
Full details of the merchant.

name
required
string
[ 1 .. 40 ] characters
The merchant's name.

required
object
The merchant's address.

line1
string
[ 1 .. 140 ] characters
Line 1 of the address

line2
string
[ 1 .. 140 ] characters
Line 2 of the address

line3
string
[ 1 .. 140 ] characters
Line 3 of the address

city
string
[ 1 .. 140 ] characters
City of the address

state
string
[ 1 .. 140 ] characters
State/County/Region of the address

postalCode
string
[ 1 .. 8 ] characters
Postal code (Post/Zip code) of the address

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

Additional properties are allowed.
Additional properties are allowed.
required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
object
The monetary value of the payment.

amount
required
integer
format: 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
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

cashbackAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of cash back included in the payment, in minor currency units.

gratuityAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of gratuity included in the payment, in minor currency units.

donationAmount
integer
format: int64[ 0 .. 999999999 ]
The amount of donation included in the payment, in minor currency units.

object
Data for Dynamic Currency Conversion if relevant to the payment.

convertedCurrencyCode
required
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

convertedAmount
required
integer
format: int64[ 0 .. 999999999 ]
The amount of the payment converted into the currency in minor currency units.

conversionRate
required
number
format: 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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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
format: int64>= 1
The transaction sequence number.

retrievalReferenceNumber
integer
format: int64[ 1 .. 9999999999 ]
The retrieval reference number for the transaction.

receiptNumber
integer
format: int64[ 1 .. 9999999999 ]
The number of the receipt to be issued.

receiptRetentionReminder
string
[ 1 .. 50 ] characters
A retention reminder to include on receipts.

receiptCustomerDeclaration
string
[ 1 .. 50 ] characters
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

oneOf
The method by which the payment was made.

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.

Allowed values:
"card/present"
"card/keyed"
"card/not-present"
"card/token"
object
Data for the card used in the payment.

tokenId
string
must match: ^[0-9a-zA-Z]{15,21}$[ 15 .. 21 ] characters
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
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
track2Data
string
must match: ^\;([0-9]{1,19})\=([0-9]{4}|\=)([0-9]{3}|\=)([^\?]+)\?$[ 7 .. 40 ] characters
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.

Allowed values:
"fuel"
"debit"
"credit"
issuerCode
string
must match: ^[a-zA-Z0-9\-]{1,256}$[ 1 .. 256 ] characters
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
must match: ^[0-9]{3}$3 characters
The 3-digit numeric ISO 3166 code for the country the card was issued in.

panSequenceNumber
string
must match: ^[0-9]{2}$2 characters
The PAN Sequence number for ICC payments, and the card's issue number for swiped UK Maestro/Solo card payments.

applicationLabel
string
[ 1 .. 16 ] characters
The mnemonic associated with the application ID (AID) of the card used for the payment according to ISO/IEC 7816-5.

applicationIdentifier
string
must match: ^[A-Z0-9]{10,32}$[ 10 .. 32 ] characters
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
format: 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.

object
The balance of the card/account.

formattedAmount
string
[ 1 .. 100 ] characters
The balance amount formatted for display.

Additional properties are allowed.
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.

object
Data for the authorisation of the payment.

authorisationCode
string
must match: ^[0-9a-zA-Z]{2,6}$[ 2 .. 6 ] characters
The authorisation code generated by the issuer for an authorised payment.

cvvResponseData
string
must match: ^[0-9A-F]{6}$6 characters
Additional response data containing the CVV response.

Additional properties are allowed.
object
transactionStatusInfo
string
must match: ^[0-9A-F]{1,4}$[ 1 .. 4 ] characters
Transaction Status Information (TSI), present only in case of an ICC payment. Used for debug purpose only.

transactionVerificationResults
string
must match: ^[0-9A-F]{1,10}$[ 1 .. 10 ] characters
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.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#12Payment Complete MessagePaymentCompleteMessage
- application/json
The message communicate that the payment process is complete.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#13Payment Settle MessagePaymentSettleMessage
- application/json
The message to settle a pre-authorised payment.
object
Message to settle a previously requested pre-auth payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
required
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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.

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

amount
required
integer
format: int64[ 1 .. 999999999 ]
The amount for the payment requested to be settled by the merchant in minor currency units.

Additional properties are allowed.
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.

Allowed values:
"card"
cardNumber
required
string
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#14Payment Cancel MessagePaymentCancelMessage
- application/json
The message to cancel a previous payment.
object
Message to cancel a payment.

merchantTransactionReference
required
string
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

gatewayTransactionReference
required
string
must match: ^[a-zA-Z0-9]{12,22}$[ 12 .. 22 ] characters
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.

required
oneOf
The method by which the original payment was made.

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.

Allowed values:
"card"
cardNumber
required
string
must match: ^[0-9]{6}[X0-9]{3,9}[0-9]{4}$[ 13 .. 19 ] characters
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.

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

month
required
integer
format: int32[ 1 .. 12 ]
year
required
integer
format: int32[ 0 .. 99 ]
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#15Payment Query Result MessagePaymentQueryResultMessage
- application/json
The message to query the result of the last payment.

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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#16Payment Query Receipt MessagePaymentQueryReceiptMessage
- application/json
The message to query the receipt of the last payment.
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
must match: ^[a-zA-Z0-9]{1,30}$[ 1 .. 30 ] characters
The transaction reference defined by the merchant to uniquely identify the payment. Must contain only alpha numeric characters.

type
required
string
The type of receipt.

customer - Customer copy of a receipt.

merchant - Merchant copy of a receipt.

Allowed values:
"customer"
"merchant"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#17Payment Report Batch Request MessagePaymentReportBatchRequestMessage
- application/json
The message to request an X or Z Report for the transactions in the current batch.

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.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#18Payment Report Batch Response MessagePaymentReportBatchResponseMessage
- application/json
The message to receive an X or Z Report for the transactions in the current batch.

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

required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
batchNumber
required
integer
format: int64[ 0 .. 99999999 ]
The current batch number.

currencyCode
required
string
3 characters
The 3-letter ISO 4217 currency code which amounts are specified in.

saleCount
required
integer
format: int64>= 0
The total number of sales in the batch.

refundCount
required
integer
format: int64>= 0
The total number of sales in the batch.

saleTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all sales in the batch in minor currency units.

refundTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all refunds in the batch in minor currency units.

required
object
A report for the current batch.

fcr
required
integer
format: int64[ 0 .. 99999999 ]
The current batch number.

reportDate
required
string
format: 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.

required
array<object>
A breakdown of the report by card scheme.

cardScheme
required
string
[ 1 .. 256 ] characters
The card scheme.

creditCount
required
integer
format: int64>= 0
The total number of credit transactions.

creditTotals
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all credit transactions in minor currency units.

debitCount
required
integer
format: int64>= 0
The total number of debit transactions.

debitTotals
required
integer
format: int64[ 0 .. 999999999 ]
The total value of all credit transactions in minor currency units.

Additional properties are allowed.
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#19Payment Report Offline Request MessagePaymentReportOfflineRequestMessage
- application/json
The message to request details of stored offline transactions.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#20Payment Report Offline Response MessagePaymentReportOfflineResponseMessage
- application/json
The message to receive details of stored offline transactions.

object
The message to receive details for offline stored transactions.

required
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
count
required
integer
format: int64>= 0
The total number transactions currently stored offline.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#21Payment Device Status MessagePaymentDeviceStatusMessage
- application/json
The message to receive the status of the connected payment device.
object
Message confirming the status of the connected payment device.

status
required
string
The current status of the payment device.

Allowed values:
"connected"
"disconnected"
"busy"
object
The paypoint the request has been performed on.

paypointId
required
string
[ 1 .. 12 ] characters
The unique payment ID assigned to this paypoint by the merchant.

terminalId
required
string
[ 8 .. 10 ] characters
The payment gateway's unique terminal ID the paypoint is registered with.

Additional properties are allowed.
restricted any
The connected payment device.

serialNumber
required
string
[ 1 .. 256 ] characters
The serial number of the payment device.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#22Payment Service Status MessagePaymentServiceStatusMessage
- application/json
The message to receive the status of the payment service.
object
Message confirming the status of the payment service.

status
required
string
The current status of the payment service.

Allowed values:
"not-busy"
"busy"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#23Payment Device Restart Request MessagePaymentDeviceRestartRequestMessage
- application/json
The message to request the restart of connected payment device.

object
The payload for this message is empty.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#24Payment Device Restart Response MessagePaymentDeviceRestartResponseMessage
- application/json
The message to receive the result of the payment device restart request.
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.

Allowed values:
"initiated"
"restarted"
"device-unavailable"
"device-busy"
"failed"
Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.
#25Error MessageErrorMessage
- application/json
The message to receive errors that occur while processing a request.

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

code
required
string
must match: ^[a-zA-Z0-9_\-]{1,20}$[ 1 .. 20 ] characters
A specific error code identifying the error scenario.

message
required
string
[ 1 .. 1000 ] characters
A short message describing cause of error.

Additional properties are allowed.
object
x-wp-correlation-id
string
format: uuid
A unique identifier for the Point of Sale application to use to correlate multiple messages together for traceability.

When sending a new message generate a new UUID for this value. When replying to a message from IPS, send the same correlation ID as the message you are replying to.

Multiple replies from IPS may be linked to a single POS request, and they will come with the same correlation ID.

x-wp-message-id
string
format: uuid
A UUID that identifies each individual message. When sending this message, generate a new UUID.

This may be used to identify duplicate messages in the event of network instability.

x-wp-publisher-id
string
[ 1 .. 256 ] characters
A unique ID that identifies the sender of the message.

Create a universally unique ID for your Point of Sale application and send it in all messages. This should be UUID generated or a MAC address of the POS to maximise uniqueness.

This may be used to identify the source of a message.

Additional properties are allowed.

Servers

Operations

PUB /v1/pos/registration

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/pos/registration

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/pos/registration/refresh

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/pos/registration/refresh

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

#6 Example

#7 Example

#8 Example

This example has been generated automatically.

SUB /client/v1/payment/notification

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/payment/action

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/action

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/abort

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/payment/receipt

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/payment/result

Major card schemes

Store cards and gift cards

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/payment/complete

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/settle

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/cancel

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/query/result

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/query/receipt

Examples

This example has been generated automatically.

This example has been generated automatically.

PUB /v1/payment/report/batch

Examples

This example has been generated automatically.

This example has been generated automatically.

SUB /client/v1/payment/report/batch