Integrated Payment Server CLOUD - Payment API 1.4.0 documentation

Integrated Payment Server CLOUD - Payment API 1.4.0

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://ws.muat.worldpaypp.com:443/ipc-app/payment/{paypointRef}stomp 1.0cloud-muat
MUAT version of IPS-Cloud.
object
paypointRef
required
string
Identifier for the paypoint on which the action should be performed on. The Paypoint Reference must be between 1 and 20 characters. Valid characters are A-Z, a-z, 0-9, - (hyphen) and _ (underscore).

Examples values:
"INST001"
wss://ipscloud.worldpay.com:443/ipc-app/payment/{paypointRef}stomp 1.0cloud-prod
PROD version of IPS-Cloud.
object
paypointRef
required
string
Identifier for the paypoint on which the action should be performed on. The Paypoint Reference must be between 1 and 20 characters. Valid characters are A-Z, a-z, 0-9, - (hyphen) and _ (underscore).

Examples values:
"INST001"

Operations

RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Point of Sale Registration
Accepts the following message:
POS Registration Request Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Point of Sale Registration
Accepts the following message:
POS Registration Response Message
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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Point of Sale Registration
Accepts the following message:
POS Registration Refresh Request Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Point of Sale Registration
Accepts the following message:
POS Registration Refresh Response Message
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.
RECEIVE /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

Card present account verification, storing the card on file for a future recurring payment

Card token sale

Card token sale with SRD

Card present refund

Card token refund

Card present check card only

Card present check card, wait for payment

Card present pre-authorisation

Card not present incremental-authorisation
Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Start Message
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":"MS1231000002","instruction":{"value":{"amount":1099},"narrative":{"line1":"Transactiondescription"},"paymentInstrument":{"type":"card/token","schemeTxnIdentifier":"000000003623582","tokenId":"99476173029255250100","tokenPurpose":"recurring"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":700},"originalGatewayTransactionReference":"PGTR5123280770","paymentInstrument":{"type":"card/token","tokenId":"99476173029255250100"}}}
{"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":"inc-auth","merchantTransactionReference":"MS1231000002","gatewayTransactionReference":"PGTR1000519913","instruction":{"value":{"amount":1399},"paymentInstrument":{"type":"card/not-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.

inc-auth - Increase the previously authorized pre-auth amount, 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"
"inc-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 ]
An amount of money in minor currency units.

Additional properties are allowed.
originalTransactionReference
string
must match: ^[0-9a-zA-Z\!#\$%\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$[ 1 .. 256 ] characters
The merchant transaction reference of the cross-channel sale being referenced.

Must contain only alpha numeric, or these special characters:

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

originalMerchantCode
string
must match: ^[0-9a-zA-Z]{1,30}$[ 1 .. 30 ] characters
The merchant code of the cross-channel sale being referenced.

originalGatewayTransactionReference
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 payment should be made.

object
Details for a payment instrument captured by a payment device.

This payment instrument is supported for sale, refund, check-card, pre-auth, inc-auth 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"
isHandledOnline
boolean
Indicates whether the payment should be, or has been, performed online or not.

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 generated by the issuer for an authorised payment.

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"
schemeTxnIdentifier
string
[ 1 .. 56 ]
This is the transaction identifier response from the scheme. Maximum 56 characters, can contain spaces. Note: Preserve this exactly as you receive it, including any spaces. Merchant Initiated Transactions aka MITS using tokens shall use Scheme reference data (SRD) aka Scheme Transaction Identifier as and when mandated by schemes.

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": "MS1231000002", "instruction": { "value": { "amount": 1099 }, "narrative": { "line1": "Transactiondescription" }, "paymentInstrument": { "type": "card/token", "schemeTxnIdentifier": "000000003623582", "tokenId": "99476173029255250100", "tokenPurpose": "recurring" } } }

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

#6 Example
{ "paymentType": "refund", "merchantTransactionReference": "MS1231000005", "instruction": { "value": { "amount": 700 }, "originalGatewayTransactionReference": "PGTR5123280770", "paymentInstrument": { "type": "card/token", "tokenId": "99476173029255250100" } } }

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

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

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

#10 Example
{ "paymentType": "inc-auth", "merchantTransactionReference": "MS1231000002", "gatewayTransactionReference": "PGTR1000519913", "instruction": { "value": { "amount": 1399 }, "paymentInstrument": { "type": "card/not-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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Status Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Action Request Message
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
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.
required
array<object>
Contact details for handling referrals. Typically telephone numbers.

object
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.
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
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

Allowed values:
"matched"
"not-matched"
"not-checked"
isAddressLineMatch
required
string
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

Allowed values:
"matched"
"not-matched"
"not-checked"
isPostalCodeMatch
required
string
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

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 ]
An amount of money 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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Action Complete Message
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 generated by the issuer for an authorised payment.

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 ]
An amount of money 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.
RECEIVE /v1/payment/abort
Abort a check card payment request, by sending a message to the STOMP destination /v1/payment/abort.

Publishing to this destination requires an authenticated connection.

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

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Abort Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
- #Manage Existing Payments
Accepts the following message:
Payment Receipt Message
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.
SEND /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/cancel

/v1/payment/query/result

/v1/payment/settle

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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Result Message
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.

object
Full details of a completed payment.

paymentType
required
string
The type of payment that was requested.

sale - Authorise and settle a payment from a customer for goods/services.

refund - Authorise and settle a payment to a customer for the return of goods/services.

pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.

inc-auth - Increase the previously authorized pre-auth amount, 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.

cancel - The cancellation of a previously requested sale, refund, or pre-auth.

settle - The settlement of a previously requested pre-auth.

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.

Allowed values:
"sale"
"refund"
"pre-auth"
"inc-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"
"succeeded"
"pre-auth-completed"
"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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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 ]
An amount of money in minor currency units.

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

cashbackAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

gratuityAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

donationAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money 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 ]
An amount of money 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
Text that can be displayed on a receipt.

receiptCustomerDeclaration
string
[ 1 .. 50 ] characters
Text that can be displayed on a receipt.

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, inc-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 date (month and year) associated with the card.

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.

schemeTxnIdentifier
string
[ 1 .. 56 ]
This is the transaction identifier response from the scheme. Maximum 56 characters, can contain spaces. Note: Preserve this exactly as you receive it, including any spaces. Merchant Initiated Transactions aka MITS using tokens shall use Scheme reference data (SRD) aka Scheme Transaction Identifier as and when mandated by schemes.

Additional properties are allowed.
posEntryMode
string
must match: ^[a-zA-Z0-9\-]{1,50}$
The method of reading the card. The current possible values are:

keyed

magstripe

integrated-circuit-chip

contactless-chip

contactless-magstripe

contactless-on-device

cardholder-not-present

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

cardVerificationMethod
string
must match: ^[a-zA-Z0-9\-]{1,50}$
The verification method used for the cardholder. The current possible values are:

signature

pin-or-consumer-device

pin-and-signature

cardholder-not-present

none

unknown

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

isHandledOnline
boolean
Indicates whether the payment should be, or has been, performed online or not.

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.
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": 1099, "currencyCode": "GBP", "cashbackAmount": 1099, "gratuityAmount": 1099, "donationAmount": 1099, "dcc": { "convertedCurrencyCode": "GBP", "convertedAmount": 1099, "conversionRate": 1.11647 } }, "merchantTransactionReference": "MS123A54B3DF", "gatewayTransactionReference": "1234567890AB", "eftSequenceNumber": 1, "retrievalReferenceNumber": 1, "receiptNumber": 1, "receiptRetentionReminder": "string", "receiptCustomerDeclaration": "string", "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", "schemeTxnIdentifier": 3623582 }, "posEntryMode": "contactless-chip", "cardVerificationMethod": "pin-or-consumer-device", "isHandledOnline": true, "authorisation": { "authorisationCode": "12345", "cvvResponseData": "422800" }, "debug": { "transactionStatusInfo": "F800", "transactionVerificationResults": "4000008000" } } } ] }

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

/v1/payment/settle

Once received the client must disconnect from the web socket connection.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Complete Message
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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Settle Message
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[ 0 .. 999999999 ]
An amount of money in minor currency units.

Additional properties are allowed.
required
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 date (month and year) associated with the card.

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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Cancel Message
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 date (month and year) associated with the card.

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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Query Result Message
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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payments
Accepts the following message:
Payment Query Receipt Message
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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Payment Reports
Accepts the following message:
Payment Report Batch Request Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Payment Reports
Accepts the following message:
Payment Report Batch Response Message
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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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 ]
An amount of money in minor currency units.

refundTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
An amount of money 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.

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

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 ]
An amount of money in minor currency units.

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

debitTotals
required
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

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
{ "paypoint": { "paypointId": "INST001", "terminalId": "987654321" }, "batchNumber": 541505, "currencyCode": "GBP", "saleCount": 71, "refundCount": 8, "saleTotalAmount": 1099, "refundTotalAmount": 1099, "batchReport": { "fcr": 541505, "reportDate": "2019-08-24T14:15:22Z", "report": [ { "cardScheme": "Visa", "creditCount": 7, "creditTotals": 1099, "debitCount": 33, "debitTotals": 1099 } ] } }

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.
SEND /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.

Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Monitoring
Accepts the following message:
Payment Device Status Message
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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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.
SEND /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.

Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Monitoring
Accepts the following message:
Payment Service Status Message
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.
RECEIVE /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.

Operation IDpublish
Available only on servers:
- cloud-muat
- cloud-prod
- #Monitoring
Accepts the following message:
Payment Device Restart Request Message
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.
SEND /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.
Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Monitoring
Accepts the following message:
Payment Device Restart Response Message
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.
SEND /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://docs.worldpay.com/apis/ips-cloud/integration/direct-integration#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.

Operation IDsubscribe
Available only on servers:
- cloud-muat
- cloud-prod
- #Error Reporting
Accepts the following message:
Error Message
application/json
The message to receive errors that occur while processing a request.

object
Details of the error that has occurred.

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 Messagepos-registration-request-message
- application/json
Message IDpos-registration-request-message
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 Messagepos-registration-response-message
- application/json
Message IDpos-registration-response-message
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 Messagepos-registration-refresh-request-message
- application/json
Message IDpos-registration-refresh-request-message
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 Messagepos-registration-refresh-response-message
- application/json
Message IDpos-registration-refresh-response-message
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 Messagepayment-start-message
- application/json
Message IDpayment-start-message
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":"MS1231000002","instruction":{"value":{"amount":1099},"narrative":{"line1":"Transactiondescription"},"paymentInstrument":{"type":"card/token","schemeTxnIdentifier":"000000003623582","tokenId":"99476173029255250100","tokenPurpose":"recurring"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":1099},"paymentInstrument":{"type":"card/present"}}}
{"paymentType":"refund","merchantTransactionReference":"MS1231000005","instruction":{"value":{"amount":700},"originalGatewayTransactionReference":"PGTR5123280770","paymentInstrument":{"type":"card/token","tokenId":"99476173029255250100"}}}
{"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":"inc-auth","merchantTransactionReference":"MS1231000002","gatewayTransactionReference":"PGTR1000519913","instruction":{"value":{"amount":1399},"paymentInstrument":{"type":"card/not-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.

inc-auth - Increase the previously authorized pre-auth amount, 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"
"inc-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 ]
An amount of money in minor currency units.

Additional properties are allowed.
originalTransactionReference
string
must match: ^[0-9a-zA-Z\!#\$%\*\+,\-\.\/\\\:;\=\?@\[\]_`\{\}~]{1,256}$[ 1 .. 256 ] characters
The merchant transaction reference of the cross-channel sale being referenced.

Must contain only alpha numeric, or these special characters:

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

originalMerchantCode
string
must match: ^[0-9a-zA-Z]{1,30}$[ 1 .. 30 ] characters
The merchant code of the cross-channel sale being referenced.

originalGatewayTransactionReference
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 payment should be made.

object
Details for a payment instrument captured by a payment device.

This payment instrument is supported for sale, refund, check-card, pre-auth, inc-auth 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"
isHandledOnline
boolean
Indicates whether the payment should be, or has been, performed online or not.

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 generated by the issuer for an authorised payment.

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"
schemeTxnIdentifier
string
[ 1 .. 56 ]
This is the transaction identifier response from the scheme. Maximum 56 characters, can contain spaces. Note: Preserve this exactly as you receive it, including any spaces. Merchant Initiated Transactions aka MITS using tokens shall use Scheme reference data (SRD) aka Scheme Transaction Identifier as and when mandated by schemes.

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 Messagepayment-notification-message
- application/json
Message IDpayment-notification-message
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 Messagepayment-action-request-message
- application/json
Message IDpayment-action-request-message
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
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.
required
array<object>
Contact details for handling referrals. Typically telephone numbers.

object
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.
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
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

Allowed values:
"matched"
"not-matched"
"not-checked"
isAddressLineMatch
required
string
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

Allowed values:
"matched"
"not-matched"
"not-checked"
isPostalCodeMatch
required
string
The result of an AVS check on an element of data.

matched - the field was checked as part of the AVS process and matched the expected value.

not-matched - the field was checked as part of the AVS process but did not match the expected value.

not-checked - the field was not checked as part of the AVS process.

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 ]
An amount of money 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 Messagepayment-action-complete-message
- application/json
Message IDpayment-action-complete-message
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 generated by the issuer for an authorised payment.

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 ]
An amount of money 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 Messagepayment-abort-message
- application/json
Message IDpayment-abort-message
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 Messagepayment-receipt-message
- application/json
Message IDpayment-receipt-message
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 Messagepayment-result-message
- application/json
Message IDpayment-result-message
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.

object
Full details of a completed payment.

paymentType
required
string
The type of payment that was requested.

sale - Authorise and settle a payment from a customer for goods/services.

refund - Authorise and settle a payment to a customer for the return of goods/services.

pre-auth - Authorise a payment from a customer, but settle the payment separately using the payment/settle channel.

inc-auth - Increase the previously authorized pre-auth amount, 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.

cancel - The cancellation of a previously requested sale, refund, or pre-auth.

settle - The settlement of a previously requested pre-auth.

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.

Allowed values:
"sale"
"refund"
"pre-auth"
"inc-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"
"succeeded"
"pre-auth-completed"
"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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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 ]
An amount of money in minor currency units.

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

cashbackAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

gratuityAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

donationAmount
integer
format: int64[ 0 .. 999999999 ]
An amount of money 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 ]
An amount of money 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
Text that can be displayed on a receipt.

receiptCustomerDeclaration
string
[ 1 .. 50 ] characters
Text that can be displayed on a receipt.

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, inc-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 date (month and year) associated with the card.

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.

schemeTxnIdentifier
string
[ 1 .. 56 ]
This is the transaction identifier response from the scheme. Maximum 56 characters, can contain spaces. Note: Preserve this exactly as you receive it, including any spaces. Merchant Initiated Transactions aka MITS using tokens shall use Scheme reference data (SRD) aka Scheme Transaction Identifier as and when mandated by schemes.

Additional properties are allowed.
posEntryMode
string
must match: ^[a-zA-Z0-9\-]{1,50}$
The method of reading the card. The current possible values are:

keyed

magstripe

integrated-circuit-chip

contactless-chip

contactless-magstripe

contactless-on-device

cardholder-not-present

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

cardVerificationMethod
string
must match: ^[a-zA-Z0-9\-]{1,50}$
The verification method used for the cardholder. The current possible values are:

signature

pin-or-consumer-device

pin-and-signature

cardholder-not-present

none

unknown

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

isHandledOnline
boolean
Indicates whether the payment should be, or has been, performed online or not.

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.
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 Messagepayment-complete-message
- application/json
Message IDpayment-complete-message
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 Messagepayment-settle-message
- application/json
Message IDpayment-settle-message
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[ 0 .. 999999999 ]
An amount of money in minor currency units.

Additional properties are allowed.
required
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 date (month and year) associated with the card.

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 Messagepayment-cancel-message
- application/json
Message IDpayment-cancel-message
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 date (month and year) associated with the card.

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 Messagepayment-query-result-message
- application/json
Message IDpayment-query-result-message
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 Messagepayment-query-receipt-message
- application/json
Message IDpayment-query-receipt-message
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 Messagepayment-report-batch-request-message
- application/json
Message IDpayment-report-batch-request-message
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 Messagepayment-report-batch-response-message
- application/json
Message IDpayment-report-batch-response-message
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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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 ]
An amount of money in minor currency units.

refundTotalAmount
required
integer
format: int64[ 0 .. 999999999 ]
An amount of money 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.

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

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 ]
An amount of money in minor currency units.

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

debitTotals
required
integer
format: int64[ 0 .. 999999999 ]
An amount of money in minor currency units.

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.
#19Payment Device Status Messagepayment-device-status-message
- application/json
Message IDpayment-device-status-message
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
Identifier for the paypoint on which the action should or has been performed on.

Each paypoint must be given a unique identifier 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.
#20Payment Service Status Messagepayment-service-status-message
- application/json
Message IDpayment-service-status-message
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.
#21Payment Device Restart Request Messagepayment-device-restart-request-message
- application/json
Message IDpayment-device-restart-request-message
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.
#22Payment Device Restart Response Messagepayment-device-restart-response-message
- application/json
Message IDpayment-device-restart-response-message
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.
#23Error Messageerror-message
- application/json
Message IDerror-message
The message to receive errors that occur while processing a request.

object
Details of the error that has occurred.

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

RECEIVE /v1/pos/registration

Examples

This example has been generated automatically.

This example has been generated automatically.

SEND /client/v1/pos/registration

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/pos/registration/refresh

Examples

This example has been generated automatically.

This example has been generated automatically.

SEND /client/v1/pos/registration/refresh

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

#6 Example

#7 Example

#8 Example

#9 Example

#10 Example

This example has been generated automatically.

SEND /client/v1/payment/notification

Examples

This example has been generated automatically.

This example has been generated automatically.

SEND /client/v1/payment/action

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/action

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/abort

Examples

This example has been generated automatically.

This example has been generated automatically.

SEND /client/v1/payment/receipt

Examples

This example has been generated automatically.

This example has been generated automatically.

SEND /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.

SEND /client/v1/payment/complete

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/settle

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/cancel

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/query/result

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/query/receipt

Examples

This example has been generated automatically.

This example has been generated automatically.

RECEIVE /v1/payment/report/batch

Examples

This example has been generated automatically.