Comunidade de Desenvolvedores maxiPago!

Transação de Zero Dollar

A Transação de Zero Dollar verifica previamente se o cartão utilizado (número, CVV e data de validade) é válido e o diferencial desta funcionalidade é que não ocorre nenhuma cobrança para o portador do cartão, isto é, o cartão é validado sem que o cliente seja sensibilizado, sendo totalmente transparente para o portador do cartão.

Esta transação não permite nenhuma ação posterior (captura, cancelamento, entre outros).

Hoje o serviço de Zero Dollar funciona com as Bandeiras VISA e MASTERCARD.

Os parâmetros aceitos na Transação de Zero Dollar são:

 

Nome Obrigatório Descrição
version Sim Versão da API
merchantId Sim ID de Loja que identifica o Estabelecimento
merchantKey Sim Chave associada ao ID de Loja
referenceNum Sim Identificador do pedido no Estabelecimento – Este campo aceita apenas valores alfanuméricos e deve ser único
processorID Sim Código da Adquirente que irá processar esta transação
Obs: Atualmente a funcionalidade “Zero Dollar” está disponível apenas para a adquirente “Rede” (REST).
number Sim Número do cartão de crédito do cliente
expMonth Sim Mês de vencimento do cartão com 2 dígitos
Exemplo: Janeiro = 01; Novembro = 11
expYear Sim Ano de vencimento do cartão com 4 dígitos
cvvNumber Sim Código de segurança do cartão
chargeTotal Sim Valor da transação

 

    <transaction-request>
        <version>3.1.1.15</version>
        <verification>
            <merchantId>100</merchantId>
            <merchantKey>secret-key</merchantKey>
        </verification>
        <order>
            <zeroDollar>
                <processorID>1</processorID>
                <referenceNum>123456789</referenceNum>
                <transactionDetail>
                    <payType>
                        <creditCard>
                            <number>4111111111111111</number>
                            <expMonth>12</expMonth>
                            <expYear>2020</expYear>
                            <cvvNumber>999</cvvNumber>
                        </creditCard>
                    </payType>
                </transactionDetail>
                <payment>
					<chargeTotal>00.00</chargeTotal>
				</payment>
            </zeroDollar>
        </order>
    </transaction-request>

Zero Dollar com token

 

Uma vez em posse do customerId e do token do cartão, é possível realizar autorizações e vendas diretas sem a necessidade de pedir o número do cartão ao cliente.

A chamada é muito similar à operação de Zero Dollar. Contudo, ao invés de se usar o elemento a <creditCard/> deve-se usar o elemento <onFile/>, que aceita os seguintes parâmetros:

Nome Obrigatório Descrição
customerId Sim ID único do cadastro, retornado quando o cliente foi adicionado à base
token Sim Token único associado ao cartão
cvvNumber Sim CVV (código de segurança) do cartão de crédito

 

Este XML exemplifica uma transação Zero Dollar usando token:

    <transaction-request>
        <version>3.1.1.15</version>
        <verification>
            <merchantId>100</merchantId>
            <merchantKey>secret-key</merchantKey>
        </verification>
        <order>
            <zeroDollar>
                <processorID>1</processorID>
                <referenceNum>123456789</referenceNum>
                <transactionDetail>
                    <payType>
                        <onFile>
                            <customerId>999</customerId>
                            <token>X9Uao5IiMBs</token>
                            <cvvNumber>888</cvvNumber>
                        </onFile>
                    </payType>
                </transactionDetail>
                <payment>
					<chargeTotal>00.00</chargeTotal>
				</payment>
            </zeroDollar>
        </order>
    </transaction-request>

Salvar o cartão automaticamente com Zero Dollar

 

É possível também salvar o número de cartão automaticamente durante uma operação de autorização ou venda direta.

Como um cartão precisa sempre estar associado a um cadastro, é preciso executar o comando add-consumer antes de se poder salvar o cartão. Também é preciso enviar os dados de cobrança (<billing/>), descritos anteriormente neste manual.

Para indicar que deseja salvar o cartão automaticamente é preciso incluir, dentro do nó da operação (<zeroDollar/>), o elemento <saveOnFile/>, que aceita os seguintes parâmetros:

 

Nome Obrigatório Descrição
customerToken Sim ID único do cadastro, retornado quando o cliente foi adicionado à base (customerId)
onFileEndDate Não Data limite para manter o cartão na base Formato MM/DD/AAAA
onFilePermission Não Duração limite do uso do cartão salvo
ongoing = indefinidamente
use_once = apenas uma vez após a 1a. cobrança
onFileComment Não Comentários adicionais sobre este cartão
onFileMaxChargeAmount Não Valor máximo que é permitido cobrar deste cartão
Decimais separados por ponto (“.”). Ex.: 100.00

 

O XML abaixo passa uma transação Zero Dollar e salva o cartão de um cliente:

    <transaction-request>
        <version>3.1.1.15</version>
        <verification>
            <merchantId>100</merchantId>
            <merchantKey>secret-key</merchantKey>
        </verification>
        <order>
            <zeroDollar>
                <processorID>1</processorID>
                <referenceNum>123456789</referenceNum>
                <transactionDetail>
                    <payType>
                        <creditCard>
                            <number>4111111111111111</number>
                            <expMonth>12</expMonth>
                            <expYear>2020</expYear>
                            <cvvNumber>999</cvvNumber>
                        </creditCard>
                    </payType>
                </transactionDetail>
                <payment>
					<chargeTotal>00.00</chargeTotal>
				</payment>
                <saveOnFile>
                        <customerToken>999</customerToken>
                        <onFileEndDate>12/25/2020</onFileEndDate>
                </saveOnFile>
            </zeroDollar>
        </order>
    </transaction-request>