> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.americanexpress.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server. # Retrieve a Card GET https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/{cardId} Return the details of a specific Card. If the Card status is IN_PROGRESS, only the cardId, the accountId, and the status fields will be returned. Reference: https://developer.americanexpress.ferndocs.com/payment-services/card-on-demand/api-reference/retrieve-card ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 client credentials. Exchange your API key and secret for a bearer token, then send it as `Authorization: Bearer `. ## Servers - `https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand` (Sandbox, default) - `https://api.americanexpress.com/commercial/v1/card_on_demand` (Production) ## Request ### Path parameters - `cardId` (string, required) — A unique ID that is created for the Card. ## Response ### 200 Successful operation - `cardId` (string, required) — A unique ID that is created for the Card. - `accountId` (string, required) — The ID of the Account being used to fund the Card. - `spendControls` (CardsCardIdGetResponsesContentApplicationJsonSchemaSpendControls, required) — The Spend Control object determines how, when, and where on-demand cards can be authorized. - `cardDetails` (CardsCardIdGetResponsesContentApplicationJsonSchemaCardDetails, required) — The details of the Card being retrieved. - `deliveryMethod` (enum, required) — The method of delivery that is used for the response. - Allowed values: `API_RESPONSE` - `cardUserId` (string, optional) — The ID of the Card User associated with the Card. - `reloadable` (boolean, optional) — Indicates whether the Card can be reloaded with a new Spend Control object after the original Spend Control either expires or is fully utilized. - `reconciliationField` (reconciliationField, optional) — The information collected for reconciliation. ## Errors ### 400 Bad Request Error Bad Request - `errors` (list of 400ErrorItems, required) ### 401 Unauthorized Error Unauthorized - `errorCode` (string, required) — A machine-readable field indicating the type of error. - `errorDescription` (string, optional) — Provides a short description of the error. ### 403 Forbidden Error Unauthenticated - `errorCode` (string, required) — A machine-readable field indicating the type of error. - `errorDescription` (string, optional) — Provides a short description of the error. ### 404 Not Found Error Resource not found - `errorCode` (string, required) — A machine-readable field indicating the type of error. - `errorDescription` (string, optional) — Provides a short description of the error. ### 500 Internal Server Error Service error - `errorCode` (string, required) — A machine-readable field indicating the type of error. - `errorDescription` (string, optional) — Provides a short description of the error. ### 503 Service Unavailable Error Service unavailable - `errorCode` (string, required) — A machine-readable field indicating the type of error. - `errorDescription` (string, optional) — Provides a short description of the error. ## Types ### CardsCardIdGetResponsesContentApplicationJsonSchemaSpendControls The Spend Control object determines how, when, and where on-demand cards can be authorized. - `currentAmount` (string, required) — The amount allocated to the Card. The amount must be a positive number, with a maximum length of eight, and an additional two decimal places if needed. The minimum amount is 0.00. The maximum amount is 99999999.99. This value is determine by the authorizationAmount. - `validFromDate` (string, required) — The beginning date from when the Spend Control is valid. The time zone will be based on the time zone set up on the accountId (or set explicitly during the Card request). The format is: YYYY-MM-DD. This date cannot be in the past. - `validToDate` (string, required) — The end date, after which the Spend Control is no longer valid. The time zone will be based on the time zone set up on the accountId (or set explicitly during the Card request). The format is: YYYY-MM-DD. The validToDate, along with the validFromDate, sets the validity period for the Card, and is different from the Card expiration date. - `spendType` (enum, optional) — Determines whether a Card can be used a single time, or multiple times. - Allowed values: `SINGLE_USE`, `MULTI_USE` - `originalAmount` (string, optional) — The original amount of the Account. The amount must be a positive number, with a maximum length of eight, and an additional two decimal places if needed. The minimum amount is 0.00. The maximum amount is 99999999.99. - `cardCurrency` (string, optional) — The Card currency is derived from the funding account that is used to create the Virtual Card. - `timeZone` (enum, optional) — Please find the International Organization for Standardization (ISO) time zones in the [ISO Timezones Guide](iso-timezones.pdf). The column to reference is 'Time zone abbreviation - STD'. The currently supported timezones are: AEST, PST, EST, MST, GST, AST, GMT, CET. - Allowed values: `AEST`, `PST`, `EST`, `MST`, `GST`, `AST`, `GMT`, `CET` - `allowedMerchantIndustries` (list of string, optional) — The codes specifying the types of Merchants for which the Card can be used, as selected from the list of Merchant's Category Codes (MCC). The maximum number of MCCs that can be used is 25 per Card. - `allowedMerchant` (list of string, optional) — The codes specifying the Merchants for which the Card can be used. The codes representing each Merchant are known as Service Establishments (SEs). - `chargeAmountVariance` (CardsCardIdGetResponsesContentApplicationJsonSchemaSpendControlsChargeAmountVariance, optional) ### CardsCardIdGetResponsesContentApplicationJsonSchemaCardDetails The details of the Card being retrieved. - `cardLastFive` (string, required) — The last five digits of the Card number. - `expiryDate` (string, required) — The expiry date that mimics the expiry date on a physical Card. This is the expiry date a Merchant may require in order to charge a VIRTUAL Card. The format is: MM-YY. - `formFactor` (enum, required) — Indicates the form of the Card provided, whether it is PLASTIC, VIRTUAL or BOTH. Only VIRTUAL is currently supported. PLASTIC is coming soon. - Allowed values: `PLASTIC`, `VIRTUAL`, `BOTH` - `cardReferenceId` (string, required) — A unique ID that can be assigned by the Buyer resource to each of the Cards requested. For instance, some Buyers use invoice numbers or employee codes to help match Cards within their systems. This field only accepts alphanumeric characters and hyphens ( - ). - `cardCreationDate` (string, required) — The date the Card was initially requested. The format is: YYYY-MM-DD. - `status` (enum, required) — The status of the Card. - Allowed values: `IN_PROGRESS`, `ACTIVE`, `PREACTIVE`, `INACTIVE`, `EXPIRED`, `CANCELLED`, `UNSUCCESSFUL` - `cardModifiedDate` (string, optional) — The date when the Card was last modified. The format is: YYYY-MM-DD. - `digitalWalletProvisionable` (boolean, optional) — This field captures the User's preference on whether the Card can be added to a digital wallet. This field is required when the Card User ID is populated in the POST /cards request and you have signed up for the mobile wallet. - `digitalWalletProvisioned` (list of string, optional) — The digital wallet type the Card was added to; currently supports Apple Pay, Google Pay, Samsung Pay, and None. ### reconciliationField The information collected for reconciliation. - `userDefinedFields` (list of ReconciliationFieldUserDefinedFieldsItems, optional) — The reference values which the buyer wants to pass as part of the payment. The buyer can send any reference information about the payment as part of this block. These values can be optionally included in the reconciliation file. The maximum allowed fields are 12. - `accountingFields` (list of ReconciliationFieldAccountingFieldsItems, optional) — The fields that allow the Card requester to pass data that can be used during reconciliation to identify the purpose of the Card. Examples are Project ID, Employee number, or cost center. The Card is tagged with the data entered here for its life cycle. The maximum allowed fields are eight. ### 400ErrorItems - `code` (string, required) — A machine-readable field indicating the type of error. - `message` (string, required) — Provides a short description of the error. - `detail` (string, optional) — Provides a detailed description of the error. - `link` (string, optional) — The link to documentation that explains the error. ### CardsCardIdGetResponsesContentApplicationJsonSchemaSpendControlsChargeAmountVariance - `varianceType` (enum, optional) — The Variance Type can be either a percentage or a dollar amount. This field is applied in conjunction with the varianceLowerBound and varianceUpperBound fields. - Allowed values: `PERCENTAGE`, `AMOUNT` - `varianceLowerBound` (string, optional) — The amount lower than the Card balance that the Card can be charged for below which it will be rejected by American Express. The maximum value of this field is dependent on the varianceType field. If the varianceType is PERCENTAGE, the maximum value is 100. If the varianceType is AMOUNT, then the amount must be zero or greater, with a maximum length of eight, and an additional two decimal places if needed, with a minimum amount of 0.00 and a maximum amount of 99999999.99. - `varianceUpperBound` (string, optional) — The amount greater than the remaining Card balance that the Card can be charged for above which the transactions will not be authorized by American Express. The maximum value of this field is dependent on the varianceType field. If the varianceType is PERCENTAGE, the maximum value is 100. If the varianceType is AMOUNT, then the amount must be zero or greater, with a maximum length of eight, and an additional two decimal places if needed, with a minimum amount of 0.00 and a maximum amount of 99999999.99. - `minimumAuthorizationAmount` (string, optional) — This defines the minimum amount the Card can be charged without affecting the Card amount currently on the Card. Any authorization amount less than or equal to this threshold would be approved, but it is not deducted from the preset Card amount. The amount must be zero or greater, with a maximum length of eight, and an additional two decimal places if needed, with a minimum amount of 0.00 and a maximum amount of 99999999.99. - `autoExpirePercent` (string, optional) — The percentage remaining of the Card's original balance, after which the Card will automatically be closed. When the Card reaches the percentage specified, it will not be able to be used for further transactions. - `autoExpireAmount` (string, optional) — The amount remaining on the Card, after which the Card will automatically be closed. When the Card reaches the specified amount remaining, it will not be able to be used for further transactions. The amount must be zero or greater, with a maximum length of eight, and an additional two decimal places if needed, with a minimum amount of 0.00 and a maximum amount of 99999999.99. ### ReconciliationFieldUserDefinedFieldsItems - `index` (string, required) — Specifies the index of the User-defined Field. - `value` (string, required) — Specifies the value of the User-defined Field. If a value is provided, an index becomes required. ### ReconciliationFieldAccountingFieldsItems - `index` (string, required) — Specifies the index of the User-defined Field. - `value` (string, required) — Specifies the value of the User-defined Field. If a value is provided, an index becomes required. ## Examples **Response** ```json { "cardId": "CAEQd4zBEYrPi56", "accountId": "CR6gVOF5QgCqunZ", "spendControls": { "currentAmount": "200.00", "validFromDate": "2024-01-01", "validToDate": "2024-06-01", "spendType": "SINGLE_USE", "originalAmount": "300.00", "cardCurrency": "USD", "timeZone": "MST", "allowedMerchantIndustries": [ "4121", "4722" ], "allowedMerchant": [ "1042721514", "1043439983" ], "chargeAmountVariance": { "varianceType": "PERCENTAGE", "varianceLowerBound": "100", "varianceUpperBound": "100", "minimumAuthorizationAmount": "300.00", "autoExpirePercent": "20", "autoExpireAmount": "2.00" } }, "cardDetails": { "cardLastFive": "56789", "expiryDate": "02-22", "formFactor": "VIRTUAL", "cardReferenceId": "PO12345-AB7890", "cardCreationDate": "2016-12-13", "status": "ACTIVE", "cardModifiedDate": "2016-12-13", "digitalWalletProvisionable": false, "digitalWalletProvisioned": [ "Apple Pay", "Google Pay" ] }, "deliveryMethod": "API_RESPONSE", "cardUserId": "123456", "reloadable": false, "reconciliationField": { "userDefinedFields": [ { "index": "1", "value": "test" } ], "accountingFields": [ { "index": "1", "value": "test" } ] } } ``` **SDK Code** ```python retrieveCard_example import requests url = "https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript retrieveCard_example const url = 'https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go retrieveCard_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby retrieveCard_example require 'uri' require 'net/http' url = URI("https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java retrieveCard_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56") .header("Authorization", "Bearer ") .asString(); ``` ```php retrieveCard_example request('GET', 'https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp retrieveCard_example using RestSharp; var client = new RestClient("https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift retrieveCard_example import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.qasb2s.americanexpress.com/commercial/v1/card_on_demand/cards/CAEQd4zBEYrPi56")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```