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