Skip to content

Acquiring a bearer token

Use the OAuth 2.0 token exchange to retrieve an access token that can be used in subsequent requests to Worldline REST APIs.

This section will guide through the details on how to successfully create a signed and base64 encoded JWT which will be posted to Worldline to exchange that for an access token.

There are several libraries that can aid you in creation of a JWT, and using the information here you can create one. For reference, see reference guide on JWT with OAuth 2.0.

Create the JWT

A JSON Web Token is composed of three parts: a header, a claim set and a signature. The header and claim set are JSON objects, serialized to UTF-8 bytes and encoded using Base64url encoding. The header, claim set and signature are concatenated together with a period “.” character.

1. Construct the JWT header

Create an encoded_JWT_Header:

{“alg”:”PS256”,”typ”:”JWT”}

2. Base64url encode the JWT Header

Base64URL encode the header, as defined in http://tools.ietf.org/html/rfc4648#page-7. The result should be similar to:

eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9

3. Construct a JSON claim set

The claim set will have the attributes iss, aud, exp, iat, and the optional consumerid

Example claim set is shown below:

    {
      "aud": "drwp",
      "iss": "application-1@123456789",
      "scope": "OrderProcessingService:GET:/v2/merchants/{mid}/orders/{orderId}",
      "exp": 1559062205,
      "iat": 1559062145
    }

4. Base64url encode the claim set.

Result will be like, call this encoded_JWT_Claims_Set.

eyJhdWQiOiAiZHJ3cCIsImlzcyI6ICJhcHBsaWNhdGlvbi0xQDEyMzQ1Njc4OSIsInNjb3Bl
IjogIk9yZGVyUHJvY2Vzc2luZ1NlcnZpY2U6R0VUOi92Mi9tZXJjaGFudHMve21pZH0vb3Jk
ZXJzL3tvcmRlcklkfSIsImV4cCI6MTU1OTA2MjIwNSwiaWF0IjoxNTU5MDYyMTQ1fQo

5. Concatenate the header and claim set

Create a new string header_payload_encoded for the encoded JWT Header and the encoded JWT Claims Set as follows:

header_payload_encoded = encoded_JWT_Header + "." + encoded_JWT_Claims_Set

Note the . on the first line of the payload:

eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiAiZHJ3cCIsImlzcyI6ICJhcHB
saWNhdGlvbi0xQDEyMzQ1Njc4OSIsInNjb3BlIjogIk9yZGVyUHJvY2Vzc2luZ1NlcnZpY2U
6R0VUOi92Mi9tZXJjaGFudHMve21pZH0vb3JkZXJzL3tvcmRlcklkfSIsImV4cCI6MTU1OTA
2MjIwNSwiaWF0IjoxNTU5MDYyMTQ1fQo

6. Create a signature of the payload

Sign the resulting string using SHA256 with RSA, and Base64url encode the result.

7. Concatenate the payload and signature

Create a new string jwt_final_encoded, in the following format:

jwt_final_encoded = header_payload_encoded + "." + base64_encoded_signature

The result should be similar to below where the signature part is highlighted.

    eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiAiZHJ3cCIsImlzcyI6ICJhcHB
    saWNhdGlvbi0xQDEyMzQ1Njc4OSIsInNjb3BlIjogIk9yZGVyUHJvY2Vzc2luZ1NlcnZpY2U
    6R0VUOi92Mi9tZXJjaGFudHMve21pZH0vb3JkZXJzL3tvcmRlcklkfSIsImV4cCI6MTU1OTA
    2MjIwNSwiaWF0IjoxNTU5MDYyMTQ1fQo.EsC5RCTbkV-JJVqInSL0kaepD8C7y3Lj2xlplRr
    bv3v1nVmx1n5wgjYR0VsFMF-GZxIneWFueKDTM4CsC12BKkl-Bqg95amSdFT_3gqMPpgyZsB
    tyMVSn4G6Y6YNIAomAWWNRlifkk6Tcqzt-pHVzPxFUYzbp6e85nlXNLJ5Oxh6v60nynyT0ZS
    WTuptROGvIC-8hmm4NsPqCOkT-XNWdSlBcvhR_Tt8o0afaARsq_NWKSLLIZuybz73OZGQRCP
    nkmPylpxCQpRq0M38hcoMlaTtBTdnWCMiLOvH4EaCIYalNAAfCkL_EcM3cEpDh_TO29QA4K7
    uYrYzkljw8PiPxA

Exchange the JWT for a bearer token

8. Send the JWT

HTTP
POST /v2/oauth2/tokens HTTP/1.1
Host: auth-endpoint
Content-type: application/x-www-form-urlencoded

jwt=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiAiZHJ3cCIsImlzcyI6ICJhcHBsaWNhdGlvbi0xQ...(abbreviated)
CURL
curl -s -X POST \
     -H "Content-type: application/x-www-form-urlencoded" \
     auth-endpoint \
     -d "jwt=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiAiZHJ3cCIsImlzcyI6ICJhcHBsaWNhdGlvbi0xQ...(abbreviated)"

9. Read the bearer token

The Worldline security service will, given that there is an active application user and that the JWT is correct, return a bearer token that is valid for a specified period of time.

Response
HTTP/1.1 201 Created
Cache-Control: no-store
Content-Type: application/json
Date: Thu, 23 May 2019 17:59:54 GMT
Pragma: no-cache
Content-Length: 119

{"access_token":"6c4fd6d6bee22f557cf65d9c06ebb8f6d5a43e","token_type":"Bearer","expires_in":3600,"number_of_retries":0}

Call a secured service

At last, we will use the bearer token to call on a Worldline service:

10. Use the bearer token

HTTP
GET /v2/merchant/1234567890/orders/my-order-1 HTTP/1.1
Host: transactions-endpoint

Authorization: Bearer 6c4fd6d6bee22f557cf65d9c06ebb8f6d5a43e
CURL
curl -X "Authorization: Bearer 6c4fd6d6bee22f557cf65d9c06ebb8f6d5a43e" \
  https://transactions-endpoint/v2/merchant/1234567890/orders/my-order-1
Back to top