Validação de Cartões

Uma transação de validação de cartões, também conhecida como zero dollar ou zero dólar, é uma funcionalidade usada para verificar se o cartão de crédito é válido sem gerar cobranças ao portador do cartão.

Para usar essa funcionalidade você precisa informar o número do cartão, do nome impressão no cartão, o CVV e a data de expiração.

Validar um cartão via zero dollar

A funcionalidade de zero dollar funciona no momento de salvar um cartão de crédito.

Abaixo detalhamos o passo a passo:

Passo 1 - Criar um merchant

Crie um merchant com pelo menos 1 provedor com suporte a validação de zero dollar.

info

Esse passo é importante por que o merchant criado será usado no passo 3 (validar e salvar o cartão)

curl --location 'https://sandbox-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"
        }
    }]
}'

Resultado:

{
    "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"
        }
    ]
}

Nesse exemplo acima criamos um merchant usando nosso adapter de sandbox.

caution

É importante dizer que nosso adapter sandbox não faz uma verificação real do cartão. Usamos mocks para emular cenários.

Passo 2 - Tokenização

Agora precisamos tokenizar os dados do cartão para trafegar os dados de forma segura.

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"
}'

Resultado:

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

info

Se você estiver usando um merchant com nosso provedor SANDBOX de testes, você pode variar o CVV para testar um cenário de cartão válido e outro de cartão inválido.

Para testar um cenário válido basta que o CVV termine com 0 (zero), por exemplo, 320.

Para testar um cenário que o cartão não é válido basta que o CVV não termine com 0 (zero), por exemplo, 321

Se tiver dúvidas sobre tokenização de cartão clicando aqui você acessa nossa documentação sobre esse assunto.

Passo 3 - Validar e salvar o cartão

O processo de verificação do cartão ocorre no momento que o cartão será salvo no cofre(vault) de cartões.

Para validar o cartão usando zero dollar precisamos informar 3 propriedades no payload:

• merchantId: Merchant contendo pelo menos 1 provedor com validação de zero dollar.
• tokenId: Token que contém os dados do cartão
• cvvCheck: true ou false para indicar o desejo de verificar ou não o cartão via zero dollar. Importante dizer que se você optar por não verificar o cartão, o mesmo será criado com status pending, permitindo que você tente validar esse cartão via uma transação.

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
}'

Resultado:

{
    "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"
}

Validar o cartão em uma transação de pequeno valor

Caso você não tenha configurado um provedor com suporte a zero dollar você tem a opção de validar um cartão através de uma transação de baixo valor, por exemplo, R$1,00.

Depois de validado você estorna a transação.

Para realizar esse teste você pode seguir os passos 1, 2 e 3 relatados acima. A única mudança a se fazer é no passo 3, basta não informar a propriedade merchantId e cvvCheck ou informe o cvvCheck como 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>",
}'

Usando cvvCheck com valor 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
}'

O resultado da operação se parece com o json abaixo:

{
    "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"
}

Recebendo um cartão com status pending basta iniciar uma transação de baixo valor.

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 deve conter o id de um cartão com status pending

Caso a transação acima receba sucesso (authorized) o cartão será ativado (active), em caso de falha o cartão será dado como inativo (inactive).

Para verificar o status do cartão acesse a api de cards

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"
}

Provedores com suporte a zero dollar

Provedor	Detalhes
SANDBOX	Somente para testes. Use para emular comportamentos de cartão válido / inválido
CIELO	Suporta somente bandeiras Visa, Master e Elo
REDE	https://developer.userede.com.br/e-rede#documentacao-zero-dollar
KLAP	https://api.pasarela.multicaja.cl/docs/apitarjetas#operation/Demorado%20(Modelo%20PSP)