-
API
- Visão geral
- Pré-requisitos técnicos
- Autenticação
- GET Listar cartões
- GET Listar campos obrigatórios
- GET Listar operadores
- POST Criar transação
- POST Criar transação criptografada
- POST Criar transação pix
- GET Cancelar transação
- PUT Cancelar transação parcialmente
- GET Listar transação
- POST Listar transações
- GET Filtrar transações
- GET Validar Cartão (Zero dollar)
- POST Cadastrar Link de Pagamento
- GET Listar Links
- GET Consulta qrcode de um link
- GET Filtrar links
- POST Cadastrar cobrança
- GET Listar cobrança
- GET Listar cobrança
- GET Consulta qrcode cobrança
- GET Filtrar cobranças
- POST Relatório de transações
- POST Relatório de extrato
- GET Filtrar Extrato
- GET Listar planos
- DELETE Remover plano
- DELETE Remover plano cliente
- PUT Editar plano
- PUT Editar plano cliente
- POST Cadastrar plano
- GET Listar adesões
- DELETE Excluir adesões
- PUT Editar adesões
- POST Cadastrar adesões
- POST Cancelar adesões
- POST Gerar Token Público
- Exemplos de checkout transparente
- POST Tokenizar cartão
- GET Listar cartões
- GET Listar campos obrigatórios
- GET Listar operadores
- POST Criar transação
- POST Criar transação pix
- GET Cancelar transação
- PUT Cancelar transação parcialmente
- GET Listar transação
- POST Listar transações
- GET Filtrar transações
- GET Validar Cartão (Zero dollar)
- GET Listar planos
- DELETE Remover plano
- DELETE Remover plano cliente
- PUT Editar plano
- PUT Editar plano cliente
- POST Cadastrar plano
- GET Listar adesões
- DELETE Excluir adesões
- PUT Editar adesões
- POST Cadastrar adesões
- POST Cancelar adesões
- GET Lista webhook
- POST Cadastra/Edita webhook
- Introdução
- Exemplo callback transações
- Cartões para teste
- Códigos API
- Antifraude
- Cupons de desconto
- Contato
Visão geral
O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a API do Pay1, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.
O mecanismo de integração com o Pay1 é simples, de modo que apenas conhecimentos intermediários em linguagem de programação para Web, requisições HTTP/ HTTPS e manipulação de arquivos JSON, são necessários para utilizar a API com sucesso.
Nesse manual você encontrará a referência sobre todas as operações disponíveis na API REST do Pay1.
Estas operações devem ser executadas utilizando sua chave específica (APIKey) nos respectivos endpoints dos ambientes:
| Ambiente | URL Base API | APIKey* |
|---|---|---|
| Homologação (testes) | https://dev.pay1.com.br/api/ | O4/YP1CWt6Cc/u3rekE4LQ== |
| Produção | https://pay1.com.br/api/ | IeimY61HmuGzWHyJZ8bFiw== |
* As chaves de API listadas nesta documentação são apenas para teste. Utilize a chave informada
pelo Suporte Pay1, pois ela é responsável por identificar as operações da sua empresa
no sistema.
Pré-requisitos técnicos
A integração é realizada através de serviços disponibilizados como Web Services. Isso permite que a integração seja multiplaforma, ou seja, pode ser integrada à diversas linguagens de programação.Os métodos HTTP disponíveis na API são: GET e POST.
| GET |
Utilizado para listar recursos já existentes. Por exemplo, consulta de transações.
Utilizado para remover um recurso já existente. Por exemplo, remoção de uma transação não autorizada. |
|---|---|
| POST |
Utilizado para criar novos recursos ou enviar informações que serão processadas. Por exemplo, criação de uma transação.
Utilizado para atualizar um recurso já existente. Por exemplo, cancelamento de uma transação autorizada. |
Para executar uma operação, combine a URL base do ambiente com a URL da operação desejada e envie utilizando o verbo HTTP conforme descrito na operação.
Autenticação
A autenticação é feita através da utilização de uma chave de API. Esta chave deve ser enviada a cada requisição e serve para que o sistema identifique a operações realizadas pela sua empresa.
Há duas maneiras de se autenticar, sendo a mais recomendada, utilizando HTTP Basic Auth. A outra maneira é enviar o API Token em um parâmetro de nome APIKey.
As chaves de API podem ser Homologação (Teste) ou Produção, utilize-as de acordo com os respectivos ambientes.
Autenticação via parâmetro
Enviar a chave através do parâmetro APIKey via query param.
Exemplo:
curl -X GET --header 'Accept: application/json' 'https://dev.pay1.com.br/api/payment/list-transaction?APIKey=O4/YP1CWt6Cc/u3rekE4LQ=='
Autenticação via cabeçalho da requisicão
Enviar a chave atráves do Header Authorization da requisição concatenada com o prefixo Basic .
Exemplo:
curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic O4/YP1CWt6Cc/u3rekE4LQ==' 'https://dev.pay1.com.br/api/payment/list-transaction'
Entre em contato com o Suporte Pay1 caso a chave da sua empresa ainda não tenha sido gerada.
Web Hooks
Introdução
Para não ser necessário ter que consultar a API toda vez que precisar verificar o status de alguma transação, nosso sistema pode enviar notificações no momento em que novos eventos ocorrerem.
Esse envio de notificação é feito para uma URL cadastrada via API ou pela na área administrativa.
No momento do disparo de evento a URL cadastrada deve retornar um status code 200 (sucesso).
Caso isso não aconteça, uma nova tentativa de notificar aquele evento será feita a cada 1 hora, o nosso sistema continuará fazendo as tentativas por até 24 horas.
Dessa forma garantimos que instabilidades no sistema integrado não afetem a notificação.
Exemplo de callback de transação
Sempre que o status de uma transação é alterado para autorizado, cancelado ou negada nosso sistema realiza uma notificação.Exemplo de notificação transação:
{
"Tipo": "Transacao",
"TransacaoID": "71189",
"Nome": "douglas Costa",
"CpfCnpj": "098.512.010-06",
"ContratoNumero": "5646546546546",
"ContratoValor": "15.00",
"ContratoGrupo": "",
"ContratoCota": "",
"TransacaoStatus": "TransactionAutorized",
"Descricao": "Transação autorizada",
"Status": "3",
"DataRegistro": "2022-05-13T11:04:44",
"DataAtualizacao": "2022-05-13T11:52:45"
}
Exemplo de notificação de cobrança:
{
"Tipo": "Cobranca",
"Hash": "MWZHcXQwS1dDNG5mcWp3Tk1SRWVoUT09",
"ContratoNumero": "5646546546546",
"ContratoValor": "15.00",
"Status": "3",
"CobrancaStatus": "Autorizada",
"DataRegistro": "2022-05-13T11:04:44",
"DataAtualizacao": "2022-05-13T11:52:45"
}
Exemplo de notificação de pagamento recorrente:
{
"Tipo": "PagamentoRecorrente",
"Id": "40",
"ContratoNumero": "5646546546546",
"ContratoValor": "15.00",
"Recorrencia": "40",
"Indice": "1",
"Status": "5",
"PagamentoRecorrenteStatus": "Autorizada",
"DataRegistro": "2022-05-13T11:04:44",
"DataAtualizacao": "2022-05-13T11:52:45"
}
Checkout transparente
O Pay1 ofereçe uma API para o pagamento de forma transparente. Confira mais informações no link abaixo:
Visualizar exemplos de implementaçãoCartões para teste
Os seguintes números de cartão podem ser usados para testar transações regulares de cartão no ambiente de homologação (teste). A tabela indica qual é o resultado esperado para cada cartão de teste, como uma transação bem-sucedida ou um erro específico.| Bandeira | Número | Expiração | CSC | Resposta |
|---|---|---|---|---|
| Mastercard | 2223000148400010 |
Cielo: Transação autorizada Rede: Transação não autorizada |
||
| Mastercard | 5448280000000007 |
Cielo: Transação não autorizada Rede: Transação autorizada |
||
| Mastercard | 5425233430109903 |
Cielo: Transação não autorizada Rede: Transação não autorizada |
||
| Visa | 4007702835532454 |
Cielo: Transação autorizada Rede: Transação não autorizada |
||
| Visa | 4235647728025682 |
Cielo: Transação não autorizada Rede: Transação autorizada |
||
| Visa | 4917484589897107 |
Cielo: Transação não autorizada Rede: Transação não autorizada |
Códigos da API
Bandeiras suportadas
| Código | Bandeira |
|---|---|
| 1 | Visa |
| 2 | Mastercard |
| 3 | Diners |
| 4 | Discover |
| 5 | Elo |
| 6 | Amex |
| 7 | Jcb |
| 8 | Aura |
| 9 | Cabal |
| 10 | Banescard |
| 11 | Hipercard |
Status transação
| Código | Status | Descrição |
|---|---|---|
| 0 | TransactionVOID | Transação Vazia |
| 1 | TransactionCreated | Transação Criada |
| 2 | TransactionInProcess | Transação Em Processamento |
| 3 | TransactionAutorized | Transação Autorizada |
| 4 | TransactionNotAuthorized | Transação Negada |
| 5 | TransactionCanceled | Transação Cancelada |
| 6 | TransactionErrorTimeout | Transação Com Erro de TimeOut |
| 7 | TransactionError | Transação Com Erro |
| 8 | TransactionInCancel | Transação Em Cancelamento |
| 9 | TransactionInAnalysis | Transação Em Análise |
Status cobrança
| Codigo | Status | Descrição |
|---|---|---|
| 0 | Aguardando | Aguardando |
| 1 | Negada | Negada |
| 2 | AutorizadaUmCartao | Autorizada - 1 cartão |
| 3 | Autorizada | Autorizada |
| 4 | Erro | Erro |
| 5 | ErroEmail | Erro envio email |
| 6 | CanceladaUmCartao | Cancelada - 1 cartão |
| 7 | Cancelada | Cancelada |
Situação Recorrência
| Codigo | Situação | Descrição |
|---|---|---|
| 0 | Aguardando | Aguardando |
| 1 | Negada | Negada |
| 2 | NegadaUma | Negada 1/3 tentativas |
| 3 | NegadaDuas | Negada 2/3 tentativas |
| 4 | NegadaTres | Negada 3/3 tentativas |
| 5 | Autorizada | Autorizada |
| 6 | Erro | Erro |
| 7 | Expirada | Expirada |
| 8 | Cancelada | Cancelada |
Códigos de retorno transação
| Retornos Pay1 | ||
|---|---|---|
| Codigo | Descrição | |
| 00 | Transação autorizada | |
| 999 | Problemas na Conexão com a Adquirente. | |
| 998 | Erro de Comunicação com a Adquirente. | |
| 997 | Erro de Conexão Fechada inesperadamente. | |
| 996 | Erro de Timeout. | |
| Erro não especificado. | ||
| Retornos padrão ABECS | ||
| Bandeira | Codigo | Descrição |
| Amex | 100 | Transação não autorizada / Suspeita de fraude |
| Amex | 101 | Cartão vencido / data expiração inválida |
| Amex | 106 | Excedidas tentativas de senha | compras / Excedidas tentativas de senha | saque |
| Amex | 109 | Comerciante inválido |
| Amex | 110 | Valor da transação inválida |
| Amex | 115 | Valor da parcela inválida / Erro no cartão |
| Amex | 116 | Saldo/limite insuficiente / Transação não permitida | capacidade do terminal |
| Amex | 117 | Senha inválida |
| Amex | 122 | Número cartão não pertence ao emissor | Número cartão inválido / Violação de segurança |
| Amex | 180 | Senha vencida / erro de criptografia de senha / Cartão inválido (criptograma) |
| Amex | 181 | Erro de formato (mensageria) |
| Amex | 200 | Transação não permitida para o cartão / Cartão perdido / Cartão roubado / Fraude confirmada |
| Amex | 911 | Falha do sistema |
| Amex | 912 | Emissor fora do ar |
| Elo | 4 | Refazer a transação (emissor solicita retentativa) |
| Elo | 04 | Refazer a transação (emissor solicita retentativa) |
| Elo | 5 | Transação não autorizada |
| Elo | 05 | Transação não autorizada |
| Elo | 6 | Consultar credenciador |
| Elo | 06 | Consultar credenciador |
| Elo | 12 | Erro no cartão |
| Elo | 13 | Valor da transação inválida |
| Elo | 14 | Número cartão não pertence ao emissor | Número cartão inválido |
| Elo | 19 | Problema no adquirente |
| Elo | 23 | Valor da parcela inválida |
| Elo | 30 | Erro de formato (mensageria) |
| Elo | 38 | Excedidas tentativas de senha | compras |
| Elo | 41 | Cartão perdido |
| Elo | 43 | Cartão roubado |
| Elo | 51 | Saldo/limite insuficiente |
| Elo | 54 | Cartão vencido / data expiração inválida |
| Elo | 55 | Senha inválida |
| Elo | 56 | Número cartão não pertence ao emissor | Número cartão inválido |
| Elo | 57 | Transação não permitida para o cartão / Transação não permitida | capacidade do terminal / Fraude confirmada / Transação negada por infração de lei |
| Elo | 58 | Comerciante inválido |
| Elo | 59 | Suspeita de fraude |
| Elo | 61 | Valor excesso | saque |
| Elo | 62 | Cartão doméstico - transação internacional |
| Elo | 63 | Violação de segurança |
| Elo | 64 | Valor mínimo da transação inválido |
| Elo | 65 | Quantidade de saques excedido |
| Elo | 74 | Senha vencida / erro de criptografia de senha |
| Elo | 75 | Excedidas tentativas de senha | saque |
| Elo | 76 | Conta destino inválida ou inexistente |
| Elo | 77 | Conta origem inválida ou inexistente |
| Elo | 78 | Cartão novo sem desbloqueio |
| Elo | 82 | Cartão inválido (criptograma) |
| Elo | 91 | Emissor fora do ar |
| Elo | 96 | Falha do sistema |
| Elo | 99 | Diferença - pré autorização |
| Elo | Ab | Função incorreta (débito) |
| Elo | Ac | Função incorreta (crédito) |
| Elo | P5 | Troca de senha / desbloqueio |
| Elo | P6 | Nova senha não aceita |
| Hipercard | 1 | Número cartão não pertence ao emissor | Número cartão inválido |
| Hipercard | 01 | Número cartão não pertence ao emissor | Número cartão inválido |
| Hipercard | 3 | Comerciante inválido |
| Hipercard | 03 | Comerciante inválido |
| Hipercard | 4 | Fraude confirmada |
| Hipercard | 04 | Fraude confirmada |
| Hipercard | 5 | Transação não autorizada |
| Hipercard | 05 | Transação não autorizada |
| Hipercard | 12 | Valor da parcela inválida |
| Hipercard | 13 | Valor da transação inválida |
| Hipercard | 14 | Número cartão não pertence ao emissor | Número cartão inválido / Violação de segurança |
| Hipercard | 15 | Emissor não localizado - bin incorreto (negativa do adquirente) |
| Hipercard | 25 | Não é possível localizar o registro no arquivo |
| Hipercard | 28 | Arquivo não disponível para atualização |
| Hipercard | 30 | Problema no adquirente / Erro de formato (mensageria) |
| Hipercard | 41 | Cartão perdido |
| Hipercard | 43 | Cartão roubado |
| Hipercard | 51 | Saldo/limite insuficiente |
| Hipercard | 54 | Cartão vencido / data expiração inválida |
| Hipercard | 55 | Senha inválida |
| Hipercard | 57 | Transação não permitida para o cartão / Transação negada por infração de lei |
| Hipercard | 58 | Transação não permitida | capacidade do terminal |
| Hipercard | 61 | Valor excesso | saque |
| Hipercard | 62 | Cartão doméstico - transação internacional |
| Hipercard | 63 | Suspeita de fraude |
| Hipercard | 65 | Quantidade de saques excedido |
| Hipercard | 75 | Excedidas tentativas de senha | compras / Excedidas tentativas de senha | saque |
| Hipercard | 86 | Senha inválida |
| Hipercard | 88 | Senha vencida / erro de criptografia de senha / Cartão inválido (criptograma) |
| Hipercard | 91 | Emissor fora do ar |
| Hipercard | 92 | Não localizado pelo roteador |
| Hipercard | 94 | Valor do tracing data duplicado |
| Hipercard | 96 | Falha do sistema |
| Mastercard | 1 | Número cartão não pertence ao emissor | Número cartão inválido |
| Mastercard | 01 | Número cartão não pertence ao emissor | Número cartão inválido |
| Mastercard | 3 | Comerciante inválido |
| Mastercard | 03 | Comerciante inválido |
| Mastercard | 4 | Fraude confirmada |
| Mastercard | 04 | Fraude confirmada |
| Mastercard | 5 | Transação não autorizada |
| Mastercard | 05 | Transação não autorizada |
| Mastercard | 12 | Valor da parcela inválida |
| Mastercard | 13 | Valor da transação inválida |
| Mastercard | 14 | Número cartão não pertence ao emissor | Número cartão inválido / Violação de segurança |
| Mastercard | 15 | Emissor não localizado - bin incorreto (negativa do adquirente) |
| Mastercard | 25 | Não é possível localizar o registro no arquivo |
| Mastercard | 28 | Arquivo não disponível para atualização |
| Mastercard | 30 | Problema no adquirente / Erro de formato (mensageria) |
| Mastercard | 41 | Cartão perdido |
| Mastercard | 43 | Cartão roubado |
| Mastercard | 51 | Saldo/limite insuficiente |
| Mastercard | 54 | Cartão vencido / data expiração inválida |
| Mastercard | 55 | Senha inválida |
| Mastercard | 57 | Transação não permitida para o cartão / Transação negada por infração de lei |
| Mastercard | 58 | Transação não permitida | capacidade do terminal |
| Mastercard | 61 | Valor excesso | saque |
| Mastercard | 62 | Cartão doméstico - transação internacional |
| Mastercard | 63 | Suspeita de fraude |
| Mastercard | 65 | Quantidade de saques excedido |
| Mastercard | 75 | Excedidas tentativas de senha | compras / Excedidas tentativas de senha | saque |
| Mastercard | 86 | Senha inválida |
| Mastercard | 88 | Senha vencida / erro de criptografia de senha / Cartão inválido (criptograma) |
| Mastercard | 91 | Emissor fora do ar |
| Mastercard | 92 | Não localizado pelo roteador |
| Mastercard | 94 | Valor do tracing data duplicado |
| Mastercard | 96 | Falha do sistema |
| Visa | 3 | Comerciante inválido |
| Visa | 03 | Comerciante inválido |
| Visa | 4 | Recolher cartão (não há fraude) |
| Visa | 04 | Recolher cartão (não há fraude) |
| Visa | 5 | Transação não autorizada |
| Visa | 05 | Transação não autorizada |
| Visa | 6 | Número cartão não pertence ao emissor | Número cartão inválido / Violação de segurança / Erro no cartão / Cartão vencido / data expiração inválida / Erro por mudança de chave dinâmica |
| Visa | 06 | Número cartão não pertence ao emissor | Número cartão inválido / Violação de segurança / Erro no cartão / Cartão vencido / data expiração inválida / Erro por mudança de chave dinâmica |
| Visa | 7 | Fraude confirmada |
| Visa | 07 | Fraude confirmada |
| Visa | 12 | Erro de formato (mensageria) |
| Visa | 13 | Valor da transação inválida |
| Visa | 15 | Emissor não localizado - bin incorreto (negativa do adquirente) |
| Visa | 19 | Problema no adquirente |
| Visa | 39 | Função incorreta (crédito) |
| Visa | 41 | Cartão perdido |
| Visa | 43 | Cartão roubado |
| Visa | 51 | Saldo/limite insuficiente |
| Visa | 52 | Função incorreta (débito) |
| Visa | 53 | Função incorreta (débito) |
| Visa | 55 | Senha inválida |
| Visa | 57 | Transação não permitida para o cartão |
| Visa | 58 | Transação não permitida | capacidade do terminal |
| Visa | 59 | Suspeita de fraude |
| Visa | 61 | Valor excesso | saque |
| Visa | 62 | Cartão doméstico - transação internacional |
| Visa | 64 | Não cumprimento pelas leis de ante lavagem de dinheiro |
| Visa | 65 | Quantidade de saques excedido |
| Visa | 74 | Senha vencida / erro de criptografia de senha |
| Visa | 75 | Excedidas tentativas de senha | compras / Excedidas tentativas de senha | saque |
| Visa | 76 | Reversão inválida |
| Visa | 78 | Cartão novo sem desbloqueio |
| Visa | 81 | Senha vencida / erro de criptografia de senha |
| Visa | 82 | Cartão inválido (criptograma) |
| Visa | 86 | Senha inválida |
| Visa | 91 | Emissor fora do ar |
| Visa | 92 | Não localizado pelo roteador |
| Visa | 93 | Transação negada por infração de lei |
| Visa | 94 | Valor do tracing data duplicado |
| Visa | 96 | Falha do sistema |
| Visa | B1 | Surcharge não suportado |
| Visa | B2 | Surcharge não suportado pela rede de débito |
| Visa | N0 | Forçar stip |
| Visa | N3 | Saque não disponível |
| Visa | n4 | Valor excesso | saque |
| Visa | N8 | Diferença - pré autorização |
| Visa | R0 | Suspensão de pagamento recorrente para um serviço |
| Visa | R1 | Suspensão de pagamento recorrente para todos serviço |
| Visa | R2 | Transação não qualificada para visa pin |
| Visa | R3 | Suspensão de todas as ordens de autorização |
Antifraude
Confira o funcionamento do antifraude logo abaixo:
1. Na coleta de dados é adicionado metatags e um javascript no browser do cliente para coleta de alguns dados que serão usados na análise de anti-fraude.
2. São enviados os dados para análise de antifraude. Essa análise, além de retornar uma recomendação (aprovar, reprovar, pendente), também retorna o score do cliente informado no pedido.
3. Retorna os dados da análise recomendando a aprovação.
4. Retorna os dados da análise informando a suspeita de fraude e recomendando a negação.
5. Nesse caso, o pedido retorna “pendente” e é feita uma análise póstuma dos dados. Uma vez finalizada a análise é enviado uma notificação webhook com a resposta da avaliação.
5.1. Retorna os dados da análise recomendando a aprovação.
5.2. Retorna os dados da análise informando a suspeita de fraude e recomendando a negação
Observação: Toda esse processo é transparente para o cliente e sua integração.
Cupons de Desconto
Para utilizar os cupons de desconto, basta utilizar o endpoint Validar Cupom para validar o cupom e então passar o código do cupom na criação da Transação pelo campo "CodigoCupom".
Observação 1: Atualmente os cupons só são cadastrados via aplicação.
Observação 2: Passe o valor da transação inteiro, nossa aplicação fará o cálculo de desconto automaticamente.
Contato
Para mais informações entre em contato com o suporte Pay1.
- Endereço: Rua Lourenço Marques, 315
Vila Olímpia - São Paulo - SP -
Telefone:
+55 (11) 99902-2602
+55 (11) 4040-4531 E-mail: [email protected]