Card Validation

A card validation transaction, also known as zero dollar transaction, is a feature used to verify if the credit card is valid without charging the cardholder.

To use this feature, you need to provide the card number, cardholder name, CVV, and expiration date.

Validating a card via zero dollar

The zero dollar functionality works when saving a credit card.

Below, we provide a step-by-step guide:

Step 1 - Create a merchant

Create a merchant with at least 1 provider supporting zero dollar validation.

info

This step is important because the merchant created will be used in step 3 (validate and save the card)

curl --location 'https://api.malga.io/v1/merchants' \
--header 'x-api-key: <YOUR_SECRET_KEY>' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "zero dollar validator",
    "mcc": "4040",
    "providers": [{
        "priority": 1,
        "name": "SANDBOX",
        "credentials": {
            "type": "SANDBOX",
            "apiKey": "123"
        }
    }]
}'

Response result:

{
    "id": "3fb1884c-f442-4044-be6f-5afe2e0629b5",
    "name": "zero dollar validator",
    "mcc": "4040",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "status": false,
    "createdAt": "2023-05-30T13:16:06.979Z",
    "updatedAt": "2023-05-30T13:16:06.979Z",
    "providers": [
        {
            "id": "ead031bb-cd67-40e7-a5b2-aa3e5b08f934",
            "name": "SANDBOX",
            "priority": 1,
            "credentials": {
                "type": "SANDBOX",
                "apiKey": "******"
            },
            "options": null,
            "createdAt": "2023-05-30T13:16:06.979Z",
            "updatedAt": "2023-05-30T13:16:06.979Z"
        }
    ]
}

In this example above we created a merchant using our sandbox adapter.

caution

It's important to say that our sandbox adapter doesn't do an actual card check. We use mocks to emulate scenarios.

Step 2 - Tokenization

Now we need to tokenize the card data to securely transfer the data.

curl --location 'https://api.malga.io/v1/tokens' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "cardHolderName": "JOAO DA SILVA",
    "cardNumber": "4929564637987814",
    "cardCvv": "320",
    "cardExpirationDate": "12/2026"
}'

Response result:

{
    "tokenId": "d3202b89-1ccd-4dea-95f2-05b3561bc055"
}

info

If you are using a merchant with our testing provider SANDBOX, you can vary the CVV to test a valid card scenario and an invalid card scenario.

To test a valid scenario, it is enough for the CVV to end with 0 (zero), for example, 320.

To test a scenario that the card is not valid, it is enough that the CVV does not end with 0 (zero), for example, 321

If you have questions about card tokenization by clicking here you will access our documentation on this subject.

Step 3 - Validate and save the card

The card verification process occurs when the card is saved in the card vault.

To validate the card using zero dollar we need to inform 3 properties in the payload:

• merchantId: Merchant containing at least 1 provider with zero dollar validation.
• tokenId: Token containing card data
• cvvCheck: true or false to indicate whether or not to verify the card via zero dollar. Important to say that if you choose not to verify the card, it will be created with pending status, allowing you to try to validate this card via a transaction.

curl --location 'https://api.malga.io/v1/cards' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": "<MERCHANT_ID CRIADO NO PASSO 1>",
    "tokenId": "<TOKEN_ID CRIADO NO PASSO 2>",
    "cvvCheck": true
}'

Response result:

{
    "id": "59085c6d-4d21-4fc0-a6da-dda38b51c2aa",
    "status": "active",
    "statusReason": null,
    "createdAt": "2023-05-30T16:18:11.045Z",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "brand": "Visa",
    "cardHolderName": "JOAO DA SILVA",
    "cvvChecked": true,
    "fingerprint": "p5hgkYxaw5EXgim3GbJ7KzDUhdtxo1O2+qkLFj/Qyoo=",
    "first6digits": "492956",
    "last4digits": "7814",
    "expirationMonth": "12",
    "expirationYear": "2026"
}

Validate the card in a small value transaction

If you haven't configured a provider with zero dollar support, you have the option of validating a card through a low-value transaction, for example, R$1.00.

Once validated, you reverse the transaction.

To perform this test you can follow steps 1, 2 and 3 reported above. The only change to be made is in step 3, just don't inform the property merchantId and cvvCheck or inform the cvvCheck as false.

curl --location 'https://api.malga.io/v1/cards' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "tokenId": "<TOKEN_ID CRIADO NO PASSO 2>",
}'

Using cvvCheck with value false

curl --location 'https://api.malga.io/v1/cards' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": "<MERCHANT_ID CRIADO NO PASSO 1>",
    "tokenId": "<TOKEN_ID CRIADO NO PASSO 2>",
    "cvvCheck": false
}'

The result of the operation looks like the json below:

{
    "id": "03099be2-9412-4d6d-a0e5-f9adee45c6b1",
    "status": "pending",
    "statusReason": "cvv check was sent as false",
    "createdAt": "2023-05-30T16:28:32.506Z",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "brand": "Visa",
    "cardHolderName": "JOAO DA SILVA",
    "cvvChecked": false,
    "fingerprint": "rjf45RCpvnKyTHB3iwsdfct4qjOgY8ppLtOboUUjAAM=",
    "first6digits": "492956",
    "last4digits": "7814",
    "expirationMonth": "10",
    "expirationYear": "2026"
}

Receiving a card with pending status, it is enough to start a low value transaction.

curl --location 'https://api.malga.io/v1/charges' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": "<YOUT_MERCHANT_ID>",
    "amount": 100,
    "currency": "BRL",
    "statementDescriptor": "Validacao do cartao",
    "capture": true,
    "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
    },
    "paymentSource": {
        "sourceType": "card",
        "cardId": "<CARD_ID_TO_BE_VALIDATED>"
    }
}'

caution

CARD_ID_TO_BE_VALIDATED must contain the id of a card with pending status

If the transaction above is successful (authorized), the card will be activated (active), in case of failure, the card will be considered inactive (inactive).

To check the status of the card access the cards api

curl --location 'https://api.malga.io/v1/cards/<CARD_ID>' \
--header 'x-client-id: <YOUR_CLIENT_ID>' \
--header 'x-api-key: <YOUR_API_KEY>'

Resultado:

{
    "id": "d66e25e7-7f83-45f1-8e2b-ab9e2d1e9c8d",
    "status": "active",
    "createdAt": "2023-05-25T23:29:15.382Z",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "customerId": null,
    "brand": "Mastercard",
    "cardHolderName": "JOAO DA SILVA",
    "cvvChecked": true,
    "fingerprint": "A4wxUVbW5AIiNYP+i/ATLZxB7VQKa5WwSlcBo12GdDg=",
    "first6digits": "527971",
    "last4digits": "3624",
    "expirationMonth": "12",
    "expirationYear": "2026"
}

Providers with zero dollar support

Provedor	Details
SANDBOX	For testing purposes only. Use to emulate valid/invalid card behaviors
CIELO	Only supports Visa, Master and Elo brands
REDE	https://developer.userede.com.br/e-rede#documentacao-zero-dollar
KLAP	https://api.pasarela.multicaja.cl/docs/apitarjetas#operation/Demorado%20(Modelo%20PSP)