Card Validation

Validates a card by sending its details directly to Bamboo’s API to confirm authenticity and issuer acceptance. This operation only checks the card validity. It does not create a purchase or authorize a charge.

🚧
PCI Scope Only merchants certified under PCI DSS can access this endpoint directly. Non-PCI merchants must use the Tokenization Form.

Choose your environment

Send a POST request to one of the following URLs:

Environment	URL
Production	`https://secure-api.bamboopayment.com/v3/api/card/validate`
Staging	`https://secure-api.stage.bamboopayment.com/v3/api/card/validate`

🧪
To test this endpoint, use the API Reference or the Postman Collection

Request parameters

The request contains two main objects: CardData and Customer.

CardData Object

Parameter	Type	Mandatory	Description
`CardHolderName`	`string`	Yes	Full name as it appears on the card.
`Pan`	`string`	Yes	Card number without spaces or separators.
`CVV`	`string`	Yes	Security code (3–4 digits).
`Expiration`	`string`	Yes	Expiration date in format MM/YY.
`Email`	`string`	Yes	Cardholder’s email address.
`Document`	`string`	Conditional	Required for some countries.
`TargetCountryISO`	`string`	Yes	Two-letter ISO country code where the card will be processed (ISO-3166-1).

Customer Object

Country-specific requirements: For Argentina and Brazil, all Customer and Address fields are mandatory. These markets require complete customer information for card validation.

Parameter	Type	Required	Description
`FirstName`	`string`	Conditional	Customer’s first name.
`LastName`	`string`	Conditional	Customer’s last name.
`Email`	`string`	Conditional	Customer’s email address.
`DocumentNumber`	`string`	Conditional	Identification number
`DocumentType`	`string`	Conditional	Document type
`Address`	`object`	Conditional	Customer’s address information.

Address Object

Parameter	Type	Required	Description
`Country`	`string`	Conditional	Two-letter ISO country code
`State`	`string`	Conditional	State or province code
`City`	`string`	Conditional	City name.
`PostalCode`	`string`	No	Postal or ZIP code.
`AddressDetail`	`string`	Conditional	Street address with number.

Request example

{
  "CardData": {
    "CardHolderName": "João Silva",
    "Pan": "4507990000004905",
    "CVV": "123",
    "Expiration": "08/30",
    "Email": "[email protected]",
    "Document": "41158995814",
    "TargetCountryISO": "BR"
  },
  "Customer": {
    "FirstName": "João",
    "LastName": "Silva",
    "Email": "[email protected]",
    "DocumentNumber": "41158995814",
    "DocumentType": "CPF.BR",
    "Address": {
      "Country": "BR",
      "City": "São Paulo",
      "State": "SP",
      "PostalCode": "01234-567",
      "AddressDetail": "Rua da Consolação, 1234"
    }
  }
}

Response Parameters

The response includes information about the validation result and details about the payment method.

Parameter	Type	Description
Status	string	Result of the validation. Possible values are `APPROVED`, `REJECTED`.
ErrorCode	string	Error code if the validation was rejected. `null` if approved.
ErrorDescription	string	Detailed description of the error if the validation was rejected. `null` if approved.
PaymentMethod	object	Information about the validated card.

Payment Method Object

Parameter	Type	Description
Brand	string	Card brand (e.g., `MasterCard`, `Visa`).
IssuerBank	string	Name of the bank that issued the card.
Type	string	Type of card (e.g., `CreditCard`, `DebitCard`).

Response example

{
  "Status": "APPROVED",
  "ErrorCode": null,
  "ErrorDescription": null,
  "PaymentMethod": {
    "Brand": "MasterCard",
    "IssuerBank": "SANTANDER BRASIL",
    "Type": "CreditCard"
  }
}

Status Values

The validation can return the following status values:

Status	Description
`APPROVED`	Card successfully validated
`REJECTED`	Card validation failed. Check ErrorCode and ErrorDescription for details

When the status is REJECTED, the ErrorCode and ErrorDescription fields will provide specific information about why the validation failed. For more information about error codes.

💡
In some acquirers, a temporary authorization is made for a small amount (usually less than USD 1) to verify the card’s validity and issuer response. This amount is automatically refunded after validation.

Discover the API

Once you’re familiar with how to validate a card, test your integration in the API Reference:

Country Requirements

Check what each country requires in terms of documents, bank formats, and supported currencies.

Test the API

Explore full request and response examples.

Error Codes

Understand possible error responses and how to resolve them.