Worldpay Logo

Worldpay Within Documentation

The Worldpay Within Architecture

Quick intro

To complement the Architecture we have released the Worldpay Within SDK. The intention for of the SDK is to encapsulate implementation and therefore assist third party vendors and developers in integration into their IoT solutions.

The core of the SDK is developed in the Go programming language with wrappers created for Java, Node.JS, Python 2.7, Pyhton 3.0 and .net(C#). Service delivery and broadcast have been implemented using TCP/IP networking.

Please note the low level service messaging json spec can be found here

Architecture Overview

In the IoT, each Thing will perform the function it is designed for be it acting as a sensor, or a controller or both. In order for 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.

Worldpay Within Pluggable agent
Figure 1. Worldpay Within Pluggable agent.

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.

Logical Overview
Figure 2. Worldpay Within Logical Overview.

In order to make and receive payments in the IoT, a Thing must be able to perform the roles of “consumer”, to make a payment for services, and the “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” receives payments for services by supporting Host Terminal Emulation (HTE). Worldpay Within contains both an HCE Brain & 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.

HCE and HTE require the secure storage and use of the credentials during the payments process. This necessitates 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 in

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 Architeture

The provision of a service within the Worldpay IoT system is performed in 4 phases, as shown in Figure 4, these being: Service Discovery; Service Negotiation; Payment; and Service Delivery. Each of these phases are described in the following sections.

The 4 phases of Worldpay Within
Figure 4. The 4 phases of Worldpay Within.

Service Discovery

Each Thing that offers services, the service ‘supplier’ shall broadcast it’s list of available services, as shown in Figure 4 below. When a potential ‘consumer’ of the service connects with ‘supplier’ it can request details of the services offered.

Providing a suitable service is discovered, the consumer then requests the service from the supplier, and price negotiations can begin.

IoT Service discovery
Figure 5. IoT Service discovery.

Service Discovery APIs

broadcastserver_UUIDAdvertising services and identifying the sender
request servicesnoneRequest a list of all services
services_responselist of services, server_UUIDProvide 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.

Service Negotiation

Once a suitable service has been discovered, there will be a price negotiation. 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.

IoT Service Negotiation
Figure 6. IoT Service Negotiation.

Service Negotiation APIs

price_requestservice_idRequest a list of all prices for a given service.
price_responseserver_UUID, list of prices, (service_id, price_id, price_per_unit, unit_ID, unit_description, price_description)Provide the client with a list of prices for a given service. A price object contains the per unit price.
price_selectservice_id, price_id, number_of_units, client_UUIDSelect a price with price_id, for service_id for a number of units.
price_select_responseprice_id, number_of_units, total_price, server_UUID, client_UUID, payment_ref_ID, Merchant_Client_keyCommunicate the expected total price to the client.

Service negotiation messages

A price request is sent containing the selected service_id.

The response from Thing B contains a list of price items; each item should contain a price_id, per unit price, unit_ID and 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 service_id, the 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 service_id, 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 is a two stage process, split between the consumer and merchant Things involved in the transaction, these stages are:

  • Client Token Request, and

  • Payment Authorisation Request. (Also known as Order Request)

During the first stage, the consumer sends their payment credentials and the merchants Client Key. returns a Client Token, which the consumer passes to the Merchant, allowing the merchant to perform the payment authorisation request with 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

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 to request the client token from This request includes Thing A’s payment credentials: Card PAN, expiry, and the client_key of Thing B. will respond with a message that includes a client_token. This is shown in Figure 7.

IoT Payment process - client token request
Figure 7. IoT Payment process - client token request.

Client token request APIs

Thing A to client token request
client_token_requestPayment_method, reusable_flag, Merchant_client_key Payment\_method (name, PAN, expiryMonth, expiryYear, type) Request a client token from, whilst providing with the payment credentials.
client_token_responseclient_token, reusable_flag, payment_method_response (type, name, expiryMonth, expiryYear, card\_type, card\_scheme\_type, card\_scheme\_name, masked\_card\_number, card\_product\_type\_description\_non\_contactless, card\_product\_type\_description\_contactless, card\_issuer, country\_code, card\_class, pre-paid) Response from containing the client_token.
Payment_requestclient_token, client_UUID, payment_ref_IDThe client_token is passed to Thing B to allow the 2^nd^ part of the transaction process to take place.

Thing A will connect to using 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 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 generation of a new client token for each transaction.

A successful response will be an HTTP POST response containing fields: client_token, reusable_flag and the payment_method_response. Once received, the client_token shall be passed to Thing B

A sample request is shown in Appendix B: Sample Service Messaging.

See documentation for client_token_request & client_token_repsonse APIs data descriptions.

Payment authorisation request

Thing B will process the order and request the payment from providing its Service key, client_token, transaction currency and payment amount. This is transmitted to over TLS. After successful processing 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
Figure 8. Payment Authorisation Request.

Payment authorisation request APIs

Thing B to payment authorisation request
order_requestclient_service_key, client_token, currency_code, amount, order_description, customer_order_codeRequest payment from
order_responseorder_code, client_token, order_description, amount, currency_code, payment_status, customer_order_code, environment, risk_score, payment_response (type, name, expiryMonth, expiryYear, card\_type, card\_scheme\_type, card\_scheme\_name, masked\_card\_number, card\_product\_type\_description\_non\_contactless, card\_product\_type\_description\_contactless, card\_issuer, country\_code, card\_class, pre-paid)Payment response indicating a successful transaction on the platform.

Thing B shall assemble a message to be posted to that contains the client token, Service key, the amount, currency and transaction description. shall 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
payment_request_responseservice_delivery_token, server_UUID, client_UUID, total_paidservice_delivery_token is passed to ThingB.

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.

Service Delivery

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.

Service delivery
Figure 8. Service delivery.

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

payment_request_responseservice_delivery_token, server_UUID, client_UUID, total_paidservice_delivery_token is passed to ThingB.
broadcastserver_UUIDAdvertising services and identifying the sender.
delivery_begin_requestservice_delivery_token, client_UUID, number_of_units_to_supplyRequest the service item, with the service_delivery_token providing right to receive the service, and amount of service to be supplied.
delivery_begin_responseserver_UUID, service_delivery_token, client_UUID, number_of_units_to_be_suppliedResponse for the service delivery. Confirmation of number of service units to be supplied (Allowing for less units than requested).
delivery_endclient_UUID, number_of_units_receivedConfirmation of service received.
delivery_end_responseserver_UUID, service_delivery_token, client_UUID, number_of_units_just_supplied, number_of_units_remainingService 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.

Useful terms

A few useful terms we're making quite a lot of use of, and if you are new to the world of payments these may be unfamiliar to you!

APIApplication Programming Interface
Online.worldpay.comWorldpay Open Payment API,
HCEHost Card Emulation
HTEHost Terminal Emulation
HTTPSHyperText Transfer Protocol Secure
IoTInternet of Things
P2PEPoint to Point Encryption
TLSTransport Layer Security
UUIDUniversally Unique Identifier
RPCRemote Procedure Call