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.

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-

• Method: POST
• Authorization Type: OAuth 2.0
• Auth URI: https://api-test.shell.com/v1/oauth/token
• Client_Id: **** (OAuth Client ID)
• Client Secret: **** (OAuth Client Secret)
• Grant Type: client_credentials

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"
}

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

• Method: GET
• Authorization Type: OAuth 2.0
• Auth URI: https://api-test.shell.com/test/pin-management/v1/generatepinkeys

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

! Please note the code library can be downloaded from the developer portal soon. Until then please reach out to 'api@shell.com' to access the library

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

• Javascript (Node.js)
• C#

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

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.

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,
}