OAuth 2.0 Authentication Workflow

OAuth 2.0 Authentication Workflow


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:


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}
Authorization:Basic c3RyaW5nOnN0cmluZw==

Response From Token Endpoint:-
HTTP/1.1 200 OK
  "access_token":"{Access Token}",
  "token_type":"{Token Type}",
    Lifetime in Seconds

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.


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

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


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


  • 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= Response


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


Content-Type: application/json

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


      "embossedName":"UrKLLvhy lRxPuPyt"          

Request Parameters

Parameter NameTypeAllowed ValuesNotes
usageenum cardholder
cardholder=data retrieved from this API call will be shown directly to the cardholder.

partner=data retrieved from this API call will be used for partners own workflow and not directly shown to the cardholder.
pciDataarray of enum- pan
- exp
- cvv
Indicate which PCI secured data to return.

- pan=card number (e.g. 16 digits on front of card)

- exp=card expiration date (month & year)

- cvv=card verification value (e.g. security code)

Unencoded URL format should be comma separated list:


2607:f0d0: 1002:0051: 0000:0000:0000:0004
Cardholder mobile/web IP address if usage=cardholder.

IP4 and IP6 format accepted.

Required field if usage=cardholder.

Optional field if usage=partner.

Error Codes

Error ScenarioCodeHTTP Status CodeDescription
Partner is not configured for private payment instrument data365400Please reach out to Partner Support to setup configuration.
Parameter missing200400Required property missing or missing a value
Invalid format350400The format of the string or number was invalid.

Commonly related to IP address parameter.

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

   " CommunicationType":"VoiceCall"

Sample Response for Voice Call

         " subCode":0,

Partner Response Codes

5391A previous voice call was sent within 2 minutes
5392Calls are prohibited
5393Failed to call Twilio
5390The maximum number of Voice Calls within 24 hours has been exceeded
6000Invalid Communication Type


ContactType is not VoicecallProcess the same as for SMS and email.
Phone is in Twilio Prohibited area codesReturn a Calls Prohibited error.
Exceeded voice call limitReturn a Call Limit Exceeded error.
Exceeded voice rate limitReturn a RateLimit exceeded error.
Latest record is not voice call, and expiration time is less than 3 minutesGenerate a new MFA code, call Twilio with PhoneNumber and MFACode, and return sessionCode.
Latest record is not voice call, and expiration time is more than 3 minutesCall Twilio with PhoneNumber and MFACode and return sessionCode.
Latest record is voice call, and existing code is not expiredCall Twilio with PhoneNumber and MFACode and return sessionCode.
Latest record is voice call, and existing code is expiredGenerate a new MFA code, call Twilio with PhoneNumber and MFACode, and return sessionCode.