Integrating With the Green Dot Network Service

The POB (Point of Banking) Partner API provides an alternative method to the Consumption API to receive cash deposit transactions to debit card accounts. This API also:

Authenticates Green Dot and its partners

Obtains customer information

Processes transactions

Returns responses back to the retailer

Following is an illustration of how Green Dot networks communicate with POB partners.

Authentication

Green Dot supports three types of authentications:

Certificate Based
OAuth 2.0
Basic Authentication Based User Name and Password

A description of each type follows.

Certificate-Based Authentication

Certificate-based authentication uses a Digital Certificate to identify a user, machine, or device before granting access to a resource, network, application, and so on.POB partners need to sign Green Dot's CSR (Certificate Signing Request) and setup the certificate on your server for decryption. This will be followed up by Green Dot’s System Engineering team.

OAuth2.0 for Authentication

This API allows you to accept an OAuth request from Green Dot

OAuth 2.0 protocol is the industry-standard protocol for authorization. To begin, Green Dot:

Obtains OAuth 2.0 client credentials from POB partners' by secure email (Non-Prod and Prod).
The Green Dot client application requests an access token from the POB partner Authorization Server, extracts a token from the response, and sends the token to the POB partner's API that you want to access.

Note: If you choose OAuth 2.0 authentication, Green Dot will need your OAuth credentials. For non-production environments, the Green Dot technical team also needs these credentials for testing.

Please contact your Green Dot Product Owner for assistance.

Structure of API Call:

POST ~/v1/oauth2/token

SLA Response and Resolution Time: 1s

Request Parameters

Parameter Name	Type	Format	Required	Description
Content-Type	string	Header	Required	"application/x-www-form-urlencoded"
client_id	string	Body	Required	The partner-provided ID of the application asking for authorization.
client_secret	string	Body	Required	The partner-provided secret known only to your application and the authorization server.
grant_type	string	Body	Required	The grant type for this flow. Always pass client_credentials.
Scope	string	Body	Required	A space-delimited list of permissions that the application requires. Value = general.

Sample Request

curl
--location
--request POST 'https://{base_url}/v1/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=general'

Response Message

If the POST request is successful, the response fields are returned along with a HTTP response code 200 (OK). If the request fails, the response fields are returned with the related HTTP response codes and error codes.

Response Parameters (Success)

Parameter Name	Type	Required	Description
access_token	string	Required	Encapsulating the security identity of a process or thread, this token is used to make security decisions and to store tamper-proof information for system entity.
token_type	string	Required	Methods to get access tokens from the authorization server are called grants. Here we expect "Bearer" as the token type.
expires_in	string	Required	The lifetime (in seconds) of the access token.
scope	string	Required	A space-delimited list of permissions that the token contains. As a default, we expect full access permissions for all POB partner APIs.

Response Parameters (Failure)

Parameter Name	Type	Required	Description
errorCode	string	Required	The error code.
errorMessage	string	Required	The error message.

Sample Responses

Success

{  
    "access_token": "xxxxxx",  
    "token_type": "Bearer",  
    "expires_in": 86400,  
    "scope": "general"
}

Unsupported Grant Type

{  
    "errorCode": "UNSUPPORTED_GRANT_TYPE",  
    "errorMessage": "An invalid string for grant_type field has been used."
}

Invalid Grant Type

{  
    "errorCode": "INVALID_GRANT_TYPE",  
    "errorMessage": "An invalid code when exchanging an authorization code for an access_token."
}

Invalid Client

{  
    "errorCode": "INVALID_CLIENT",  
    "errorMessage": "Either your client_id or client_secret is invalid."
}

Basic Authentication Based User Name and Password

Basic authentication is where a client sends a request with the client credentials in the Authorization header. The credentials are formatted as the string "name:password", base64- encoded. The credentials are not encrypted.

For example, to authorize when name is "demo", password is "p@55w0rd", credentials are formatted as the string " demo: p@55w0rd ", base64-encoded as ” ZGVtbzpwQDU1dzByA==”, the client would send the following: Authorization: Basic ZGVtbzpwQDU1dzByA==

For additional information refer to: https://docs.microsoft.com/en-us/aspnet/web-api/overview/security/basic-authentication

Note: POB partners must provide name and password.

Retrieve Customer Information

Overview

The Customer Information API is used to retrieve POB partner customer information.

Note: To test this API, you must provide a test account for each scenario. Please send test data in an email to: [email protected].

GET~/customers/accounts/search

SLA Response and Resolution Time: 1s

Request Parameters

Parameter Name	Type	Format	Required	Description
x-GD-RequestId	GUID	Header	Required	Unique ID generated by GD to identifying the request for tracking purposes.
Content-Type	string	Header	Required	"application/json"
accountNumber	string	Body	Required	The account number.
retailer: storeNumber	string	Body	Optional	Store number
retailer: storeName	string	Body	Optional	Store name
retailer: stateCode	string	Body	Optional	State code
retailer: latitude	decimal	Body	Optional	Store location latitude
retailer: longitude	decimal	Body	Optional	Store location longitude

Response Message:

If the GET request is successful, the response fields are returned along with a HTTP response code 200 (OK). If the request fails, the response fields are returned with the related HTTP response codes and error codes.

Response Parameters (Success)

Parameter Name	Type	Required	Description
customerId	string	Required	The customer identifier.
accountId	string	Required	The account identifier.
firstName	string	Required	First name of cardholder.
lastName	string	Required	Last name of cardholder.
zipCode	string	Required	Cardholder home zip code.
expiryYear	string	Required	Format YYYY
expiryMonth	string	Required	Format MM (i.e., 01 for January)

Response Parameters (Failure)

Parameter Name	Type	Required	Description
errorCode	string	Required	The error code
errorMessage	string	Required	The error message

Sample Responses

Obtain valid customer

{
    "customerId": "0033B00000ToKB8QAN",      
    "accountId": "a0I3B000001qiEsUAI",
    "firstName": "Nancy",      
    "lastName": "Yang",     
    "zipCode": "02110",      
    "expiryYear": "2030",     
    "expiryMonth": "01"
}

Customer not found

{      
    "errorCode": "ACCOUNT_NOT_FOUND",      
    "errorMessage": "The provided account doesn't exist ..."
}

Obtain Retail Store Information by Zip Code or Location

To return a list of stores to the partner’s POB customers, the POB Partner API uses the Store API is to look for the enabled retailer’s store information by zip code or location.

For more information refer to the Store API documentation section.