API Gateway de Pagamentos 4all - 0.

1. Introdução
O Gateway de Pagamentos 4all é um intermediário entre o comerciante e o adquirente, fornecendo um meio seguro de trafegar dados das
transações e permitindo a integração de múltiplos adquirentes com apenas uma API (Application Programming Interface).

1.1. Comunicação com o Gateway

A API do gateway só pode ser acessada com o uso do protocolo TLS 1.2 ou posterior. O certificado fornecido pelo servidor deve ser
inspecionado a cada nova conexão, para confirmar que se trata de um certificado confiável. A URL do servidor contida no certificado deve
corresponder ao endereço correto do gateway 4all (gateway.4all.com).

1.1.1. CHAVE DE AUTENTICAÇÃO

O acesso à API é restrito aos ECs cadastrados, sendo necessário informar, em cada conexão, a chave de autenticação fornecida na interface
de gerenciamento. A duração da chave é indeterminada, somente perdendo a validade caso a conta do EC seja desativada na interface de
gerenciamento.

1.1.2. JSON SOBRE HTTPS

Atualmente, a única forma de comunicação suportada é JSON sobre HTTPS. Os dados devem esta codificados no formato UTF8. Os headers
HTTP devem indicar ‘ContentType’ como ‘application/json’ . O header ‘Accept’ deve ser usado e deve indicar ‘application/json’ .

1.1.3. PARÂMETROS DAS REQUISIÇÕES E REPOSTAS

O tamanho dos parâmetros pode ser fixo ou variável e segue a seguintes regras:

String, URL e Datetime : tamanho medido em caracteres UTF8;

Number : Valores numéricos;
Object : Não possui tamanho.

1.1.4. RESPOSTAS DE SUCESSO

Respostas de sucesso apresentam status HTTP 200 quando possuírem conteúdo, e status HTTP 204 quando não possuírem nenhum
conteúdo.

1.1.5. RESPOSTAS DE ERRO

Exemplo (JSON sobre HTTPS):

1
 {
"code": "30.17",
"message": "Parse error"
}

Respostas que indicam erros podem ser identificadas pelo código de status HTTP 4xx (client error) ou 5xx (server error). O corpo da resposta
de erro sempre contém um código de erro e uma mensagem descrevendo o motivo do erro ter ocorrido.

Campo Descrição Formato Presente

code Código de erro String sim

message Mensagem detalhando o erro ocorrido String sim

1.1.6. POSTBACK

O postback é um mecanismo de comunicação com o EC para informar sobre mudanças ocorridas em um determinado evento. Atualmente o
único tipo de evento que produz um postback são as transações financeiras. Para que seja gerado um fluxo de postback para um determinado
evento, haverá campos especificos para informar a URL de postback, que deverá ter um tamanho máximo de 250 caracteres. Por exemplo,
para as as transações financeiras, temos um campo especifico na chamada createTransaction (item 2.2). Os seguintes dados serão
passados na chamada à URL de postback:

Exemplo (JSON sobre HTTPS):

{
"id": "1234",
"type": 1,
"status": 4
}

Campo Descrição Formato Presente

id Identificador do evento. String sim

type Identificador único fornecido pelo EC. (1 - Transaction) Number sim

status Status atual da transação (conforme Anexo C.1 ). Number sim

Para que seja considerado que a comunicação ocorreu com sucesso, a resposta da requisições deverá conter o código de status 200/204 do
protocolo HTTP. Caso ocorra um timeout na resposta, ou a resposta contenha um status diferente dos citados anteriormente, serão efetuadas
retentativas intervaladas entre si em pelo menos um minuto até um máximo de cinco vezes. Caso ainda não se obtenha sucesso, NÃO serão
feitas tentativas adicionais de comunicação da mudança de status.

O recurso de postback é apenas uma conveniência para facilitar a integração com o gateway, e está sujeito a falhas de comunicação,
indisponibilidade de alguma das partes, etc. Desta forma, não elimina a necessidade de consultas periódicas ao status da transação que se
deseja monitorar.

Outra questão importante é que o postback pode ser forjado, então quando um postback for recebido não se deve assumir que a informação é
confiável : o sistema da 4all deve ser consultado para se confirmar se aquela informação realmente é válida ou não. De certa forma, o
postback deve ser usado como um ‘trigger’ para ações.

1.1.7. ENDEREÇOS DOS SERVIDORES DE TESTES E DE PRODUÇÃO

Os seguintes endpoints devem ser usados para executar as chamadas:

Ambiente URL

Testes gateway.test.4all.com

Produção gateway.api.4all.com

Os serviços sempre devem ser acessados usando TLS, na porta 443. Na prática, os endpoints acima sempre serão precedidos de “ https:// ”.

2
1.2. De�nições
1.2.1. ESTABELECIMENTO COMERCIAL (EC)

O estabelecimento comercial, doravante denominado EC, é o publico alvo deste gateway.

1.2.2. CADEIA DE PAGAMENTO

Para realizar um pagamento, existe toda uma cadeia onde cada um dos elos se comunica com o próximo.

1.2.3. TRANSAÇÃO AUTORIZADA

Para que a transação seja realizada, é necessário primeiramente sua autorização. Nesta etapa a instituição financeira verifica se o portador do
cartão possui crédito suficiente para realizar a transação, e em caso positivo irá autorizála.

Uma chamada da API do gateway para criar uma transação, usualmente, apenas a autoriza. É possível informar nos seus parâmetros que a
transação deve também ser capturada. Se este for o caso, o gateway captura a transação automaticamente (caso ela seja autorizada com
sucesso).

Nem sempre é interessante realizar a captura instantaneamente. O EC pode estar interessado apenas em saber se o cartão de crédito é
valido ou garantir que o seu cliente tenha crédito para pagar pelo serviço que será prestado.

As transações autorizadas que não forem capturadas em até 5 dias serão canceladas.

1.2.4. TRANSAÇÃO CAPTURADA

Após a transação ser autorizada, ela estará disponível para captura, termo utilizado para indicar que o valor será cobrado do portador do
cartão de crédito.

1.2.5. TRANSAÇÃO CANCELADA

Transações capturadas podem ser canceladas, usualmente, até 90 dias após a transação ter sido capturada (o prazo exato depende do
adquirente que processou aquela transação).

Quando a transação é cancelada no mesmo dia em que foi capturada, ela não é realmente cobrada do portador do cartão e nem aparece no
seu extrato. No caso das transações que forem canceladas a partir do dia seguinte à sua captura, será iniciado o processo de estorno, que
devolverá o valor cobrado ao portador do cartão de crédito.

1.2.6. CHARGEBACK

Quando um cliente contesta uma transação junto à operadora do seu cartão de crédito, isto pode resultar num chargeback , situação em que o
valor da transação não será repassado ao EC que fez a transação, mesmo que o produto tenha sido entregue ou o serviço tenha sido
prestado.

O chargeback é algo inerente ao mercado. É inevitável que aconteça em algum momento, então é importante que o EC preveja esta situação
e saiba como proceder quando isto ocorrer.

3
 2. Chamadas da API

2.1. Request Vault Key

Caminho: <endpoint>/requestVaultKey Descrição: Retorna uma chave temporária que deve ser utilizada para chamar a funcionalidade P
repare Card do cofre de cartões 4all (conforme Anexo B ).

Exemplo de requisição:

{
"merchantKey": "0123456789ABCDEF01..."
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC String 44 sempre

Exemplo de resposta:

{
"accessKey": "05AD8CB11AA34..."
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

Chave de acesso temporária ao cofre de cartões, para a chamada da funcionalidade p

accessKey repare card (conforme Anexo B ). String 44 sempre

Observações:

Os dados do cartão devem ser informados usando a chamada prepare card do cofre de cartões 4all (conforme Anexo B ).
accessKey se tornará inválida após 15 minutos.

2.2. Create Transaction

Caminho: <endpoint>/createTransaction

Descrição: Cria uma nova transação com os dados fornecidos. A transação é processada de forma assíncrona, então será necessário
consultar posteriormente a transação para determinar o seu estado final (aprovada ou recusada), usando a chamada get transaction details.

O parâmetro “metaId” será utilizado para recuperar a transação caso ocorra um problema de comunicação com o gateway. Esta exigência tem
como objetivo evitar que o EC crie duas ou mais vezes a mesma transação, consequentemente sobretaxando o seu cliente. O EC é
responsável pela geração do “metaId”, que deve ser único, e na ocorrência da repetição será devolvido um erro imediatamente.

Exemplo de requisição (cardToken):

{
"merchantKey": "0123456789ABCDEF01...",
"amount" : "7500",
"metaId": "AF85GHQ97A",
"paymentMethod": {
"cardToken": "TWFuIGlzIGRpc3Rpbmd<...>",
"softDescriptor": "Dr. Zeus Inc."

4
 },
"autoCapture": false,
"postbackURL": "www.example.com/postback/"
}

Exemplo de requisição (cardNonce):

{
"merchantKey": "0123456789ABCDEF01...",
"amount" : "5000",
"metaId": "AEF010FBC569D",
"paymentMethod": {
"cardNonce": "PAB6z8sikfx7RZ9VyL<...>",
"cardBrandId": 1,
"softDescriptor": "ACME SA"
},
"autoCapture": true,
"postbackURL": "www.example.com/postback/"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 44 sim

amount Valor da transação, em centavos. Number sim

Modalidade de pagamento da transação: 1-Crédito, 2-Débito. Caso não seja

paymentType Number não
informado, a modalidade de pagamento será 1-Crédito.

Tipo de parcelamento da transação: 0-À vista, 1-Parcelado pelo emissor,

2-Parcelado pelo lojista. Quando indica que o pagamento é parcelado, o
installmentType Number não
parâmetro installmentCount se torna obrigatório e deve indicar uma quantidade
de parcelas maior do que 1. Quando ausente, assume o valor padrão '0’ (à vista).

Quantidade de parcelas do pagamento parcelado. Quando ausente, ou quando

installmentCount configurado com o valor 1, a compra é à vista. Obrigatório quando o parâmetro Number não
installmentType estiver presente e for diferente de '0’ (à vista).

Identificador único, atribuído pelo estabelecimento comercial, para poder

metaId pesquisar esta transação em caso de não recebimento da resposta desta String 20 sim
chamada.

Informa o método de pagamento que será usado para processar a transação (ver
paymentMethod Object * sim
abaixo).

customerInfo Dados do comprador (ver tabela “customerInfo” abaixo) Object * não

Quando true , indica que a transação deve ser automaticamente capturada.

autoCapture Quando false ou ausente, a transação será apenas autorizada, e para ser Boolean não
capturada será necessário usar a chamada capture transaction.

postbackURL Endereço a ser chamado quando a situação da transação mudar. URL 250 não

paymentMethod:

Campo Descrição Formato Tam. Obrigatório

Token do cartão que será usado na transação, retornado pela rotina prepareCard do
cardNonce cofre de cartões 4all (conforme Anexo B ). String 44 depende

Identificador da bandeira. Deve ser informado quando o **cardNonce* estiver

cardBrandId Number depende
presente.

cardToken Token permanente de cartão, obtido através da chamada Create Card Token String 44 depende

Indica se a transação é de crédito ou de débito: 1-Crédito, 2-Débito. Quando

paymentMode Number não
ausente, a transação é de Crédito.

5
 Campo Descrição Formato Tam. Obrigatório

softDescriptor Descrição que irá aparecer na fatura do cliente. String 20 não

customerInfo:

Campo Descrição Formato Tam. Obrigatório

fullName Nome completo do comprador. String 100 sim

cpf CPF do comprador. String 11 sim

phoneNumber Telefone do comprador. String 20 sim

emailAddress Email do comprador String 200 sim

zipCode CEP do comprador String 9 não

address Endereço do comprador String 200 não

neighborhood Bairro do comprador String 50 não

city Cidade do comprador String 50 não

state Estado do comprador String 50 não

Exemplo de resposta:

{
"transactionId": "1843246811",
"status": 0
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

transactionId Identificador da transação. String 1-20 sempre

status Estado da transação, conforme Anexo C Tabela C.1 Number sempre

Observações:

Se a forma de pagamento (débito ou crédito) não for compatível com o cartão informado, um erro específico será retornado.

Na requisição, apenas um dos dois campos deve ser informado: ou se usa cardNonce , ou se usa cardToken .

2.3. Capture Transaction

Caminho: <endpoint>/captureTransaction

Descrição: Realiza a captura de uma transação já autorizada. Retorna um erro imediato caso a transação não esteja disponível para captura.
O prazo máximo para capturar uma transação autorizada é de 5 dias. Ocorrendo o término do prazo, a transação será cancelada e o EC
deverá criar uma nova transação.

Para alguns adquirentes, a captura da transação pode ser parcial, ou seja, é possível cobrar do portador do cartão um valor menor do que o
informado na criação da transação. Vale notar que o valor da captura parcial não pode ser superior ao da transação original.

Exemplo de requisição:

{
"merchantKey": "0123456789ABCDEF01...",

6
 "transactionId": "1843246811"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 44 sim

transactionId Identificador da transação. String 20 depende

metaId Identificador fornecido pelo EC (obrigatório se transactionId não for informado). String 1-20 depende

Valor da transação, em centavos, a ser capturado. Quando ausente, a captura será

amount Number não
igual ao valor total autorizado. Suportado pelos adquirentes: Stone.

Exemplo de resposta:

{
"transactionId": "1843246811",
"status": 3
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

transactionId Identificador da transação String 20 sempre

status Estado da transação, conforme Anexo C Tabela C.1 Number sempre

2.4. Get Transaction Details

Caminho: <endpoint>/getTransactionDetails

Descrição: Consulta uma transação. Esta chamada permite a utilização do “metaId” informado na criação da transação, como forma de
recuperá-la no caso de falha de comunicação.

Exemplo de requisição:

{
"merchantKey": "0123456789ABCDEF01...",
"transactionId": "1843246811"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 48 sim

transactionId Identificador da transação (obrigatório se metaId não for informado). String 20 depende

metaId Identificador fornecido pelo EC (obrigatório se transactionId não for informado). String 1-20 depende

Exemplo de resposta:

{
"transactionId": "1843246811",
"amount": "5000",

7
 "status": 2,
"createdAt": "2016-01-31T12:37:25Z",
"authorizationInfo": {
"acquirerId": 1,
"acquirerUsn": "11960000570248",
"acquirerTimestamp": "2016-01-16T13:32:58",
"paymentMode": 1,
"lastDigits": "1234",
"expirationDate": "1218",
"brandId": 1
},
"customerInfo": {
"fullName": "John Smith",
"cpf": "68805501425",
"phoneNumber": "51987654321",
"emailAddress": "john@example.com"
}
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

transactionId Identificador da transação. String 20 sempre

authorizedAmount Valor da transação, em centavos. Number sempre

capturedAmount Valor da transação que foi capturado no adquirente, em centavos. Number sempre

status Estado da transação, conforme Anexo C Tabela C.1 . Number sempre

Data e hora UTC em que a transação foi criada no servidor 4all (formato YYYY-
createdAt String 20 sempre
MM-DDThh:mm:ssZ).

customerInfo Dados do comprador (ver abaixo) Object * depende

authorizationInfo Objeto contendo detalhes de autorização da transação (ver abaixo). Object * depende

customerInfo:

Campo Descrição Formato Tam. Presente

fullName Nome completo do comprador. String 100 sempre

cpf CPF do comprador. String 11 sempre

phoneNumber Telefone do comprador. String 20 sempre

emailAddress Email do comprador String 200 sempre

zipCode CEP do comprador String 9 depende

address Endereço do comprador String 200 depende

neighborhood Bairro do comprador String 50 depende

city Cidade do comprador String 50 depende

state Estado do comprador String 50 depende

authorizationInfo:

Campo Descrição Formato Tam. Presente

Identificador do adquirente que processou a transação, conforme Anexo C Tabela

acquirerId Number sempre
C.2

Identificador/NSU do adquirente para a transação. O formato deste campo segue

acquirerUsn String 50 sempre
o formato usado pelo adquirente.

8
 Campo Descrição Formato Tam. Presente

Timestamp de pagamento conforme reportado pelo adquirente. O formato e t

acquirerTimestamp imezone deste campo segue o formato usado pelo adquirente. Presente somente String 50 depende
se o adquirente informar.

paymentMode Indica se a transação é de crédito ou de débito: 1-Crédito, 2-Débito Number sempre

lastDigits Últimos quatro dígitos do número do cartão usado na transação (para exibição). String 4 sempre

expirationDate Data de vencimento do cartão usado na transação (MMYY). String 4 sempre

brandId Bandeira do cartão, conforme Anexo C Tabela C.3 Number sempre

2.5. Cancel Transaction

Caminho: <endpoint>/cancelTransaction

Descrição: Realiza o cancelamento de uma transação aprovada, seja ela capturada ou apenas autorizada. Para transações autorizadas, o
prazo de cancelamento normalmente é de 5 dias após sua criação, e excedendo este período ela será cancelada automaticamente caso não
tenha sido capturada. Para transações capturadas, o prazo máximo para esta solicitação depende do adquirente usado, sendo que se o
cancelamento for realizado no mesmo dia, a transação não aparecerá na fatura do cliente.

Exemplo de requisição:

{
"merchantKey": "0123456789ABCDEF01...",
"transactionId": "1843246811"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC String 44 sim

transactionId Identificador da transação String 20 depende

metaId Identificador fornecido pelo EC (obrigatório se transactionId não for informado). String 1-20 depende

Exemplo de resposta:

{
"transactionId": "1843246811",
"status": 5
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

transactionId Identificador da transação. String 20 sempre

status Estado da transação, conforme Anexo C Tabela C.1 Number sempre

2.6. Create Card Token

Caminho: <endpoint>/createCardToken

9
Descrição: Cria um token de cartão com os dados fornecidos. Este token corresponde aos dados de cartão informados ao cofre e pode ser
usado pelo EC para autorizar novas transações com aquele cartão. Somente o EC que realizou esta chamada pode utilizar o token obtido.

A criação de um token inicia uma transação de validação do cartão uma autorização de R$ 0,10 será executada com aquele cartão e, em
seguida, será cancelada. Este processo ocorre de forma assíncrona e deve ser monitorado, através da chamada checkCardToken , para
verificar se a criação do token foi feita com sucesso (o token só pode ser usado em uma transação após este processo ter sido concluído com
sucesso).

Exemplo de requisição:

{
"merchantKey": "0123456789ABCDEF01...",
"cardNonce": "PAB6z8sikfx7RZ9VyL<...>"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 44 sim

Token do cartão que será usado nesta chamada, retornado pela rotina p repare card
cardNonce do cofre de cartões 4all (conforme Anexo B ) String 44 sim

Quando presente e com valor true , a chamada não retorna enquanto o status do
token do cartão for 0 (em processo de validação). O chamador deve estar preparado
waitForToken Boolean não
para lidar com tempos de resposta longos, de até 30 segundos. Existe um timeout de
30 segundos quando a chamada retorna, independente do estado do token.

Exemplo de resposta:

{
"cardToken": "CAdU9iNBoTuiHVTlu1i+fE<...>",
"status": 1,
"type": 1,
"lastDigits": "1234",
"expirationDate": "1218",
"brandId": 1
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

cardToken Token permanente do cartão. String 44 sempre

status Estado do token de cartão: 0-em processo de validação, 1-válido, 2-inválido Number sempre

Indica se o cartão é de crédito, débito ou ambos. 1-Crédito, 2-Débito, 3-Crédito e

type Number sempre
débito.

lastDigits Últimos quatro dígitos do número do cartão (para exibição). String 4 sempre

expirationDate Data de vencimento (MMYY). String 4 sempre

brandId Bandeira do cartão, conforme Anexo C Tabela C.3 Number sempre

2.7. Check Card Token

Caminho: <endpoint>/checkCardToken

Descrição: Verifica se o processo de validação do cartão tokenizado já está concluído.

10
 Exemplo de requisição:

{
"merchantKey": "hT8zVB3CrueBorrNkziwh<...>",
"cardToken": "CAdU9iNBoTuiHVTlu1i+fE<...>"
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 44 sim

cardToken Token permanente do cartão. String 44 sim

Exemplo de resposta:

{
"status": 1
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

status Estado do token de cartão: 0-em processo de validação, 1-válido, 2-inválido. Number sempre

2.8. List Transactions

Caminho: <endpoint>/listTransactions

Descrição: Retorna uma listagem das transações deste comerciante.

Exemplo de requisição:

{
"sessionToken": "JsFbKkyhM+q05nSKB...",
"itemIndex": 0,
"itemCount": 10,
"filterOptions": {
"after": "2016-01-31T03:00:00Z",
"before": "2016-02-01T02:59:59"
}
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

merchantKey Chave única do EC. String 44 sim

itemIndex Índice do item a partir do qual se deseja iniciar a listagem. Number sim

itemCount Quantidade de transações que devem ser retornadas pelo servidor na listagem. Number sim

filterOptions Opções de filtragem de transações Object * Não

customerInfo Filtros de uma ou mais informações do customer Object * não

filterOptions:

11
 Campo Descrição Formato Tamanho Obrigatório

Ordem em que as transações são retornadas

order 1 - Da mais recente para a mais antiga; Number * Não
2 - Da mais antiga para a mais recente

after Início do período das transações retornadas, no formato YYYY-MM-DDThh:mm:ssZ String 20 Não

before Fim do período das transações retornadas, no formato YYYY-MM-DDThh:mm:ssZ String 20 Não

customerInfo:

Campo Descrição Formato Tam. Obrigatório

fullName Filtra pelo nome do comprador. String 100 não

cpf Filtra pelo CPF do comprador. String 11 não

phoneNumber Filtra pelo elefone do comprador. String 20 não

emailAddress Filtra pelo email do comprador String 200 não

zipCode Filtra pelo CEP do comprador String 9 não

address Filtra pelo endereço do comprador String 200 não

neighborhood Filtra pelo bairro do comprador String 50 não

city Filtra pela cidade do comprador String 50 não

state Filtra pelo estado do comprador String 50 não

Exemplo de resposta:

{
"transactionList": [
{
"transactionId": "854383518",
"amount": 5000,
"capturedAmount": 5000,
"status": 4,
"createdAt": "2016-01-31T20:12:31Z",
"paidAt": "2016-01-31T20:33:12Z",
"authorizationInfo": {
"acquirerId": 1,
"acquirerUsn": "4215813",
"acquirerTimestamp": "1454271151000"
},
"customerInfo": {
"fullName": "John Smith",
"cpf": "68805501425",
"phoneNumber": "51987654321",
"emailAddress": "john@example.com"
}
},
{ ... }
]
}

RESPOSTA:

Campo Descrição Formato Tam. Presente

transactionList Lista de transações. Array de objetos transactionDetails (ver abaixo). Array de objetos * sempre

transactionList:

Campo Descrição Formato Tam. Presente

12
 Campo Descrição Formato Tam. Presente

transactionId Identificador da transação. String 20 sempre

amount Valor da transação autorizada, em centavos. Number sempre

capturedAmount Valor da transação capturada, em centavos. Number sempre

status Estado da transação (conforme Anexo C.1 ). Number sempre

Data e hora UTC em que a transação foi criada no servidor 4all. Formato:YYYY-MM-
createdAt String 20 sempre
DDThh:mm:ssZ

Data e hora UTC em que a transação foi paga por uma conta 4all (formato YYYY-
paidAt String 20 depende
MM-DDThh:mm:ssZ). Presente somente se a transação já foi paga.

authorizationInfo Informação sobre a transação fornecido pelo adquirente Object * depende

customerInfo Informações sobre o comprador Object * sempre

transactionDetails:

Campo Descrição Formato Tam. Presente

acquirerId Identificador do adquirente. Number sempre

acquirerUSN Identificador da transação fornecido pelo adquirente String 32 sempre

Data quando a transação foi processada pelo adquirente. Formato: YYYY-MM-

acquirerTimestamp String 20 sempre
DDTHH:mm:ss[Z]

customerInfo:

Campo Descrição Formato Tam. Presente

fullName Nome completo do comprador. String 100 sempre

cpf CPF do comprador. String 11 sempre

phoneNumber Telefone do comprador. String 20 sempre

emailAddress Email do comprador String 200 sempre

zipCode CEP do comprador String 9 depende

address Endereço do comprador String 200 depende

neighborhood Bairro do comprador String 50 depende

city Cidade do comprador String 50 depende

state Estado do comprador String 50 depende

Observações

Cada um dos filtros do cliente podem ser utilizados com o dado parcial. Por exemplo, pode-se informar apenas parte do nome, parte do
telefone, etc.

Anexo A - Códigos de Erro

Os códigos de erro serão definidos durante o desenvolvimento do gateway.

13
 Anexo B - Cofre de Cartões 4all
O Cofre de Cartões 4all é usado para armazenamento dos dados de cartões de crédito e de débito de maneira segura, em conformidade com
a norma PCIDSS. Neste anexo estão listadas as funcionalidades deste serviço que precisam ser chamada pelo frontend para informar dados
de um cartão de crédito/débito.

Para acessar o ambiente de testes do cofre, o endpoint a ser usado é vault.test.4all.com . Para acessar o ambiente de produção do cofre, o
endpoint a ser usado é vault.api.4all.com .

B.1. Prepare Card

Caminho: <endpoint do cofre>/prepareCard

Descrição: Informa os dados de um cartão para o cofre de cartões.

Exemplo de requisição:

{
"accessKey": "aO1Jn8J/b32DM6/YBG<...>",
"cardData": {
"type": 1,
"cardholderName": "JOHN SMITH",
"cardNumber": "4024007126652816",
"expirationDate": "0119",
"securityCode": "123"
}
}

REQUISIÇÃO:

Campo Descrição Formato Tam. Obrigatório

accessKey Chave temporária de acesso externo, obtida na chamada requestAccessKey. String 44 sim

cardData Dados do cartão. Object * sim

cardData:

Campo Descrição Formato Tam. Obrigatório

type Define se o cartão é de: 1-Cédito, 2-Débito ou 3-Ambos. Number 1 sim

cardholderName Nome do portador (conforme impresso no cartão). String 2-28 sim

cardNumber Número do cartão. String 12-19 sim

expirationDate Data de validade (MMYY). String 4 sim

securityCode Código de segurança do cartão. String 3-4 sim

Exemplo de resposta:

{
"cardNonce": "PAB6z8sOi/B+N4kfVyL<...>"
}

RESPOSTA:

14
 Campo Descrição Formato Tam. Presente

Token que deve ser usado para identificar estes dados de cartão em uma futura chamada
cardNonce String 44 sempre
ao cofre de cartões.

Anotações:

Esta chamada deve ser feita pelo frontend diretamente ao servidor do cofre de cartões. Desta forma, a informação de cartão não
circula em outros ambientes não-PCI.

Se não for usado, o cardNonce expira em 30 minutos neste caso, todos os dados de cartão informados são apagados.

O cardNonce retornado é de uso único.

Nenhuma transação de validação será executada contra os dados informados.

Anexo C - Tabelas de Estados

Tabela C.1 - Estados de uma transação

Estado Descrição

0 Transação em processo de autorização.

1 Transação recusada.

2 Transação autorizada.

3 Transação em processo de captura.

4 Transação capturada (paga).

5 Transação em processo de cancelamento.

6 Transação cancelada.

7 Transação paga cancelamento falhou.

8 Transação contestada pelo portador do cartão (chargeback).

9 Transação paga reapresentada após contestação (chargeback refund).

10 Transação falhou.

11 Transação com falha no processo de cancelamento.

12 Transação capturada mas não confirmada.

Tabela C.2 - Adquirentes

acquirerId Nome do Adquirente

1 Stone

2 Pagar.me

3 GetNet

15
 acquirerId Nome do Adquirente

5 Cielo

6 Rede

Tabela C.3 - Bandeiras de Cartão

brandId Nome da Bandeira

0 Desconhecido

1 Visa

2 Mastercard

16