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.
- Get the public RSA Key
- Encrypt the desired pin along with the RSA Key in Shell provided encryption logic.
- 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"
}
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
- 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
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
- UUID
- Value (RSA Public Key)
- PIN
Note:
- UUID and Value passed in the library needs to be generated from the previous step using endpoint - /generatepinkeys
- 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.
- RSA public key UID
- Encrypted base64 encoded message
- 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,
}