Card validation
Before processing a payment or saving a card as the default for recurring charges, it's good practice to validate the card details and confirm that authorizations can be made successfully. A common way to do this is by running a zero-value authorization that checks if the card is valid without initiating an actual charge.
To validate a card (RAW_CARD or CARD_PPRO_VAULTED) include the validate object when creating an agreement, charge or instrument.
Validate a card prior to authorization
Include the validate object in your payment request to perform card validation before attempting an authorization. If the validation fails, the payment will not proceed.
Create a payment agreement with card validation
Request
POST /v1/payment-agreements/
{
"paymentMethod": "CARD",
"description": "subscription",
"startDate": "2023-03-26T20:24:27+00:00",
"frequency": {
"type": "MONTHLY"
},
"instrument": {
"type": "RAW_CARD",
"validate": {
"currency": "BRL"
},
"details": {
"brand": "VISA",
"number": "4111111111111111",
"cvv": "123",
"holderName": "John Smith",
"expiryMonth": 12,
"expiryYear": 2023
}
},
"consumer": {
"name": "John Smith",
"country": "BR"
}
}
Response
{
"id": "agr_VgEBeWxNu2Vyyo6FyWkSP",
"status": "ACTIVE",
"description": "subscription",
"paymentMethod": "CARD",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"startDate": "2023-03-26T20:24:27Z",
"instrumentId": "instr_cFBjegcOCDZRZmW8hGNaM",
"consumer": {
"name": "John Smith",
"country": "BR"
},
"history": [
{
"id": "ahist_A3FIK08zwCA5DWgI71rqi",
"status": "ACTIVE",
"createdAt": "2023-11-24T11:21:42.822Z"
}
],
"createdAt": "2023-11-24T11:21:42.822Z",
"updatedAt": "2023-11-24T11:21:42.822Z"
}
If the consumer is just saving their card details without making a payment / buying a subscription, you can also use the validate object in a standalone instrument creation request.
Create a payment instrument with card validation
Request
POST /v1/payment-instruments/:
{
"type": "RAW_CARD",
"validate": {
"currency":"BRL"
},
"details": {
"brand": "VISA",
"number": "4111111111111111",
"cvv": "123",
"holderName": "John Smith",
"expiryMonth": 1,
"expiryYear": 2024
}
Response
{
"id": "instr_jQzVJK0ZWmx6z2xCTOAf9",
"details": {
"brand": "VISA",
"bin": "411111",
"last4Digits": "1111",
"expiryMonth":1,
"expiryYear": 2024,
"holderName": "John Smith",
"panAlias": "ppro_khNy1rGvb",
"cvvAlias": "ppro_5AsWpq3Wh",
"isCvvPresent": true
},
"type": "CARD_PPRO_VAULTED"
}
Tax identification
Fallback to low value
Updated 1 day ago