To complement the architecture we've released the Worldpay Within SDK. The intention for the SDK is to encapsulate implementation and help third party vendors and developers integrate into their Internet of Things (IoT) solutions.
For more information about the low level service messaging, click here.
In the IoT, each Thing will perform the function it is designed for, be it acting as a sensor, a controller or both. In order for the Thing to be able to make and receive payments for services they can provide to other Things, they need to add the payments functionality contained in Worldpay Within.
Things in the IoT will be implemented on dedicated low cost processor systems. The Thing and Worldpay Within must co-exist and operate on the resources provided by these devices, as demonstrated in Figure 2.
In order to make and receive payments in the IoT, a Thing must be able to perform the roles of consumer (shopper), to make a payment for services, and the producer (merchant), to receive a payment for provision of services. In the Worldpay Within IoT architecture, the “consumer” pays for services by supporting Host Card Emulation (HCE). The “merchant” or "producer" receives payments for services by supporting Host Terminal Emulation (HTE). Worldpay Within contains both HCE Brain and HTE Brain functionalities, ensuring a Thing can both consume and supply services. These services are provided through a series of public APIs, described within this document.
During the payments process, HCE and HTE require the secure storage and use of credentials. This requires the use of secure processing within the Thing in a “Secure Execution Environment”. For HCE Things, these credentials include the details of the “card” which the payment will be made from. For HTE Things, these credentials include the details the Merchant requires to perform transactions with Worldpay.
As well as the provision of the payment for the services, Worldpay Within provides for the generation and validation of secure service tokens, which allow for services to be consumed in part or together, but separately from the payments functionality.
Worldpay Within IoT Service Architecture¶
The provision of a service within the Worldpay IoT system is performed in 4 phases, as shown in Figure 3. These are: Discover, Select, Pay, and Release. Each of these phases are described in the following sections.
For each Thing that offers services, the service ‘producer’ shall broadcast its list of available services, as shown in Figure 4 below. When a potential ‘consumer’ of the service connects with ‘producer’, it can request details of the services offered.
Providing a suitable service is discovered, the consumer then requests the service from the producer, and price negotiations can begin.
Service Discovery APIs¶
||Advertising services and identifying the sender.|
|request services||none||Request a list of all services.|
||Provide client with a list of possible services that the sender can provide.|
Service discovery messages¶
A broadcast message that includes Thing B’s UUID is sent.
Upon receiving the message, Thing A connects to Thing B and requests the list of available services.
Thing B responds with a list identifying the services available.
Once a suitable service has been discovered, the shopper will make the choice. The provider may offer the same service at different rates depending on the number of units of service to be purchased. The process is outlined in Figure 5. The outcome of the process is an agreement to purchase an amount of service and a total price for the service to be provided. The service provider can then request payment for the agreed service and price.
Service selection APIs¶
||Request a list of all prices for a given service.|
||Provide the client with a list of prices for a given service. A price object contains the per unit price.|
||Select a price with
||Communicate the expected total price to the client.|
Service selection messages¶
A price request is sent containing the selected
The response from Thing B contains a list of price items; each item should contain a
price_id, per unit price,
description fields of both the unit and the price.
Thing A then selects an appropriate
price_id by sending a request with its
client_UUID, the selected
price_id, and the number of items required.
If the number of items falls within the correct number of items for the price selected, then Thing B responds with a price select response containing the
price_id, the total price, the
service_UUID and a reference for the payment and its Merchant Client key. Otherwise, Thing B shall return the number of units it can supply along with the correct price, and additional details required to initiate the payment.
The payment process with Worldpay is a two stage process, split between the consumer and merchant Things involved in the transaction:
- Client Token Request
- Payment Authorisation Request (Also known as Order Request)
During the first stage, the consumer sends Worldpay their payment credentials and the merchants Client Key. We return a Client Token, which the consumer passes to the Merchant. This allows the merchant to perform the payment authorisation request with Worldpay by providing the Client Token and transaction details.
This payment process ensures that the consumer does not pass their payment credentials to the merchant, only to Worldpay.
Client token request¶
The first step in the payment process is when Thing A receives the
Merchant_Client_Key from Thing B. Thing B passes their public Client Key to Thing A as part of the
price_select_response during the Service Negotiation phase. Upon receiving the Client Key from Thing B, Thing A connects with Worldpay to request the client token from us. This request includes Thing A’s payment credentials: Card PAN, expiry, and the
client_key of Thing B. Worldpay will respond with a message that includes a
client_token. This is shown in Figure 6.
Client token request APIs¶
Thing A to Worldpay client token request¶
||Request a client token from Worldpay, whilst providing us with the payment credentials.|
||Response from Worldpay containing the client_token.|
Thing A will connect to Worldpay using Transport Layer Security (TLS). It will then request a
client_token by securely (see 2.2.1) sending a JSON message containing the
paymentMethod, its payment credentials (PAN, expiry) to us, along with the
client_key from Thing B. In addition, a flag indicating if the client details can be used in future is sent. For IoT this should always be set
‘reusable’:’false’ in order to force the generation of a new client token for each transaction.
A successful response will be an HTTP
POST response containing fields:
reusable_flag and the
payment_method_response. Once received, the
client_token is passed to Thing B.
A sample request is shown in Sample Service Messaging.
See API keys for documentation on
client_token_repsonse APIs data descriptions.
Payment authorisation request¶
Thing B will process the order and request the payment from Worldpay providing its service key,
client_token, transaction currency and payment amount. This is transmitted to Worldpay over TLS. After successfully processing the payment, Worldpay will provide a payment response. Thing B shall then generate a service token, which Thing A may use in future to obtain the services that the payment has been made for. This is shown in Figure 7.
Payment authorisation request APIs¶
Thing B to Worldpay payment authorisation request¶
||Request payment from Worldpay.|
||Payment response indicating a successful transaction on the Worldpay platform.|
Thing B will assemble a message to be posted to Worldpay that contains the client token, Service key, the amount, currency and transaction description. We will then perform an authorisation using the payment credentials identified by the
client_token. A successful authorisation will result in a
payment_status of SUCCESS being returned to Thing B.
Thing B to Thing A service token¶
Thing B shall then generate a cryptographically secure
service_delivery_token, which can be used by Thing A to request provision of services from Thing B.
Once the payment has been made, Thing B shall return to broadcasting its available services. Thing A will now be able to consume the service from Thing B by providing the
service_delivery_token. The service delivery may be in a single step, or over time. An overview of service delivery is shown in Figure 8.
Once in possession of a
service_token, Thing A may then request the service be provided. The service could be consumed in one session, or in several sessions over time, depending on the nature of the service and number of units purchased. Thing A may repeatedly send service delivery requests until Thing B indicates that the service has been delivered.
Service Delivery APIs¶
||Advertising services and identifying the sender.|
||Request the service item, with the
||Response for the service delivery. Confirmation of number of service units to be supplied (Allowing for less units than requested).|
||Confirmation of service received.|
||Service end indicating outstanding service credits and token for subsequent delivery.|
Thing A sends a message with the
service_delivery_token to Thing B, along with the amount of service it wishes to consume. The response shall confirm the amount of service units that Thing B can supply to Thing A at that time. Once the service has been delivered, Thing A shall confirm the amount of service units it has received, with Thing B responding, stating the number of units still remaining to Thing A, if any.