Overview

The Payment Instruments API creates a new physical or virtual payment instrument (card) for a specific user under a specific account. A new user has the option to request a virtual card, physical card, or a contactless EMV card.

Note: Contactless EMV payment instruments require configuration. Please contact your Green Dot Representative for assistance.

Active Consumer Account Limits

Social Security Number (SSN) Limits

• Up to 1 active account with the same SSN per program is allowed
• Up to 3 lifetime accounts with the same SSN per program are allowed

Phone Limits

• Up to 2 active accounts with the same phone number per program are allowed
• Up to 10 lifetime accounts with the same phone number per program are allowed

Response Codes

Unblock Card Retry Process

If a fraud block is removed from an account and the payment instrument remains blocked, the request to unblock the payment instrument will be retried up to 3 times.

Note: All three retries will be completed in 15 minutes.

Retry Process

1. A BaaS account is locked due to suspicion of fraud.
2. A request to update the account and payment instrument to a healthy and normal state is submitted.
3. The account is updated to healthy and normal, but the payment instrument remains blocked.
4. The request to unblock the payment instrument is automatically retried up to 3 times.
5. The retry process is successful and the card is unblocked OR the retry process is unsuccessful and the kycPendingGate is set to manual with the statusReason underReview.
6. If the retry process is unsuccessful, the payment instrument will need to be unblocked by the Green Dot Care team.

Payment Instruments API Endpoints

Create a New Payment Instrument

This endpoint creates a new payment instrument. It may be called after an enrollment or upgrade is cured using the kycGates/IDV endpoint.

Note: If the upgradeFlag parameter is true, it initiates the GPR > DDA upgrade process. This causes the system to:

• Insert new product terms and disable old product terms
• Update the history data
• Send Webhooks

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments

Request Parameters

• userIdentifier - Unique identifier of a user within a program.
• productMaterialType - Optional string value that returns the physical material type of product. Partner must designate the type(s) they would like to offer. Note: Do not set the productMaterialType when requestPhysicalCardFlag is false. If done, the API call will fail trying to set the value for the non-existent physical card.
• requestPhysicalCardFlag - Optional. May be true or false. Defaults to true if not provided. Indicates the client wants a physical or virtual card (payment instrument) issued. To create an account with a virtual payment instrument only, this flag must be set to false.
  Note: Do not set productMaterialType when requestPhysicalCardFlag is false. If done, it will be ignored since it is not applicable to a virtual card.
• fraudData - Used to exchange fraud related information about the user or account.

Sample Response Parameters

Response Codes

Obtain List of Payment Instruments for an Account

If only a list of Payment Instruments is needed, this endpoint should be used in place of GET /enrollments/account/{accountidentifier}.

API Call Structure

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

Obtain Payment Instrument Details

This endpoint gives the partner the ability to retrieve payment instrument details.

There is an additional version of this API for partners who wish to display full PCI data in their application. See Full PCI Data Access V2 for more information.

API Call Structure

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

Response Parameters

Note: If a card is paused, the cardPausedDateTime attribute will be included in the response.

Obtain Private Payment Instrument Data

This endpoint enables the partner to retrieve private payment instrument data for a specific payment instrument.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/extend=privatePaymentInstrumentData

Sample Unencrypted Private Payment Instrument Data

{
   "encryptedPin":{
      "version":"string",
      "ephemeralPublicKey":"string",
      "publicKeyHash":"string",
      "data":"string"
   }
}

Note: Partners who are not configured for encryption will have encrypted data, such as encryptedPrivatePaymentInstrumentData, omitted from the data objects in their responses.

Unencrypted Private Payment Instrument Data Parameters

The following are the out of the box constraints for retrieving and displaying private card information.

Note: EMV & magStripe return the expiration date only.

Private Payment Instrument Data Retrieval - Virtual Card

The following table demonstrates virtual card behavior when calling GET / paymentInstruments/{paymentInstrumentIdentifier}/extend=privatePaymentInstrumentData

*This PIN Set for virtual cards may be waived for certain programs that do not enable provision of the card into eWallets. Contact Green Dot for requirements and additional information about access to this data.

Retrieve Custom Card ID to Request Customer Card

This API is used to retrieve a customer card ID and use it to request a custom card.

API Call Structure

GET /programs/{programCode}/users/{userIdentifier}/getCustomCard?customCardImageIdentifier=GUID

How it Works

• Call GET /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}
• If there is a custom card available, your response will contain the customCardImageIdentifier field containing a unique identification number for the custom card.
• Call GET /programs/{programCode}/userIdentifiers/{userIdentifier}/getCustomCard?customCardImageIde ntifier=GUID
  • Search for the customCard you are looking for, using the customCardImageIdentifier
  • If the customCard is found, you will receive a response containing the customCard information.
  • If the customCard is not found, you will receive the following:
    • Code: 4
    • subcode: 1024
    • Description: customCardImageIdentifier not found or not supplied
  • Note: GET customCard can be called with or without the customCardImageIdentifier.

📘

Partners who are not configured for encryption will have encrypted data, such as encryptedPrivatePaymentInstrumentData, omitted from the data objects in their responses.

Set and Reset an ATM Pin

This endpoint enables the partner to update the ATM pin data for a payment instrument.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}

Sample Request Parameter

Update Instant Issue Card Status

This API provides the card status after an instant issue card is printed.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/instantIssue/paymentInstruments/{paymentInstrumentIdentifier}

Get Card Information for Embossing in the Store

This API is used when a customer goes into a Financial Services Center (FSC) store to buy a new personal card or replace with a new personal card. The vendor needs to get card information for this account and select the printable card to be printed in the store. This API provides the card information for a specific account registered with a specific partner.

Use ATM PIN to Validate a Card

This IVR enhancement enables a customer to use an ATM PIN without requiring a physical card.

How it Works

The customer logs in to IVR by using either a PAN or SSN. Next, IVR:

• Searches for the customer's card.
• Requires the customer to enter a PIN.
• Prepares a requesttoken that contains:
  • accountidentifier
• Four-digit PIN
• programcode
• paymentInstrumentIdentifier

IVR then passes the token to a new endpoint, which calls the Verify Pin API to determine if the PIN matches up with the customer's card.

• If validation is successful, isPinValid = true
• If validation fails, isPinValid = false

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/verifyPin

Retrieve Eligibility for Lost/Stolen Cards

This endpoint provides Partners with the ability to restrict customers from ordering replacement cards when they are lost or stolen.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/replaceCardEligibility

Sample Response Body - Replacement Options

{
    "replacementOptions": [
        {
            "replaceReason": "Lost",
            "isEligible": false
        },
        {
            "replaceReason": "Stolen",
            "isEligible": false
        },
        {
            "replaceReason": "NeverReceived",
            "isEligible": false
        },
        {
            "replaceReason": "Damaged",
            "isEligible": true
        },
        {
            "replaceReason": "UnauthorizedUse",
            "isEligible": false
        },
        {
            "replaceReason": "Compromised",
            "isEligible": false
        },
        {
            "replaceReason": "InitialPhysicalCard",
            "isEligible": false
        }
    ],
    "replacementDeliveryOptions": [
        {
            "deliveryMethod": "Regular",
            "isEligible": true
        }
    ],
    "isAddressChangedIn30Days": true,
    "lastAddressChangeDate": "9/8/2023 1:03:20 AM -07:00",
    "responseDetails": [
        {
            "code": 0,
            "subCode": 0,
            "description": "Success",
            "url": "http://tbd"
        }
    ]
}

Response Parameters

Response Codes

Additional Fields

Replacing a Virtual Payment Instrument (Card)

Replacement virtual payment instruments can be requested. The replacement fee will be waived, and the new virtual PAN will be activated in the same call. Replacements will also have the same pin as the previous virtual card. Users will not need to create a new pin and they will be able to use their new virtual cards immediately.

How it works

• A virtual card is reported:
  • lost
  • stolen
  • unauthorizedUse
  • compromised
• Call PUT …/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent to request a replacement virtual card.
• A new virtual PAN is created and activated. The new virtual card will have the same pin as the previous virtual card.
• The replacement fee is waived.
• Call GET …/accounts/{accountIdentifier}/paymentInstrument/{paymentInstrumentIdentifier} to request the new virtual card information.
• Note: If the user’s virtual account is in eligibility check, only the following replace reasons will be allowed:
  • lost
  • stolen
  • unauthorizedUse
  • compromised

Replace Payment Instrument Edge Cases

PAN

When a card replacement request is processed, the user will receive a new payment instrument with the same PAN as their previous payment instrument or a new PAN. The following table provides guidance on when a user will receive a new PAN and when they will receive the same PAN, when requesting a card replacement

Card Pause and Unpause

The PUT /lifecycleEvent endpoint can also be used to pause and unpause a payment Instrument (card).

How it Works

• Simply call PUT /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent with the lifecycleEventType pause or unpause.
• If the call is successful, a block will be placed on the payment instrument. The block will also apply to any other non-closed payment instrument sharing the same card number.
• Note: Requesting an unpause on a payment instrument that is not currently paused will leave the status unchanged.
• When a card is paused:
  • All network transactions will be declined, including eWallet based transactions and recurring transactions (Ex: Monthly Netflix bill).
  • Internally initiated transactions (ON-US) such as cash reloads, transfers (ACH, MRDC, P2P, BillPay, disbursements and purse to purse), and direct deposits are not affected
  • Attempted transactions will be declined with a declineReason of cardStatus or customerHold. See Transaction Decline Reasons for more information.
• GET …/paymentInstruments will return:
  • status: blocked
  • statusReason: customerInitiatedHold
  • cardPausedDateTime: Indicates if and when the paymentInstrument was paused.

Response Codes

Response Parameters

Response Message

If the POST request is successful, the following response message will be returned along with a 200 HTTP status code.

OK

Note: If paymentInstrument.status is "notActivated" but there is a more recent Payment Instrument, then the following response will be returned:

• code: 4
• subCode: 303
• description: More Recent Card Found
• activationStatus: moreRecentCardFound

If a card replacement request is placed for an “initialPhysicalCard”, the system will check to see if there is an existing physical card for the account (in any state) and if there is one, the request will be blocked. When this occurs:

• http status code: 200
• code: 4
• subCode: 310
• description: An initial physical card cannot be requested on an account that already has a physical card

If an invalid PAN is submitted when calling the activateCard API, the following response (error) message will now be received:

• code: 4
• subCode: 302
• description: Identification Failed

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"operation is successful",
         "url":"http://tbd"
      }
   ],
   "activationStatus":"activated",
   "paymentInstrumentIdentifier":"string"
}

Response Parameters

Possible Response Codes & Activation Statuses

Note: See Fraud State vs. Features Matrix for details.

Verify Card Verification Value (CVV)

This endpoint provides the ability to verify a physical card's CVV value.

API Call Structure

POST /programs/{programCode}/validateCard

Life Cycle Event

This endpoint gives the partner the ability to replace a physical or virtual payment instrument (i.e., card) and allows requests for initial physical cards for accounts that currently have a virtual card only.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent

Things to Remember

• Only the most recent PaymentInstrument (based on issued date) can be replaced.
• The system will check to see if there is an existing physical card for the account (in any state) and if there is an existing physical card, the request will be blocked.
• To prevent duplicate lost/stolen requests, this API will not allow a lost/stolen request within 24 hours of a previous lost/stolen request.
• Note: The replaceReason neverReceived is not allowed for activated payment instruments.

Sample Response Description

Note: See Response Details.

Replacing a Virtual Payment Instrument (Card)

Replacement virtual payment instruments can be requested. The replacement fee will be waived, and the new virtual PAN will be activated in the same call. Replacements will also have the same pin as the previous virtual card. Users will not need to create a new pin and they will be able to use their new virtual cards immediately.

How it Works

• A virtual card is reported as: lost, stolen, unauthorizedUse, or compromised.
• Call PUT …/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent to request a replacement virtual card.
• A new virtual PAN is created and activated. The new virtual card will have the same pin as the previous virtual card.
• The replacement fee is waived.
• Call GET …/accounts/{accountIdentifier}/paymentInstrument/{paymentInstrumentIdentifier} to request the new virtual card information.

Replace Payment Instrument Edge Cases

PAN

When a card replacement request is processed, the user will receive a new payment instrument with the same PAN as their previous payment instrument or a new PAN. The following list provides guidance on when a user will receive a new PAN and when they will receive the same PAN, when requesting a card replacement.

• lost - Receives new PAN.
• stolen - Receives new PAN.
• UnauthorizedUse - Receives new PAN.
• Compromised - Receives new PAN.
• NeverReceived - Receives same PAN.
• Damaged - Receives same PAN.
• InitialPhysicalCard - Receives same PAN (as virtual if the virtual card exists).
• Upgraded - Receives same PAN.
• NameChange - Receives same PAN.

Card Pause and Unpause

The PUT /lifecycleEvent endpoint can also be used to pause and unpause a payment Instrument (card).

How it Works

• Call PUT /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent with the lifecycleEventType pause or unpause.
• If the call is successful, a block will be placed on the payment instrument. The block will also apply to any other non-closed payment instrument sharing the same card number.
  Note: Requesting an unpause on a payment instrument that is not currently paused will leave the status unchanged.
• When a card is paused:
  • All network transactions will be declined, including eWallet based transactions and recurring transactions (Ex: Monthly Netflix bill).
  • Internally initiated transactions (ON-US) such as cash reloads, transfers (ACH, MRDC, P2P, BillPay, disbursements and purse to purse), and direct deposits are not affected.
  • Attempted transactions will be declined with a declineReason of cardStatus or customerHold. See Transaction Decline Reasons for more information.
• GET …/paymentInstruments will return:
  • status: blocked
  • statusReason: customerInitiatedHold
  • cardPausedDateTime: Indicates if and when the paymentInstrument was paused.

Response Codes

Complete Registration for Account Stuck In Incomplete Status

This API is used to complete an account registration.

API Call Structure

POST ​/programs​/{programCode}​/accounts​/{accountIdentifier}​/paymentInstruments

Sample Request Description

• lifecycleEventType - Required field. An action that can be performed against a Payment Instrument (i.e. card). Some actions may only be performed by certain roles and applications (i.e. replacement). A payment instrument (card) can only be replaced if it is the most recent one on file, according to the issued date. Therefore, the user needs to pick the most recent paymentInstrument by issuedDate. Note: See Fraud State vs. Features Matrix for details.
• replaceReason - Required field that provides the reason for the replacement request. It also requires that there be an existing physical payment instrument on the account. The replacement reason can be one of the following:
  • lost
  • stolen
  • neverReceived – Not allowed for activated payment instruments (cards)
  • unauthorizedUse
  • compromised
  • damaged
  • initialPhysicalCard
  • upgrade
  • Note: The upgraded payment instrument may be used within 10 days of a previous replacement. Also, some fields are only applicable based on the replacement reason. For example:
    Lost
  • dateLastUsed
  • dateDiscoveredMissing
  • Stolen
  • dateLastUsed
  • dateDiscoveredMissing
  • policeNotified
  • initialPhysicalCard
  • productMaterialType
  • Upgrade
  • productMaterialType
• waiveFee - Optional. Valid values:
  • True
  • False (default)

productMaterialType - Optional. Providing an explicit value when there is more than one option is strongly suggested.

Note: The productMaterialType can be provided in a lost/stolen replacement request. The replacement paymentInstrument will be ordered with the requested productMaterialType.
notes - Optional. Any additional information that the user would like to provide. (max. 1000 characters)

• deliveryMethod - Optional. Valid values:
  • Regular (default)
  • overnight
• waiveOvernightFee - Optional. Valid values:
  • True
  • False (default)
• CustomCardImageIdentifier - Optional. If there is a custom card available, this field contains the card's unique ID number.
• CreateVirtualCard - Optional. This parameter is used to create a virtual card while a lost or stolen card is being replaced.
  Note: To implement this capability, you must first contact your account manager.
• Valid values:
  • True (requires that replaceReason = lost or stolen)
  • False (default)

Note: Refer to Unblock Card Retry Process at the top of this document for related information.

Activate Card Using PAN, Expiration Date, CVV

The following endpoints enable the partner to activate a card.

API Call Structures

POST /programs/{programCode}/accounts/{accountIdentifier}/activateCard

This endpoint is used if the customer has the PAN, Expiration Date, and CVV.

Note: The PAN must be exactly 16 digits.

POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/ActivateCard

This endpoint uses the customer's Payment Instrument Identifier, which is returned after activation.

Things to Remember

• There are no limits on activateCard attempts.
• If there is more than one “notActivated” Payment Instrument, when a newer Payment Instrument is “activated”, all older “notActivated” Payment Instruments will be set to “deactivated”.
• Partners who accept Matricula Identification will be allowed to use the last four digits of the ID to activate a customer’s payment instrument(s) (cards). This allows the successful activation of their payment instrument and validation of their card verification value (CVV)