---
title: "Add or Validate External Bank Card"
method: POST
path: "/programs/{programCode}/externalcards"
tags: ["ExternalCards"]
---

# Add or Validate External Bank Card

`POST /programs/{programCode}/externalcards`

Adds or validates an external bank card for a customer using encrypted card data. This endpoint is intended for external and general use.

## Path parameters

- `programCode` string, required

## Headers

- `X-GD-RequestId` string, required

## Request body

- AddExternalCardEncryptedRequest — Represents a request to add an external card using encrypted card data.
  - `encryptedExternalCardData` 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, nullable — The unique identifier for the account to which the external card will be added.
  - `firstName` string, nullable — The first name of the cardholder.
  - `lastName` string, nullable — The last name of the cardholder.
  - `nickName` string, nullable — The nickname for the external card.
  - `action` string, nullable — The action to perform (e.g., "add", "update", "remove").
  - `address1` string, nullable — The first line of the cardholder's address.
  - `address2` string, nullable — The second line of the cardholder's address (optional).
  - `city` string, nullable — The city of the cardholder's address.
  - `state` string, nullable — The state or province of the cardholder's address.
  - `zip` string, nullable — The ZIP or postal code of the cardholder's address.

## Response `201`

Created

- AddExternalCardResponse — Represents the response returned after adding an external card to a customer profile. Contains details about the card, its network, eligibility for funding and withdrawal, and a unique identifier for the external card. Inherits standard response metadata from Gd.Bos.DataTransfer.Response.ResponseBase.
  - `bankName` string, nullable — The name of the bank that issued the external card.
  - `network` string, nullable — The payment network associated with the card (e.g., Visa, Mastercard).
  - `fundingEligible` boolean, nullable — Indicates whether the card is eligible for funding (can receive deposits).
  - `withdrawalEligible` boolean, nullable — Indicates whether the card is eligible for withdrawal (can be used for cash-out).
  - `accountExternalCardIdentifier` string, uuid, nullable — Unique identifier for the external card account, used for future operations.
  - `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

---

[API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)