Configurable Options

TL;DR

What we are about to do:

Tokenize an Identifier
Receive a Transmission Token
Transmit a Receipt using Transmission Token

In this short How-To, we will show you how easy it is to transmit a Receipt using wunderbon and how we ensure strong privacy for all parties at the same time. Enjoy!

Requirements

We will go through this How-To without requiring a wunderbon account (real Authentication or Id Token). If you have an account already and want to walk through this How-To using your account and the Testnet (0xFF), feel free to do so. For this, you just need to exchange the URL from playground-api.wunderbon.io to testnet-api.wunderbon.io.

Beside the Access Token, you will need the following tools to get through this guide:

Some kind of Shell (whatever you prefer)
cURL

Note: We assume that you have cURL in place. All our examples are based on cURL as a client. If you like to use Postman or Stoplight Studio instead, check out the latest OpenAPI specification to load the wunderbon API.

Authentication

With your registration as Merchant, you received your Client-Id and your Client-Secret. We need to receive an Authentication Token (Id Token) to authenticate against the wunderbon API. You can try the following recipe if you don't know already how to log in and exchange credentials with an Authentication Token.

Authenticate as POS 🛒

For all further access to the protected wunderbon API endpoints, we make use of the following Authentication Parameters:

Authentication-Type: http
Authentication-Scheme: bearer
Bearer-Format: JWT
Transportation-Method: Header

Recipient

For testing purposes or for evaluating the wunderbon API, we provide a set of test data. Almost any operation within the wunderbon network requires a reference to a user. So to transmit a Receipt, you need to identify the customer as a wunderbon user. The following set of data is used in this How-To:

Official Test User

For testing purposes and demonstration of the network functionality (Testnet), we provide the following user entity:

Id: c1de9956-9fca-42aa-87ef-a90a48c9d112

Official Test Identifiers

wunderbon Account Number
- Provider Id: 0x01
- Identifier: Random Tokenized
- Sequence: null
- Expires: null
Primary Account Number (ISO/IEC 7812)
- Provider Id: 0x02
- Identifier: 5168 4412 2363 0339 ¹
- Sequence: 01
- Expires (month/year): 06/2026

The wunderbon Account Number will be provided from the Consumer's smartphone display at the POS. The token will be either shown as QR Code or fallback as Code 128. The Code128 will require an additional step to receive the real tokenized cryptogram. This may depend on the capabilities of the scanning device (POS-System).

QR Code Data:
eyJpdiI6IjdpWjljalVuUm5Nb25KNG1tM3NFREE9PSIsImVwaGVtUHVibGljS2V5IjoiQkhEdj... (truncated for brevity)

Identifier

In this How-To, we will make use of the user's Primary Account Number (ISO/IEC 7812). ¹ The following Cardholder Data is provided only for testing/demonstration purposes. wunderbon DOES NEVER STORE ANY PAYMENT OR OTHER SENSITIVE INFORMATION!

Cardholder Data

Issuing network: Mastercard
Name: Jane Doe
Address: 1600 Amphitheatre Parkway, Mountain View, CA 94043
Country: USA
Bank: Bank of America
CVV: 202
Expires: 06/2026
Sequence: 1

Tokenization

Warning: The implementation is currently only available to registered partners. If you are a registered partner and would like to transmit receipts using Provider Id 2, contact us at [email protected] for more details.

Registered users can make use of the /tokens/identifiers endpoint of the API to tokenize an Identifier. We recommend this endpoint for testing purposes only! We recommend implementing the whole tokenization on the client side. Furthermore, we do not want any payment data on our platform, neither in the database nor in log files or similar. So the endpoint does not log any data.

In this step, you would tokenize the Identifier from the previous step. But this step is a bit more complex and currently only available to certified partners. We can go on using the tokenized representation of the Identifier we created for you: 2mdkUcY1XRGA2TBJW7wzto6niwipLhqz9fc. This one is calculated from Primary Account Number PAN (ISO/IEC 7812) and Provider Id 0x02.

Transmission Token

With the tokenized representation of the user's Identifier, we can go over to receive a Transmission Token from it. We need this token for transmitting a Receipt.

Receive Transmission Token for Maestro-/Giro-/Creditcard 💳

The recipe consists of the following steps:

curl -L --request POST \
  --url https://playground-api.wunderbon.io/tokens/transmissions \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer ${YOUR-TOKEN}' \
  --data '{"network": 2, "token": "2mdkUcY1XRGA2TBJW7wzto6niwipLhqz9fc"}'

You will receive a response which looks similar to the following one:

{
  "meta": {
    "success": true
  },
  "data": {
    "type": "Tokens",
    "attributes": {
      "token": "ac15d9238c384695901667433e7c3dc0c6231e2d",
      "expiresIn": 60,
      "created": "2022-01-10T22:09:34.053Z"
    }
  }
}

The token is linked to a dummy account of a user with Id c1de9956-9fca-42aa-87ef-a90a48c9d112 named Mrs. Jane Doe. This is the default Test User described above. If you submitted an unknown Identifier, you would receive a 404 response instead of a successful one.

Transmit a Receipt

Now we go to deliver a receipt to the user using the token ac15d9238c384695901667433e7c3dc0c6231e2d:

curl -L --request POST \
  --url https://playground-api.wunderbon.io/receipts \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer ${YOUR-TOKEN}' \
  --data '{"header":["..."], ...}'

If you would like to see more of the receipt data, have a look here.

{
  "meta": {
    "success": true
  },
  "data": {
    "type": "Receipts",
    "id": "c29041a5-038e-4e44-8b3b-745a929721a5"
  }
}

You receive the id of the receipt created. The hash of the receipt as persisted in Blockchain is added asynchronously. You will receive it with the receipt data from the API using the entity's id (e.g., c29041a5-038e-4e44-8b3b-745a929721a5).

Hooray!

It is so easy to deliver secure GDPR-compliant digital smart receipts by just using our 2-step protocol as seen here.

Info: Are you a POS Software Provider?

We are looking for strong partnerships in EMEA and worldwide. If you are developing POS-Software and/or providing hardware to Retailers/Merchants, then get in contact with our Revenue-Team and start providing additional high-quality and stable encrypted value-added services (VAS) by just partnering with us.

Earn fair by subscription share of aggregated clients. Find out more.