Skip to main content

B2B Mobility Card Pin Management 1.0.12

Getting Started with B2B Shell Card Pin Management

B2B Shell Card Pin Management

Shell Card pin management has been updated with 2 major steps to be followed.

  1. Get the public RSA Key
  2. Encrypt the desired pin along with the RSA Key in Shell provided encryption logic.
  3. Send the encrypted values when ordering cards using our order card API.

More detailed explanation is provided in this guide along with the clear representation of the flows.

sequenceDiagram participant PartnerApplication participant Shell Authentication participant Shell API participant Shell Code Library autonumber alt Manual Process rect rgb(200, 150, 255) PartnerApplication ->>Shell Authentication: Request Client ID and Client Secret activate Shell Authentication Shell Authentication ->> PartnerApplication : Generate and provide Client ID and Client Secret deactivate Shell Authentication end end alt Authentication/Authorization rect rgb(191, 223, 255) PartnerApplication ->>Shell Authentication: Inititate request to OAuth end point activate Shell Authentication Note right of PartnerApplication: Client ID and Secret Shell Authentication ->> PartnerApplication : (200-OK) Returns Bearer Token deactivate Shell Authentication Note left of Shell Authentication: Access Token end end alt pin-management/v1/generatepinkeys rect rgb(200, 150, 255) PartnerApplication ->>Shell API: Initiate request to get the public RSA key to encrypt PIN activate Shell API Note right of PartnerApplication: Access Token Shell API ->> PartnerApplication : Returns a response on validation of the bearer token with RSA key deactivate Shell API Note left of Shell API: UID, value end end alt Shell PIN Encrypt Code Library rect rgb(191, 223, 255) PartnerApplication ->> Shell Code Library: Use Code library provided by Shell to encrypt the PIN activate Shell Code Library Note right of PartnerApplication: UID, value, pin (which user wants to use) Shell Code Library ->> PartnerApplication: Get all the encoded values after encryption deactivate Shell Code Library Note left of Shell Code Library: UID, Encrypted base64 encoded message, Encrypted base64 encoded Details end end alt ONLY in UAT to test rect rgb(200, 150, 255) PartnerApplication ->>Shell API: Initiate request to pin-management/v1/validatepin API to verify the PIN encryption activate Shell API Note right of PartnerApplication: Access Token, UID, Encrypted base64 encoded message, Encrypted base64 encoded Details Shell API ->> PartnerApplication : Returns a response with the pin used during encryption deactivate Shell API Note left of Shell API: pin end end alt card-management/v2/ordercard rect rgb(191, 223, 255) PartnerApplication ->>Shell API: Initiate request to order card along with the encrypted details activate Shell API Note right of PartnerApplication: UID, Encrypted base64 encoded message, Encrypted base64 encoded Details Shell API ->> PartnerApplication : Returns a response on validation for ordering card deactivate Shell API Note left of Shell API: CardReferences, OrderReference end end

Authentication

Shell API’s are secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The end to end process is illustrated in the sequence diagram below.

This step is to generate the API Access Token using the unique Client ID and Client Secret provided by Shell. (Please note that this credentials is to validate the API request between Shell and its partner so its system to system access token)

Key Request Parameters

Once you receive the client ID & Secret, next step is to call the https://api-test.shell.com/v1/oauth/token endpoint to authenticate. Following are the key parameters-

Sample cURL Request

curl --location --request POST 'https://api-test.shell.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=*************' \
--data-urlencode 'grant_type=client_credentials'

On receiving the request Shell Authorization system will verify all the parameters in the request and, if everything checks out, it will generate your access token and return it in the response.

Sample Response

{
    "access_token": "***********",
    "token_type": "Bearer",
    "expires_in": 899
}

The response will contain the following parameters:

  • access_token: The token to be used to call the functional APIs
  • expires_in: The amount of seconds until the access token expires.
  • token_type: Bearer

Exception Handling

All error scenarios are returned with a response body and identifier.

{
      "error_descrription": "invalid client or client credentials",
      "error": "invalid_client"
}
HTTP Code Description Scenarios
400 Bad Request If Invalid scope passed to Token url
Invalid grant type passed to Token url
401 Unauthorized If Invalid id/secret passed to Token url
If Invalid or expired token passed to destination system’s API

Get Public RSA Key

In this step a public RSA Key is generated which needs to be used in the pin encryption code library.

Only the authorization token need to be passed in this end point which will verify the user and provide 2 parameters in the response

  • UUID - Unique identifier generated for the request
  • Value - Base64 encoded RSA public key in PEM format

Key Request Parameters

Sample cURL Request

curl --location --request GET 'https://api-test.shell.com/test/pin-management/v1/generatepinkeys' \
--header 'Authorization: Bearer **************' 

Sample Response

{
    "uid": "2K83*******USsyHEnE8E1u979",
    "value": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lEQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnMEFNSUlDQ0FLQ0FnRUEyb2dVM0I2U0sxLytudy9IZUFwUwp4WDBDb1FCVTVKZXhMRThWc2F1KzA2RFBabURZZWwvNmtNYXYrallVTzllR1cvczVUemI1Zm1wVGI5WF***************************xWUV6ZXlVemNGb0cKVmxDODd1dW8wZDNad1Vnd0d5R1FQZEEzUFkzazNIQlhaN3J3Nm5udWtWdXlkTWRUUE5oUVpJbVB1aEFQV3g1SAo4eG80SEJDMDZ1aENsYm1xZ0dJM2tFWWZ4QXIvVm5hWUN1ckJZUm1NYTYwTmlteGcrZHlwVENTdS80ajQ3VnF0CldFaEp3Y2FhbTF1MkxiV3RWZGhwbDdjQ0FRTT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
}

Encyrpt the desired PIN using Shell Code Library

Shell provides the technical solution in order to encrypt the desired PIN for the user using the Shell Code Library available in 3 programming languages

  • Javascript (Node.js)
  • C#
  • Java

Also provided with the library is a simple HTML page which runs the library and prints the output for your reference.

The Code libraries for all above 3 languages can be downloaded from here - Shell ePin Code Libraries

Key Request Parameters

The key parameters to be passed into the code library are

  1. UUID
  2. Value (RSA Public Key)
  3. PIN

Note:

  1. UUID and Value passed in the library needs to be generated from the previous step using endpoint - /generatepinkeys
  2. Please note that there are set of Weak PIN validations that are recommeneded from Shell.

Key Response Parameters

Once the code library is saved with all the above 3 values passed, then the HTML page needs to be opened in order to view the output. Below parameters are provided in the response.

  1. RSA public key UID
  2. Encrypted base64 encoded message
  3. Encrypted base64 encoded details

Verify the encrypted PIN

! Please note this process to verify the encyption is availbale strictly only in UAT environment

In order to verify the encryption was executed as per Shell logic, this end point can be used in order to view the PIN.

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/test/pin-management/v1/validatepin
  • Headers :
    • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
    • Content-Type : application/json
  • Body :
    • uid : Unique identifier for the request.
    • encrypted_pin : Base64 encoded and encrypted PIN block.
    • session_key : Base64 encoded and encrypted details for decryption.

Sample cURL Request

curl --location --request POST 'https://api-test.shell.com/test/pin-management/v1/validatepin' \
--header 'Authorization: Bearer 9tScPA8lGkq7dyu6bmAvZ7vn8RsX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uid": "2K86mSOt4tHd*******6Ld5KpC1m1GKjI0",
    "encrypted_pin": "i+Qib**********ldxZsmpvpkS7fqynjjPd3KtLA+V5XtgXXwBrH1zTadMtF0+ks=",
    "session_key": "KZ8EHcq4gVuw8iGKPL4RqK2nH0R0P70iMj3IN8ZCxpgMmhJnPvAXSCoaLgURd943XlX9GpKlzhKkd/VIot2o3sN5P6lTpv1KVYWE6wrDiNpsWO2TVhvoD0+************+sYswJpGomiMkaF+Zq9CIveGFmhGU0csZa9+14X60eu2VMb4Q5JKcmydISxJ/61F3a5Xex6+IC1Cs3MeHBn55ayZcCSdkSSuvXB+R/aG84xSKmwUyWmmXstTNuYYIOiiNkCVtA1Wo1XQprGEJcGQ2FqlidFifeqX/*********+QIeo7VXv1Uu0zuBFj4fYuHOF4wAXL3u25JjK+PKUDXjAyAqq0h4C5jNnRLbNCM9yQKhFl3ayiiBtVRGe1P/YPedCXeRu8aRC6qnjSfzm8LlSiV8C7+27TP8f4zj/MuBC0CcZQ0XS2SbrVV93wTzbFBXQB3wir6z79eGZfshi1KGeB+lmRYTtTBTs2TBwiMVSO/be7ixf9XlgAESfN6FF7lP+yvKW1FtrJO8ZQBKKhJ9UZtKe4e/y70yNLQE/F8T/GrH6ebP+aUclLga0qIjIzi1hRX2dm4UhGiK23xfKuZKc7q3NGiX+Nm2Fd8="
}'

Sample Response

{
    "pin": "1920"
}

Order Card using the encrypted values

Once the encryption is done all the below 3 parameters need to be included in the Order Card endpoint in order to receive the Shell card with the requested PIN.

Parameters in Shell Code Library Parameters in Card Order API Description
uid SelfSelectedPINKeyID Unique identifier for the request
encrypted_pin SelfSelectedEncryptedPIN Base64 encoded and encrypted PIN block
session_key SelfSelectedPINSessionKey Base64 encoded and encrypted details for decryption

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/test/fleetmanagement/v2/card/OrderCard
  • Headers :
    • Authorization : Uses Basic Authorization Scheme Passing base64 encoded ConsumerKey + Secret as Authorization.
    • apikey : This is the API key of the specific environment which needs to be passed by the API client.
    • Content-Type : application/json
  • Body :
    • SelfSelectedPINKeyID : Unique identifier for the request (uid)
    • SelfSelectedEncryptedPIN : Base64 encoded and encrypted PIN block (encrypted_pin)
    • SelfSelectedPINSessionKey : Base64 encoded and encrypted details for decryption (session_key)

Sample cURL Request

curl -X 'POST' \
  'https://api-test.shell.com/fleetmanagement/v2/card/OrderCard' \
  -H 'accept: application/json' \
  -H 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer **********' \
  -d '{
  "CardDetails": [
    {
      "ColCoCode": 5,
      "PayerNumber": "GB00000003",
      "AccountNumber": "GB00000003",
      "CardTypeId": 503,
      "DriverName": "John Smith",
      "TokenTypeId": 500,
      "EmbossText": "JSMITH",
      "PurchaseCategoryId": 104,  
      "SelfSelectedEncryptedPIN": "0hCx7wfFp3z8QkW8dElhHiMwCwC1",
      "SelfSelectedPINKeyID": "123aaa33198dc8f3s4k77dsc78",
      "SelfSelectedPINSessionKey": "WoWB+8UEd71+8QXwuE75flkAQ /4Q6gDFSn027oJ/0ne6LmzVIxJ87yoeqKS /C+OIBJ7bTvasLH+xvDSZtzoOZHr 7wfFmpfSyet8KnKjnagSicrUgpGk 7qFyOw3iA9/Qd6Oy9djYR3C3cDWEpj /YREZ1lBGReb9fqdSpoKx8mnGuPAw7",
      "CardDeliveryType": 1,
      "CardContact": {
        "DeliveryContactTitle": "Mr.",
        "DeliveryContactName": "Robert",
        "DeliveryCompanyName": "WILTON AUFDERHAR ",
        "DeliveryAddressLine1": "Herrn Dieter Whausen Lansstrab ",
        "DeliveryAddressLine2": "10th avenue",
        "DeliveryAddressLine3": "makati city",
        "DeliveryZipCode": "12130",
        "DeliveryCity": "manila",
        "DeliveryRegionId": 43,
        "DeliveryRegion": "Philippines",
        "DeliveryCountry": "WILTON AUFDERHAR",
        "PhoneNumber": 99999999999,
        "EmailAddress": "xxxxx@example.com",
        "SaveForCardReissue": false
      },
      "PINDeliveryAddressType": 1,
      "PINAdviceType": 1,
      "PINContact": {
        "DeliveryContactTitle": "Mr.",
        "DeliveryContactName": "Robert",
        "DeliveryCompanyName": "WILTON AUFDERHAR ",
        "DeliveryAddressLine1": "Herrn Dieter Whausen Lansstrab ",
        "DeliveryAddressLine2": "10th avenue",
        "DeliveryAddressLine3": "makati city",
        "DeliveryZipCode": "12130",
        "DeliveryCity": "manila",
        "DeliveryRegionId": 43,
        "DeliveryRegion": "Philippines",
        "DeliveryCountry": "WILTON AUFDERHAR",
        "PhoneNumber": 99999999999,
        "EmailAddress": "xxxxx@example.com",
        "SaveForPINReminder": false
      }
    }
  ],
  "RequestId": "ed557f02 - c7d7 - 4c01 - b3e5 - 11bf3239c8ed"
}'

Sample Response

{
  "CardReferences": [
    {
      "DriverAndVRN": "John Smith;1234",
      "OrderCardReference": 229781
    }
  ],
  "OrderReference": 181565,
}

About us

The Shell Developer Portal is here to support partners to onboard to Shell APIs, the portal is here to take ideas to production

 

Shell logo

Login to your account