Reload

Get Card Reload API Method

This method is used to reload money to a Green Dot or a Green Dot Partner Card.

📘

Every request triggered should have a unique X-GD-RequestId value in the header

Syntax

POST {baseUrl}/reload/execute

Example Request

Success Request

POST {baseUrl}/reload/execute
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: 123456789

{
  "metadata": {    
    "merchantId": "FSCC0342",
    "registerId": "01001",
    "requestDateTime": "2013-09-18T10:53:00Z",    
    "storeId": "CC970",
    "userId": "[email protected]"
  },
  "accountNumber": "1234567890123456",
  "paymentProgramType": "Regular",
  "transactionAmount": 50.00,
  "accountIdentifier": "",
  "reloadType": "SwipeReload"
} 

Negative Request

POST {baseUrl}/reload/execute
X-GD-RequestId: 35962988448630
Content-Type: application/json
Authorization: Bearer {token}

{
    "accountNumber":"1234567890123456",
    "paymentProgramType":"Regular",
    "transactionAmount":20,
    "accountIdentifier":"",
    "reloadType":"SwipeReload",
    "metadata":{
        "storeId":"CC988",
        "merchantId":"FSCC0342",
        "userId":"[email protected]",
        "requestDateTime":"2023-09-22T02:23:31Z",        
        "registerId":""
    }
}

Request Parameters

Parameter

Required(Y/N)

Format/Data Type

Pattern

Description

X-GD-RequestId

Yes

String

MaxLength:50

It is a unique transaction identifier that is generated by the retailer.

requestDateTime

No

DateTime

2023-08-08T12:34:56Z

Time stamp at which transaction occurred.
The time stamp has to be in UTC time zone and follow the following date and time formats:
• YYYY-MM-DDTHH:mm:ssZ

registerId

No

String

MaxLength: 20

Register where the transaction occurred.

userId

No

String

MaxLength:50

The unique ID of the user generating the transaction.
UserID is now a required field to support ‘teller incentive program’.

storeId

Yes

String

MaxLength: 20

The store number associated with the retailer that sold the package.
If not supplied, InvalidParameter (Code:100) error will be return.

merchantId

Yes

String

MaxLength: 20

The unique merchant Id. Defined by Green Dot – Merchant corresponding with Retailer.

accountNumber

No

String

16 digits PAN

Account Number (PAN) of the card.
Note: Either AccountNumber or AccountIdentifier is required.
Standard Partner must provide AccountNumber

transactionAmount

Yes

Decimal

500.00

Amount of money to be reloaded. Must be greater than zero.
For example: Five Hundred Dollars is entered as 500.00. Twenty Dollars is entered as 20.00.

paymentProgramType

Yes

Enum

Regular,
CheckCashing

Type of payment option that customer selects.
For example:
• If the customer is paying with a check, then it will be “CheckCashing”.
• If they are paying by cash, or a combination of check and cash, PaymentProgramType will be “Regular”.

accountIdentifier

No

GUID

e5843e05-d367-4bf1-a223-3af46ae18802

Newly created unique identifier for sale card, should be using for all subsequent API calls
Note: Either AccountNumber or AccountIdentifier is required

reloadType

No

Enum

InitialLoad ,
SwipeReload

ReloadType includes the following values:
• SwipeReload
• InitialLoad
If request doesn’t provide the ReloadType, it will use ‘SwipeReload’ as the default value.

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: 201309181254
X-GD-ResponseId: 873e01e2-76fe-4fd1-8b18-2ccf5f2d5af9
X-GD-ResponseCode: 1
{
    "metadata": {
        "requestId": "201309181254",
        "responseCode": 1,
        "responseDescription": "SuccessFundingDelay",
        "responseDateTime": "2013-09-18T10:53:10.2543261Z",
        "responseId": "873e01e2-76fe-4fd1-8b18-2ccf5f2d5af9"
    },
    "pendingBalance": "100.00",
    "fundingDelaySeconds": "60",
"isGDN": false,
"receiptText":"Keep your receipt as proof of your reload. Check with your card provider for your updated account balance. Stores cannot provide refunds or exchanges."    
}

Negative Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-GD-RequestId: 35962988448630
X-GD-ResponseCode: 861
X-GD-ResponseId: 32ff3f6a-c4cf-4b87-94f3-f8cb62ce93ff

{
    "pendingBalance": null,
    "fundingDelaySeconds": null,
"isGDN": false,
"receiptText":"",
    "metadata": {
        "requestId": "35962988448630",
        "responseId": "32ff3f6a-c4cf-4b87-94f3-f8cb62ce93ff",
        "responseDateTime": "2023-09-22T02:23:37.4826331Z",
        "responseCode": 861,
        "responseDescription": "User is not found."
    }
}

Response Parameters

Parameter

Required(Y/N)

Format/Data Type

Pattern

Description

requestId

Yes

String

MaxLength:50

The unique request ID from request.

responseId

Yes

String

MaxLength:50

The unique response identifier (generated by GreenDot).

responseDateTime

Yes

DateTime

2023-09-07T16:12:23.4541445+08:00

Time stamp at which transaction occurred.
The time stamp is in UTC time zone and follow the following date and time formats:
• YYYY-MM-DDTHH:mm:ssfffffffK

responseCode

Yes

Numeric

MaxLength:4

Indicates success and failure of the response codes. It is in the numeric format.

responseDescription

Yes

String

MaxLength:255

Describes the Response Code in more detail. It is in the String format.

pendingBalance

Yes

String

“1500.00”

Transaction amount + card balance will be returned as PendingBalance in successful response. Only successful reload will have pendingBalance value.

fundingDelaySeconds

Yes

String

“60”

The length of the funding delay in seconds. The transaction may be voided immediately after it had succeeded and up to FundingDelaySeconds. Please note that the actual delay the funds will be usable may be up to 2 minutes longer that this value due to some asynchronous processing in the backend system. Only successful reload will have fundingDelaySeconds value.

isGDN

No

Boolean

true/false

Indicates that the reloaded card is a GDN card.

receiptText

No

String

Max 1000

Describes the receipt text.

Response Codes

Code

CodeText

Response Description

Explanation of the Response Code

1

SuccessFundingDelay

SuccessFundingDelay

Success with funding delay. For transactions that have funding delay.

100

InvalidParameter

• Either AccountNumber or AccountIdentifier is required
• MerchantId is required
• RequestId is required
• RequestDateTime is required
• UserId is required
• StoreId is required
• RequestId is too long
• UserId is too long
• StoreId is too long
• MerchantId is too long
• Invalid length of AccountNumber
• The field RegisterId must be a string or array type with a maximum length of '20'.

Invalid parameter when validating request.

460

OperationNotAllowed

Invalid Initial Load Request

Invalid Initial load. Initial load can only be done once.

This response code will be used if card already had initial load
OR
Time window for the initial load has expired.
OR
Perform InitialLoad with invalid card

130

InvalidMerchant

InvalidMerchant

MerchantId in request has not been found/enabled in the system.

800

InvalidStore

• Store was not found
• Store feature is invalid

Store is not found; store is not for the partner or store does not support this operation.

801

StoreBlocked

The store is blocked

Store is blocked by store blocker rule.

861

RetailChainUserNotFound

User is not found.

UserID in the request is not found in system.

862

RetailChainUserNotActive

User is not active.

UserId in request is not active.

700

LoadLimitValidationFailed

• Load amount should be between XX and XXX
• The transfer would cause the account's maximum allowed balance to be exceeded.
• Exceeds account daily load limit

Per transaction, account balance or daily account reload limit reached

110

InvalidAccountNumber

• AccountNotFound
• Account Not Found.
• AccountStatus is Closed.
• AccountStatus is Pending.
• AccountStatus is Locked.
• Account Status is Restricted
• This account is in a restricted state that does not allow inbound or internal transfers.

Account is not found; account status is not valid, or account is not reloadable for current partner

600

UnableToProcessRequest

Duplicate transaction detected.

Unable to process request due to duplicate transaction and downstream error.

The duplicate reload request is a request with same partner, retail chain, store, user, card number and amount within 3 minutes.

842

TransactionAlreadyVoided

Transaction was already voided

Void request has been received before reload.
Decline reload request and mark transaction as voided.

1000

GeneralFailure

GeneralFailure

Service failure.