Payments Instruments API Guide Overview

The Payment Instruments API is the core mechanism for issuing and managing cards for your end users. After a user is enrolled, this API allows you to issue physical or virtual payment instruments (cards), retrieve their details, control their lifecycle, and support operations like activation, replacement, PIN management, and card pausing.

This section of the Card Management documentation sits alongside related guides such as Inventory Order Management, eWallet Tokens, and Hosted UX. Together, these APIs give partners full control over how cards are issued, managed, and presented to cardholders.

A payment instrument can be:

• Virtual — a digital card issued immediately at enrollment; can be provisioned into eWallets
• Physical (EMV) — a standard physical debit card mailed to the account holder
• Contactless EMV — requires advance configuration; contact your Green Dot Representative to enable

Key Concepts

Payment Instrument Lifecycle

A payment instrument moves through the following statuses over its lifetime:

Physical vs. Virtual Cards

Virtual cards are activated immediately upon issuance. Physical cards must be activated by the account holder after they receive the card in the mail.

Account Limits

Green Dot enforces limits on the number of active and lifetime accounts per SSN and per phone number within a program. The limits are:

• SSN: Up to 1 active account and up to 3 lifetime accounts per program
• Phone: Up to 2 active accounts and up to 10 lifetime accounts per program

Unblock Card Retry Process

When a BaaS account is locked due to suspected fraud, the system attempts to unblock the payment instrument automatically after the account is restored to a healthy state. Here is the full retry flow:

1. A BaaS account is locked due to suspicion of fraud.
2. A request to restore the account and payment instrument to a healthy state is submitted.
3. The account is updated successfully, but the payment instrument remains blocked.
4. The system automatically retries the unblock request up to 3 times. All retries complete within 15 minutes.
5. If retries succeed, the card is unblocked. If all retries fail, kycPendingGate is set to manual with statusReason: underReview, and the payment instrument must be unblocked by the Green Dot Care team.

API Endpoints

Issuance & Retrieval

These endpoints cover the creation of new payment instruments and retrieval of instrument data for a given account or user.

Create a New Payment Instrument

Issues a new payment instrument (physical or virtual) for a user on a given account. This endpoint may be called after enrollment or after an IDV/KYC upgrade. When the upgradeFlag parameter is set to true, it initiates a GPR-to-DDA upgrade, which inserts new product terms, disables old product terms, updates history data, and triggers webhooks.

Note: Do not set productMaterialType when requestPhysicalCardFlag is false — this will cause the request to fail.

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

→ View API Reference

Response Codes

List Payment Instruments for an Account

Returns all payment instruments associated with an account. For joint accounts, this endpoint returns the payment instruments for both account holders. Use this endpoint instead of GET /enrollments/account/{accountIdentifier} when you only need payment instrument data.

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

→ View API Reference

Sample Response

{
  "paymentInstruments": [
    {
      "userIdentifier": "c31a99f5-7370-4a59-90cb-3b0b9b2e1042",
      "paymentIdentifier": "ec726fcf-e09a-49fe-a7c9-e8d403162d0a",
      "paymentInstrumentIdentifier": "dcd8bd7c-4418-44da-8658-dbe59722643d",
      "paymentInstrumentType": "virtual",
      "status": "activated",
      "isPrimaryAccountHolder": true,
      "isPrivateDataViewable": false,
      "isPinSet": false,
      "last4Pan": "3645",
      "activatedDateTime": "2025-02-04T12:45:18Z",
      "issuedDateTime": "2025-02-04T12:45:18.660Z"
    },
    {
      "userIdentifier": "c31a99f5-7370-4a59-90cb-3b0b9b2e1042",
      "paymentIdentifier": "ec726fcf-e09a-49fe-a7c9-e8d403162d0a",
      "paymentInstrumentIdentifier": "13fb49c6-0838-4e87-ba55-47ecce4cf8af",
      "paymentInstrumentType": "emv",
      "status": "notActivated",
      "isPrimaryAccountHolder": true,
      "isPrivateDataViewable": false,
      "isPinSet": false,
      "last4Pan": "3645",
      "issuedDateTime": "2025-02-04T13:12:25.007Z"
    },
    {
      "userIdentifier": "4ece5cc8-bae5-4411-aa35-5912a802fd93",
      "paymentIdentifier": "e380129a-d352-439b-8748-b30506b830e7",
      "paymentInstrumentIdentifier": "d6022a92-ba88-4ed9-aed4-a6b72be77387",
      "paymentInstrumentType": "virtual",
      "status": "activated",
      "isPrimaryAccountHolder": false,
      "isPrivateDataViewable": false,
      "isPinSet": false,
      "last4Pan": "2817",
      "activatedDateTime": "2025-02-04T12:46:28Z",
      "issuedDateTime": "2025-02-04T12:46:28.263Z"
    },
    {
      "userIdentifier": "4ece5cc8-bae5-4411-aa35-5912a802fd93",
      "paymentIdentifier": "e380129a-d352-439b-8748-b30506b830e7",
      "paymentInstrumentIdentifier": "a72fea42-8757-4b19-b6da-5b14edb48098",
      "paymentInstrumentType": "emv",
      "status": "notActivated",
      "isPrimaryAccountHolder": false,
      "isPrivateDataViewable": false,
      "isPinSet": false,
      "last4Pan": "2817",
      "issuedDateTime": "2025-02-04T13:15:27.753Z"
    }
  ],
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "Success",
      "url": "http://tbd"
    }
  ]
}

Get Payment Instrument Details

Retrieves details for a specific payment instrument, including its status, type, last four digits of the PAN, PIN status, issued date, and activated date. If a card is currently paused, the response will include a cardPausedDateTime attribute.

Note: For partners who need to display full PCI data within their application, see the Full PCI Data Access guide, which covers an extended version of this API.

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

→ View API Reference

Get Custom Card Image

Retrieves a custom card image for use during card replacement or issuance. If a custom card is available for a payment instrument, the GET /paymentInstruments/{paymentInstrumentIdentifier} response will include a customCardImageIdentifier field.

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

→ View API Reference

How It Works

1. Call GET .../paymentInstruments/{paymentInstrumentIdentifier}. If a custom card is available, the response will include a customCardImageIdentifier.
2. Pass that identifier to GET .../getCustomCard?customCardImageIdentifier={GUID} to retrieve the custom card details.
3. If found, the response contains the custom card information. If not found, the response returns: Code 4, SubCode 1024, Description: customCardImageIdentifier not found or not supplied.

Note: This endpoint can be called with or without the customCardImageIdentifier parameter.

Complete Registration for an Account Stuck in Incomplete Status

Used to complete an account registration that failed to finish. Retries the creation of a payment instrument for an account in an incomplete state.

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

→ View API Reference

Activation & Verification

These endpoints handle the activation of newly issued cards and the verification of card credentials such as CVV and ATM PIN.

Activate Card

Activates a card for an account holder. There are two activation paths depending on what information is available:

• By PAN, Expiration Date, and CVV — used when the customer has the physical card in hand. The PAN must be exactly 16 digits. POST /programs/{programCode}/accounts/{accountIdentifier}/activateCard

→ View API Reference

• By Payment Instrument Identifier — used when the payment instrument identifier is already known. POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/ActivateCard

→ View API Reference

Things to remember:

• There are no limits on activateCard attempts.
• If multiple notActivated payment instruments exist and a newer one is activated, all older notActivated instruments will be automatically set to deactivated.
• Partners who accept Matricula Identification may use the last four digits of the ID to activate a card and validate the CVV.

Sample Response

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

Response Codes & Activation Statuses

Note: If paymentInstrument.status is notActivated but a more recent payment instrument exists, the response will return Code 4, SubCode 303, description More Recent Card Found, with activationStatus: moreRecentCardFound.

If an initialPhysicalCard replacement request is placed and an existing physical card is already on file in any state, the request will be blocked: Code 4, SubCode 310.

See the Fraud State vs. Features Matrix for details on which operations are permitted in each state.

Verify Card Verification Value (CVV)

Verifies the CVV value for a physical card.

POST /programs/{programCode}/validateCard

→ View API Reference

PIN Management

These endpoints handle setting, resetting, and validating the ATM PIN associated with a payment instrument.

Set or Reset ATM PIN

Updates the ATM PIN for a specific payment instrument. PIN data must be submitted in encrypted form using the fields below.

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

→ View API Reference

Encrypted PIN Request Fields

Verify ATM PIN (IVR Use Case)

Validates a customer's ATM PIN without requiring their physical card. This endpoint is designed for IVR (Interactive Voice Response) integrations.

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

→ View API Reference

How It Works

1. The customer logs in to the IVR using either their PAN or SSN.
2. The IVR searches for the customer's card and prompts the customer to enter their PIN.
3. The IVR prepares a request token containing: accountIdentifier, programCode, paymentInstrumentIdentifier, and the four-digit PIN.
4. The token is passed to the verifyPin endpoint, which calls the Verify PIN API to check if the PIN matches the customer's card.
5. Returns isPinValid: true if validation succeeds, or isPinValid: false if it fails.

Card Lifecycle Management

These endpoints manage the ongoing state of a payment instrument — including replacement, pause/unpause, and eligibility checks. The central endpoint for all lifecycle events is PUT /lifecycleEvent.

Check Card Replacement Eligibility

Before initiating a replacement, call this endpoint to determine whether a customer is eligible to replace their card for a given reason. Returns eligibility per replacement reason and delivery method, and flags whether the account holder's address has changed in the last 30 days.

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

→ View API Reference

Sample Response

{
  "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 Codes

Lifecycle Event (Replace, Pause, Unpause, Upgrade)

The core lifecycle management endpoint. Supports card replacement, pause/unpause, and initial physical card requests for accounts that currently only have a virtual card.

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

→ View API Reference

Things to remember:

• Only the most recent payment instrument (by issuedDate) can be replaced.
• The system blocks initialPhysicalCard requests if any physical card already exists on the account in any state.
• Duplicate lost/stolen requests within 24 hours are blocked.
• neverReceived is not a valid replacement reason for already-activated cards.

Card Replacement

Initiates a replacement for a physical or virtual payment instrument. The upgrade replacement reason may be used within 10 days of a prior replacement.

PAN assignment by replacement reason:

Virtual card replacement behaves slightly differently: the replacement fee is waived, the new virtual PAN is activated in the same call, and the new card retains the same PIN as the previous virtual card — no PIN reset is required.

How Virtual Card Replacement Works

1. A virtual card is reported as lost, stolen, unauthorizedUse (deprecated), or compromised (deprecated).
2. Call PUT .../paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent to request the replacement.
3. A new virtual PAN is created and activated in the same call. The replacement fee is waived, and the new card inherits the previous card's PIN.
4. Call GET .../paymentInstruments/{paymentInstrumentIdentifier} to retrieve the new virtual card information.

Note: If the user's virtual account is in eligibility check, only lost, stolen, unauthorizedUse, and compromised replacement reasons are permitted.

Partners may also request a virtual card to be created simultaneously while a lost or stolen physical card replacement is being processed (CreateVirtualCard: true). Contact your account manager to enable this capability.

Replacement Response Codes

Card Pause and Unpause

Allows the cardholder (via the partner's application) to temporarily block their card by submitting lifecycleEventType: pause or lifecycleEventType: unpause.

How It Works

1. Call PUT .../paymentInstruments/{paymentInstrumentIdentifier}/lifecycleEvent with lifecycleEventType: pause or unpause.
2. If successful, a block is placed on the payment instrument and applied to any other non-closed payment instrument sharing the same card number.
3. To confirm the paused state, call GET .../paymentInstruments — the response will return status: blocked, statusReason: customerInitiatedHold, and a cardPausedDateTime timestamp.

Note: Requesting unpause on a card that is not currently paused will leave the status unchanged.

When a card is paused:

• All network transactions are declined, including eWallet and recurring transactions (e.g., monthly subscriptions).
• Internally initiated transactions (ACH, MRDC, P2P, BillPay, disbursements, purse-to-purse, direct deposits) are not affected.
• Declined transactions will carry declineReason: cardStatus or customerHold. See for more information.

Pause/Unpause Response Codes

In-Store & Instant Issue

These endpoints support partners who operate physical retail locations with on-site card printers. They are used together to complete the in-store personalized card issuance flow - where a customer enrolls or purchases a card at a retail location and receives a printed, personalized, chip- and magstripe-programmed card on the spot.

Partners using this flow must be configured for in-store card issuance. Contact your Green Dot Representative to enable this capability.

How It Works

1. A customer visits a retail location to enroll or purchase a personalized card.

2. The partner's store system calls Get Instant Issue Card Status to retrieve the card data needed to perform embossing and chip/magstripe programming.

3. The store's card printer uses that data to print and program the card.

4. Once the card has been successfully printed and handed to the customer, the store system calls Update Instant Issue Card Status to notify Green Dot that issuance is complete and the card is in the customer's hands.

Get Instant Issue Card Status

Retrieves the card data required to perform in-store embossing and chip/magstripe programming for a personalized card. This endpoint is called by the store system before printing to obtain the information needed to produce the card.

GET /programs/{programCode}/accounts/{accountRefNumber}/instantIssue/paymentInstruments

Update Instant Issue Card Status

Notifies Green Dot that an instant-issue card has been successfully printed and handed to the customer at a retail location. This endpoint should be called by the store system only after embossing and chip/magstripe programming have completed successfully.

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

Related Resources

• Full PCI Data Access — For partners who need to surface full card data within their application
• Fraud State vs Features Matrix — Details on which operations are allowed in each fraud/lock state
• Transaction Decline Reasons — Full list of decline reason codes relevant to paused or blocked cards
• eWallet Tokens — For provisioning virtual cards into Apple Pay, Google Pay, and other wallets
• Webhook Samples — Payment instrument events and webhook samples