Criar Pagamento

POST/v1/payments

Crie uma transação com cartão de crédito. Antes de enviar o pagamento, implemente a biblioteca antifraude.

Exemplo de implementação

A POC mostra como preparar o pagamento no navegador, enviar a requisição pelo Postman e interpretar a resposta.

Exemplo educacional para homologação. Use apenas credenciais e cartões de teste.

Como usar a POC e cuidados de integração

O ZIP contém a pasta POC_PAYMENTS_EXPLAIN, com o código do exemplo, as instruções no README.md e a coleção do Postman em postman.

O fluxo combina o navegador e o Postman:

Autenticação e chave pública: no Postman, você faz a autenticação e obtém a chave pública usada na criptografia.
Preparação do pagamento: no navegador, você inicia o antifraude, criptografa o número do cartão e gera o JSON da requisição.
Envio e interpretação da resposta: você envia o JSON pelo Postman. Depois, informa o status HTTP e cola o corpo da resposta na página da POC para interpretar o resultado.

Use o código em uma IDE, como o Visual Studio Code. Siga as instruções do README.md para configurar e executar o exemplo.

O integrador é responsável por adaptar o exemplo à sua arquitetura e implementar as validações e o tratamento de erros necessários. Também deve cuidar da observabilidade, da proteção de credenciais, da conformidade e das demais boas práticas de desenvolvimento e segurança.

Parâmetros

Requisição

Para vendas parceladas, utilize productType como lojista. Para vendas à vista (parcela única), utilize avista.

O exemplo da segunda aba, “JSON - Armazenar Cartão (vaultId)”, utiliza um cartão já armazenado. Para obter o vaultId, consulte o endpoint e os exemplos de requisição em Armazenar Cartão.

Exemplo de requisição

{
  "payment": {
    "transactionType": "credit",
    "amount": 1035,
    "productType": "avista",
    "installments": 1
  },
  "referenceTransaction": "pedido-001",
  "sellerInfo": {
    "codeAntiFraud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "cardInfo": {
    "cardholderName": "JOSE SILVA",
    "securityCode": "123",
    "brand": "visa",
    "expirationMonth": "01",
    "expirationYear": "30",
    "encryptedCard": "qlfB5XY15tsu3eU1w1ZELRczB3igqf06mHQeBlweQc0udma638XtRgN+jexHmJZy7N+bJeofFbQoULRU4IXzBclAxJRhYPypThF6OGk5C8TJkzKhoSp4OIOleK0weiwUD7C5LVWSMoa6d5sjLlWk2Wv6r66XWnTruiw4EhS8vkE="
  },
  "customer": {
    "documentType": "cpf",
    "documentNumber": "12345678901",
    "firstName": "Jose",
    "lastName": "Silva",
    "email": "[email protected]",
    "phoneNumber": "11999999999",
    "mobilePhoneNumber": "11999999999",
    "address": "Rua Exemplo, 123",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310100",
    "ipAddress": "192.168.1.1",
    "country": "BR"
  }
}

Resposta de sucesso

O exemplo abaixo apresenta o retorno HTTP 200.

Exemplo de resposta

{
  "returnCode": "0",
  "description": "Sucesso",
  "paymentId": "020080286103040952150000006201850000000000",
  "authorizationCode": "043711",
  "orderNumber": "0000000001",
  "expireAt": "2019-09-24T13:20:52.877",
  "amount": 1035,
  "releaseAt": "2019-09-24T13:20:52.877"
}

Campos da resposta

Erros

Para recusas retornadas pelo emissor ou adquirente, consulte também os Códigos de resposta do autorizador. Esses códigos identificam o resultado da transação e não devem ser confundidos com os status HTTP.

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Exemplo documentado

[
  {
    "tag": "",
    "description": "O valor da venda precisa ser maior do que R$ 1,00"
  }
]

Ver validações observadas em homologação

Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.

[
  {
    "tag": "Payment.TransactionType",
    "description": "Tipo de transação não pode estar vazio"
  },
  {
    "tag": "Payment.TransactionType",
    "description": "Tipo de transação deve ser 'credit', 'debit', '1' (Crédito) ou '3' (Débito)"
  },
  {
    "tag": "Payment.Amount",
    "description": "Valor deve ser maior que zero"
  },
  {
    "tag": "Payment.ProductType",
    "description": "Tipo de produto não pode estar vazio"
  },
  {
    "tag": "Payment.ProductType",
    "description": "Tipo de produto deve ser 'avista', 'parcelado_loja', 'parcelado_adm', '1', '2' ou '3'"
  },
  {
    "tag": "Payment.Installments",
    "description": "Parcelas deve ser maior que zero"
  },
  {
    "tag": "SellerInfo.CodeAntiFraud",
    "description": "Código antifraude é requerido"
  },
  {
    "tag": "Customer.DocumentNumber",
    "description": "Número do documento é requerido"
  },
  {
    "tag": "Customer.DocumentNumber",
    "description": "Documento deve ter 11 (CPF) ou 14 (CNPJ) dígitos"
  },
  {
    "tag": "Customer.FirstName",
    "description": "Nome é requerido"
  },
  {
    "tag": "Customer.FirstName",
    "description": "É obrigatório enviar o nome completo"
  },
  {
    "tag": "Customer.Email",
    "description": "E-mail é requerido"
  },
  {
    "tag": "Customer.Email",
    "description": "E-mail deve ter formato válido"
  },
  {
    "tag": "Customer.IpAddress",
    "description": "Endereço IP é requerido"
  },
  {
    "tag": "Customer.IpAddress",
    "description": "Endereço IP deve ter formato válido"
  },
  {
    "tag": "Customer.Address",
    "description": "Endereço é requerido"
  },
  {
    "tag": "Customer.City",
    "description": "Cidade é requerida"
  },
  {
    "tag": "Customer.State",
    "description": "Estado é requerido"
  },
  {
    "tag": "Customer.State",
    "description": "Estado deve ter 2 caracteres (ex: SP)"
  },
  {
    "tag": "Customer.ZipCode",
    "description": "CEP deve ter 8 dígitos"
  },
  {
    "tag": "Customer.Country",
    "description": "País é requerido"
  },
  {
    "tag": "Customer.Country",
    "description": "País deve ter 2 caracteres (ex: BR)"
  },
  {
    "tag": "CardInfo",
    "description": "Token do cartão ou cartão criptografado é requerido quando vaultId não é fornecido"
  },
  {
    "tag": "CardInfo.CardholderName",
    "description": "Nome do portador é requerido quando vaultId não é fornecido"
  },
  {
    "tag": "CardInfo.SecurityCode",
    "description": "Código de segurança é requerido quando vaultId não é fornecido"
  },
  {
    "tag": "CardInfo.SecurityCode",
    "description": "Código de segurança deve ter 3 ou 4 dígitos"
  },
  {
    "tag": "CardInfo.ExpirationMonth",
    "description": "Mês de expiração é requerido quando vaultId não é fornecido"
  },
  {
    "tag": "CardInfo.ExpirationMonth",
    "description": "Mês de expiração deve estar entre 01 e 12"
  },
  {
    "tag": "CardInfo.ExpirationYear",
    "description": "Ano de expiração é requerido quando vaultId não é fornecido"
  },
  {
    "tag": "CardInfo.ExpirationYear",
    "description": "Ano de expiração deve ter 2 dígitos e ser atual ou futuro"
  },
  {
    "tag": "CardInfo",
    "description": "Deve ser fornecido vaultId ou numberToken para processar o pagamento"
  }
]

Campos da resposta de erro

A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.