--- title: "Recovers Retail Card (Encrypted)" method: POST path: "/programs/{programCode}/enrollments/retailcard/recover" tags: ["Enrollments"] --- # Recovers Retail Card (Encrypted) `POST /programs/{programCode}/enrollments/retailcard/recover` ## Request - The document declares no server URL. - Auth: API key in header `Authorization` Recovers a retail card for a customer. The request payload is encrypted. ## Path parameters - `programCode` string, required ## Headers - `X-GD-RequestId` string, required ## Request body - RetailCardEnrollmentRecoverRequestEncrypted: Represents a request to recover a retail card enrollment using encrypted user data. Inherits all properties from Gd.Bos.DataTransfer.Request.RetailCardEnrollmentRecoverRequest. - `userData` EncryptedData: Represents a container for encrypted data used in secure data transfer operations. Contains the encrypted payload and associated cryptographic metadata, including encryption version, ephemeral public key, and public key hash. Used to securely transmit sensitive information such as user data, ensuring confidentiality and integrity during transport. - `version` string, nullable: The version of the encryption algorithm used to encrypt the data (e.g., "v1", "v2"). - `ephemeralPublicKey` string, nullable: The ephemeral public key used in the encryption process, typically for key exchange or session establishment. - `publicKeyHash` string, nullable: The hash of the public key used to verify the integrity and authenticity of the encryption key. - `data` string, nullable: The encrypted data payload, typically base64-encoded, containing the sensitive information. - `accountIdentifier` string, required: The unique identifier (UID or GUID) for the account associated with the retail card enrollment recovery. - `fraudData` object, nullable: Optional. Additional fraud-related data as key-value pairs for further analysis or processing. - `requestTempCardOnly` boolean: Indicates whether the recovery request is for a temporary card only. ## Response `200` OK - RetailCardEnrollmentResponse: Represents the response returned after a successful retail card enrollment operation. Contains account identifiers, status, direct deposit information, purses, account holders, and activation details. Inherits standard response metadata from Gd.Bos.DataTransfer.Response.ResponseBase. - `accountIdentifier` string, nullable: The unique identifier (UID or GUID) for the enrolled account. - `accountReferenceNumber` string, nullable: The reference number associated with the account, used for partner or customer reference. - `status` string, nullable: The current status of the account. - `accountStatusChangedDateTime` string, nullable: The date and time when the account status was last changed. - `statusReasons` string[], nullable: A list of reasons describing the current status of the account. - `statusCure` string, nullable: The cure or remediation action associated with the current account status, if applicable. - `directDepositInformation` DirectDepositInformation: Represents the direct deposit information for an account. Contains the account number and routing number required to receive ACH direct deposits. Used to provide customers and partners with the necessary banking details for setting up direct deposit transactions. - `accountNumber` string, nullable: The account number used for receiving direct deposits via ACH. - `routingNumber` string, nullable: The routing number of the financial institution for ACH direct deposits. - `purses` Purse[], nullable: The list of purses (sub-accounts or balance containers) associated with the account. - `purseIdentifier` string, nullable: The unique identifier for the purse. - `purseType` string, nullable: The type of purse (e.g., "Savings", "Spending", "Goal"). - `purseDescription` string, nullable: A human-readable description of the purse. - `availableBalance` number, double: The available balance in the purse, representing funds that can be spent or withdrawn. - `ledgerBalance` number, double: The ledger balance in the purse, representing the total balance including pending transactions. - `availableBalanceAsOfDateTime` string, nullable: The date and time when the available balance was last updated. - `ledgerBalanceAsOfDateTime` string, nullable: The date and time when the ledger balance was last updated. - `isHidden` boolean: Indicates whether the purse is hidden from the user interface. - `status` string, nullable: The current status of the purse. - `goalAmount` number, double, nullable: The goal amount set for the purse, if applicable (e.g., for savings goals). - `goalDate` string, nullable: The target date for achieving the goal amount. - `iconName` string, nullable: The name of the icon associated with the purse for display purposes. - `createDate` string, date-time, nullable: The date and time when the purse was created. - `changeDate` string, date-time, nullable: The date and time when the purse was last changed or updated. - `purseNumber` string, nullable: The purse number, which may be used for display or reference purposes. - `interestRateTierIdentifier` string, nullable: The identifier for the interest rate tier applied to the purse, if applicable. - `interestRateTier` string, nullable: The name or description of the interest rate tier applied to the purse. - `interestYieldStartDate` string, nullable: The start date for interest yield calculation. - `interestYieldEndDate` string, nullable: The end date for interest yield calculation. - `APY` number, double, nullable: The annual percentage yield (APY) for the purse, if applicable. - `purseSubType` string, nullable: The subtype of the purse, providing additional categorization (e.g., "RoundUp", "EmergencyFund"). - `interestRate` number, double, nullable: The interest rate applied to the purse, if applicable. - `isRoundUp` boolean: Indicates whether the purse is configured for round-up savings functionality. - `accountHolders` AccountHolder[], nullable: The list of account holders associated with the account. - `paymentInstruments` PaymentInstrument[], nullable: A list of payment instruments (e.g., cards, payment methods) associated with the account holder. - `encryptedPrivatePaymentInstrumentData` EncryptedData: Represents a container for encrypted data used in secure data transfer operations. Contains the encrypted payload and associated cryptographic metadata, including encryption version, ephemeral public key, and public key hash. Used to securely transmit sensitive information such as user data, ensuring confidentiality and integrity during transport. - `version` string, nullable: The version of the encryption algorithm used to encrypt the data (e.g., "v1", "v2"). - `ephemeralPublicKey` string, nullable: The ephemeral public key used in the encryption process, typically for key exchange or session establishment. - `publicKeyHash` string, nullable: The hash of the public key used to verify the integrity and authenticity of the encryption key. - `data` string, nullable: The encrypted data payload, typically base64-encoded, containing the sensitive information. - `privatePaymentInstrumentData` PrivateCardData: Represents sensitive card data associated with a payment instrument. Contains the primary account number (PAN), card verification value (CVV), and expiration details. Used to securely store and transmit card information for payment processing, typically in encrypted or restricted contexts. - `pan` string, nullable: The primary account number (PAN) of the card, typically a 16-digit number. - `cvv` string, nullable: Card Verification Value (CVV) of the card. - `expiration` Expiration: Container for expiration details - `month` string, nullable: Represents the expiration details for a payment instrument, such as a card. - `year` string, nullable: The year of expiration in four-digit format (e.g., "2027"). - `paymentIdentifier` string, nullable: Unique identifier for the payment (may be used for transaction tracking). - `paymentInstrumentIdentifier` string, nullable: Base class for payment instrument details. - `paymentInstrumentType` string, nullable: The type of payment instrument (e.g., "card", "virtualCard"). - `status` string, nullable: The current status of the payment instrument (e.g., "active", "inactive", "blocked"). - `statusReasons` string[], nullable: The list of reasons for the current status of the payment instrument. - `isPinSet` boolean: Indicates whether the PIN has been set for this payment instrument. - `last4Pan` string, nullable: The last four digits of the payment instrument's PAN (Primary Account Number). - `activatedDateTime` string, nullable: The date and time when the payment instrument was activated, if applicable. - `cardPausedDateTime` string, nullable: The date and time when the payment instrument was paused, if applicable. - `issuedDateTime` string, nullable: The date and time when the payment instrument was issued. - `isOverIssuedDaysLimit` boolean, nullable: Indicates if the instrument is over the allowed days since issuance. - `isPrivateDataViewable` boolean: Indicates if private card data is viewable in the response. - `embossedName` string, nullable: The name embossed on the card, if applicable. - `customCardImageIdentifier` string, nullable: Identifier for a custom card image, if used. - `paymentInstrumentLevel` 'personalized' | 'nonpersonalized', nullable: The level of the payment instrument (e.g., personalized, nonpersonalized). - `productMaterialType` string, nullable: The product material type (e.g., "plastic", "virtual"). - `cardIssueSource` string, nullable: The source of card issuance (e.g., "online", "branch"). - `paymentIdentifierBin` string, nullable: The BIN (Bank Identification Number) associated with the payment instrument. - `user` User: Represents user profile information associated with an account holder. Contains personal details, identity information, account status, and KYC (Know Your Customer) state data. Used to provide a comprehensive view of the user's identity, preferences, and compliance status within the system. - `firstName` string, nullable: The user's first name. - `lastName` string, nullable: The user's last name. - `dobStatus` string, nullable: The status of the user's date of birth verification. - `last4Identity` string, nullable: The last four digits of the user's identity number. - `identityType` string, nullable: The type of identity document or number provided (e.g., "SSN", "Passport", "DriverLicense"). - `userIdentifier` string, nullable: The unique identifier assigned to the user within the system. - `peerTransferAcceptPreference` string, nullable: The user's preference for accepting peer-to-peer transfers (e.g., "AutoAccept", "ManualAccept"). - `status` string, nullable: The current status of the user (e.g., "Active", "Inactive", "Suspended"). - `isPrimaryAccountHolder` boolean: Indicates whether the user is the primary account holder. - `kycStateData` KycStateData: Represents the Know Your Customer (KYC) state data for a user. Contains information about OFAC (Office of Foreign Assets Control) screening status, overall KYC status, and any pending KYC gates. Used to track regulatory compliance and the current state of user verification during onboarding or account management. - `ofacStatus` string, nullable: The OFAC (Office of Foreign Assets Control) screening status for the user. Typical values: "Passed", "Failed", "Pending", or other business-specific status indicators. - `kycStatus` string, nullable: The overall KYC (Know Your Customer) status for the user. Typical values: "Verified", "Pending", "Failed", or other business-specific status indicators. - `kycPendingGate` string, nullable: The name or code of any pending KYC gate or step that must be completed for full verification. Example: "DocumentVerification", "AddressCheck", or null if no gates are pending. - `partnerConsumerId` string, nullable: The partner consumer identifier associated with the user. - `accountHolderIdentifier` string, nullable: The unique identifier for the account holder. - `accountCycleDay` integer, nullable: The account cycle day, typically used for billing or statement cycles. - `paymentInstrumentIdentifier` string, nullable: The identifier for the primary payment instrument associated with the account. - `activationStatus` string, nullable: The activation status of the account. - `responseDetails` ResponseDetail[], nullable: Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation. - `code` integer: The primary status or error code for the response (e.g., 200 for success, 400 for validation error). - `subCode` integer, nullable: An optional subcode providing more granular detail about the response or error. - `description` string, nullable: A human-readable description of the response, error, or status. - `url` string, nullable: A URL linking to documentation or a web page with more information about the response code. ## Other responses - `401`: Unauthorized - `403`: Forbidden - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-11-03** `28aa54bed51e`: 1 info - endpoint added [Operation history](https://skmtc.dev/greendot/apis/baas-apis/changes/programs/:programCode/enrollments/retailcard/recover/post.md) --- [API](https://skmtc.dev/greendot/apis/baas-apis.md) - [All operations](https://skmtc.dev/greendot/apis/baas-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/greendot/apis/baas-apis/revisions/28aa54bed51e?raw)