OAuth 2.0 Authentication Workflow

Introduction

This appendix describes a two-legged OAuth 2.0 flow that depicts app-to-app authentication. If you are not already familiar with the OAuth 2.0 authentication protocol, please refer to the following link for more detailed information on OAuth 2.0:

• https://auth0.com/docs/api-auth/which-oauth-flow-to-use

Components

The following components make up the authentication workflow:

• Partner client
• OAuth Authorization Server (part of the BaaS Platform)
  • Responsible for:
    • Issuing Credentials for clients – permanent
    • Issuing Access tokens (per provided Request tokens) – temporary
    • Validating Access tokens
• BaaS Platform API-s:
  • Any request to API-s must be made with an Access token, which will be validated by the API prior to executing it, per business logic.

The sequence in the diagram below, illustrates how Oauth2.0 authentication functions when making API calls.

Note: Step 0 (not in this diagram) assumes that valid credentials were issued to the Partner during the on-boarding process.

Client Credentials Flow

Endpoint: POST /authentication

This endpoint uses OAuth 2.0 and authenticates the client credential. It requests an access token that is required for all BaaS APIs. Access tokens are valid for a fixed period. Once expired, they must be requested again.

API Call Structure Parameters

• Authorization (String, Header) - Required. In the form of “Basic {ClientCredential}”, where Client Credential is Base64 encoded of ClientID followed by colon and clientSecret: “client_id:client_secret”.
• X-GD-RequestId (String, Header) - Required. A request identifier in UUID format.
• Content-Type (String, Header) - Required. Application/JSON.
• grant_type (String, Body) - Required.
• Scope (String, Body) - Optional. Note: Provide a value if specific scopes are requested.

Sample Request and Response

Request Details:-
POST /Authentication HTTP/1.1
Host:{BaaS Server}
X-GD-RequestId:e8459421-3cd1-497f-9dae-4507a37d2f56
Authorization:Basic c3RyaW5nOnN0cmluZw==
Content-Type":"application/json
Body:
{
  "grant_type":"client_credentials"
}

Response From Token Endpoint:-
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
Cache-Control:no-store
Pragma:no-cache
{
  "access_token":"{Access Token}",
  "token_type":"{Token Type}",
  "expires_in":{
    Lifetime in Seconds
  },
  "scope":"{Scopes}"
}

Oauth Access Token Validation

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}

Request Parameters

• X-GD-RequestID (String, Header) - Required. A request identifier in UUID format.
• Authorization (String, Header) - Required. In the form of “Bearer {Access_Token}”, where Access_Token is obtained using Authentication endpoint.
• accountIdentifier - (String, Path) - Required. A unique identifier for an account.
• programCode - (String, Path) - Required. A unique identifier for a program.

Request

GET …/programs/{programCode}/accounts/{accountIdentifier}

• Host: {BaaS Server}
• Authorization: Bearer 6ECC4zFnNAEZDwHM7twavw==

Response

If the request is not successful with invalid access token, the response message will be returned along with a 401 Unauthorized HTTP status code.

If the request is successful with valid access token, the request will be processed.

Virtual Analyst Feature

Green Dot is rolling out fraud reduction functionality to select partners to verify account activity. When the automated system suspects there may be a fraudulent transaction happening on the account, an SMS will be sent to the accountholder to verify the activity. If the accountholder responds that they didn’t initiate the transaction, the payment instrument used will be immediately blocked, and its status updated. This “Virutal Analyst” will set the following reasons when an instrument is blocked:

• PaymentIdentifierStatusReasons = "virtualAnalyst"
• PaymentInstrumentStatusReasons = "suspiciousActivity"

Once set, these status reasons will be returned as values in any payment instrument object return until the instrument is unblocked.

If you would like more information about this feature codenamed ‘Falcon’, contact your Green Dot representative.

Full PCI Data Access V2

GET /paymentInstruments

Private payment instrument data, such as the PAN, expiration date, and CVV can be made available via API to Partners based on their physical and virtual card configurations. Contact Green Dot if your program would like to consider implementing this API.

Partners can request the private payment instrument data for a specific payment instrument using the following API endpoint:

• GET /paymentInstruments/{paymentInstrumentIdentifier}?usage={usage}& pciData={pciDataArray}&IpAddress={IpAddress}
• “BaaS-Version: 2.0” indicated in header

Benefits

• Cardholder experience - Provide cardholders easy access to physical or virtual card details that can be used for online purchases, manual e-wallet provisioning, and mobile payments.
• Flexible payment methods - Ability for Partners to access full payment instrument data with third parties, such as push-to-card (or IFT) transactions over debit card rails.

How it Works

1. Partner is configured to access private payment instrument data.
2. Partner submits a request to GET /paymentInstruments/...
3. Request must include the header value “BaaS-Version: 2.0” to point to applicable API version.
4. New request parameters in URL string will indicate:
5. Usage: Purpose of the private payment instrument data request
6. PciData: The specific private payment instrument data points requested
7. IpAddress: The cardholder’s IP Address (required if usage=cardholder)
   iii. See Request Parameters for details.
8. Green Dot sends a response to the Partner containing the encrypted private payment instrument data.
9. Partner accesses private payment instrument data to:
   1. Display to cardholder: Cardholder views private payment instrument data and the event is logged and monitored by Green Dot.
   2. Partner usage: Partner uses private payment instrument data to initiate a transaction. Cardholder does not see display of private data.

Configuration Requirements

1. Partners should ensure they are Payment Card Industry Data Security Standard (PCI) compliant or have completed the relevant PCI requirements.
2. Partners should ensure they adhere to all relevant PCI requirements, such as not storing CVV information persistently.
3. Partners must ensure that cardholders complete a successful authentication within 10 minutes of their request and the PCI data being displayed to end users.
4. Partners must implement measures to prevent screen scraping, such as requiring a tap to display user action before displaying any PCI data.
5. Partners will decrypt the encrypted data transmitted from Green Dot to access the full card details.
6. Partners will need to request the appropriate configurations from Green Dot for both physical and virtual cards.
7. All cardholder actions that result in a display of PCI data are logged (including cardholder IP address) appropriately on the Partner side as well.

Sample Requests

Endpoint: GET /paymentInstruments

Structure of API Call:

GET /paymentInstruments/programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}?usage=cardholder&pcidata=pan,cvv,exp&ipAddress=127.0.0.1Sample Response

REQUEST

GET {{$host}}/baas/v1/programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/

{paymentInstrumentIdentifier}?usage=cardholder&pcidata=pan,cvv,exp&ipAddress=127.0.0.1

Content-Type: application/json

X-GD-RequestId: {{$guid}}

BaaS-Version: 2.0 ### WILL BE REQUIRED TO ACCESS API VERSION 2.0

{
   "paymentInstrument":{
      "encryptedPrivatePaymentInstrumentData":{
         "version":"EC_v1",
         "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWQyizlkN8/ZHSVMRDub1lwFuWzHWuFQ6rXUtAMOvQUiLxTBfzrw8XHlqe3PdxfeEA+Gq67E4TK0Bbt78ximFXw==",
         "publicKeyHash":"pD35siZ5RZWxW+zxEoZzbB0BMrhpTqQUYVMXchC5aC4=",
         "data":"BF9pkBjf0qGTksE0TdRUCoSR5LAYJrhyVdL4kMaysk0E11xPylAoschJqdOwhJpgsVzK/nuF/qZfo7RFvg8yNd28C4TrsPnONhVfNr0iRPqwQ81jionJE6/z9vCK"
      },
      "paymentIdentifier":"9da28b7d-876c-41f7-9e07-efc0b6095905",
      "paymentInstrumentIdentifier":"935f4eb2-458f-42c2-889f-d383ae2e6d75",
      "paymentInstrumentType":"emv",
      "status":"activated",
      "isPinSet":true,
      "last4Pan":"2777",
      "activatedDateTime":"2021-01-28T03:39:16Z",
      "issuedDateTime":"2021-01-28T03:38:58Z",
      "isPrivateDataViewable":true,
      "embossedName":"UrKLLvhy lRxPuPyt"          
	  ### DECRYPTED PAYLOAD
         {
         "pan":"4111999999991234",
         "cvv":"123",
         "expiration":{
            "month":"12",
            "year":"2020"
         }
      }
   },
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Request Parameters

Error Codes

Voice Dial Functionality Feature for Multi-Factor Authentication Phone Call

This feature allows a customer to receive a phone call that recites and transcribes the MFA code so that the customer can enter it into the phone verification screen.

Sample Request for Voice Call

{
   "verificationEventType":"registration",
   "contactType":"Phone",
   "contactHandle":"6554952560",
   "accountIdentifier":"",
   "firstName":"",
   "lastName":"",
   "productCode":"40002",
   " CommunicationType":"VoiceCall"
}

Sample Response for Voice Call

{
   "contactVerificationIdentifier":"d6a577b8-85db-4c55-b8ba-2281fb1ac07b",
   "responseDetails":[
      {
         "code":0,
         " subCode":0,
         "description":"success",
         "url":"http://tbd"
      }
   ]
}

Partner Response Codes

Scenarios