Como evitar erros em requisições...
A nossa API valida cada um dos campos enviados na requisição (request) antes de prosseguir com a criação, consulta ou gerenciamento dos pedidos, transações e recursos.
Utilizamos os códigos de resposta convencionais do HTTP para indicar o sucesso ou a falha de uma requisição.
Sendo assim, códigos 2xx indicam sucesso, 4xx indicam erro por algum dado informado incorretamente (por exemplo, algum campo obrigatório não enviado ou um cartão sem data de validade) e 5xx indicando erro nos servidores da MundiPagg.
Tabela dos HTTP Status Code:
| Código | Nome | Descrição |
|---|---|---|
200 | OK | Sucesso |
400 | Bad Request | Algum campo obrigatório não foi enviado ou foi enviado de maneira incorreta |
404 | Not Found | Recurso não encontrado |
500 | Internal Server Error | Erro nos servidores da MundiPagg |
504 | Timeout | Erro de comunicação entre a MundiPagg e a adquirente em questão |
Toda resposta (response) contém os campos Success e ErrorReport.
O campo Success é um booleano que informa se a operação foi executada com sucesso (true) ou não (false).
Já o campo ErrorReport pode conter diferentes tipos de erros. Cada item de erro tem os seguintes campos:
ErrorCode: Código identificador do erro
ErrorField: Campo que originou o erro
Description: Descrição do erro
Sistemas Antifraude
Se a sua loja possui algum sistema antifraude habilitado na MundiPagg, os dados do carrinho de compras e do comprador são validados pela nossa API.
Header da requisição
No header da requisição você deve informar a MerchantKey, o conteúdo do POST e como você quer receber a resposta:
MerchantKey: '00000000-0000-0000-0000-000000000000'
Content-Type: application/json
Accept: application/json
Erros 400
Abaixo colocamos uma lista com os possíveis erros da família 400 que podem ser ocasionados em uma requisição. A sua aplicação deve estar preparada para tratar esses erros, evitando problemas em requisições e perdas no carrinho de compras.
| Campo | Descrição |
|---|---|
| MerchantKey | Chave de loja inválida |
| OrderReference | Pedido duplicado: '123456'. Configuração da loja não permite pedidos duplicados |
| OrderReference | Tamanho máximo permitido para o campo OrderReference é de 56 caracteres |
| Caso não seja informando nenhuma transação de cartão nem de boleto | O Pedido deve conter uma transação de cartão ou boleto |
| CreditCardTransaction.AmountInCents | O valor da transação deve ser maior que zero |
| CreditCardTransaction.TransactionReference | O campo TransactionReference deve ter no máximo 40 caracteres. |
| CreditCardTransaction.CreditCardBrandEnum | Esta loja não possui um meio de pagamento configurado para a bandeira XYZ |
| CreditCardTransaction.PaymentMethodCode | O código de meio de pagamento X não tem suporte para a bandeira Y |
| CreditCardTransaction.InstantBuyKey | A chave de compra não é válida |
| CreditCardTransaction.ExpMonth | O mês de expiração do cartão deve ser maior que 0 e menor que 13 |
| CreditCardTransaction.ExpYear | O ano de expiração do cartão deve conter 2 ou 4 dígitos |
| CreditCardTransaction.ExpYear | Data de vencimento do cartão inválida |
| CreditCardTransaction.CreditCardNumber | O cartão da Havan deve possuir de 18 digitos |
| CreditCardTransaction.CreditCardNumber | O número do cartão deve ter no mínimo 10 dígitos e no máximo 24 digitos |
| CreditCardTransaction.HolderName | O nome do portador deve conter mais de um caracter |
| CreditCardTransaction.InstallmentCount | A quantidade de parcelas da transação deve ser um valor válido |
| CreditCardTransaction.SecurityCode | O campo SecurityCode deve ser preenchido |
| CreditCardTransaction.SecurityCode | O campo código de segurança para a bandeira Visa deve conter 3 dígitos |
| CreditCardTransaction.SecurityCode | O campo código de segurança para a bandeira Mastercard deve conter 3 dígitos |
| CreditCardTransaction.SecurityCode | O campo código de segurança para a bandeira Amex deve conter 4 dígitos |
| CreditCardTransaction.SoftDescriptorText | Tamanho máximo permitido para o campo CreditCardTransaction.SoftDescriptorText é de 35 caractéres. |
| Recurrency.DateToStartBilling | A data de início da cobrança deve ser maior ou igual a data de hoje |
| Recurrency.Interval | O intervalo entre cada recorrência deve ser maior que zero |
| BoletoTransaction.AmountInCents | O valor do boleto deve ser maior que zero |
| BoletoTransaction.NossoNumero | O campo nosso número não pode conter letras |
| BoletoTransaction.Instructions | O campo Instructions deve possuir até 352 caracteres |
| BoletoTransaction.BankNumber | O campo BankNumber deve possuir até 8 caracteres |
| BoletoTransaction.TransactionReference | O campo TransactionReference deve possuir até 40 caracteres |
| Buyer.HomePhone | O número de telefone deve possuir no máximo 32 dígitos |
| Buyer.MobilePhone | O número de telefone deve possuir no máximo 32 dígitos |
| Buyer.WorkPhone | O número de telefone deve possuir no máximo 32 dígitos |
Erros 400 nas tags para o antifraude
Estendemos a lista com os possíveis erros 400 na validação do carrinho caso o seu ecommerce tenha antifraude integrado na Mundi. O mapeamento desses erros é extremamente importante em sua aplicação, pois a ferramenta antifraude deve receber os parâmetros corretamente para analisar as transações.
| Campo | Descrição |
|---|---|
| Buyer | Informe os dados do comprador |
| Buyer.Name | Informe o nome do comprador |
| Buyer.HomePhone/MobilePhone/WorkPhone | Informe os dados de ao menos um telefone de contato |
| Buyer.HomePhone/MobilePhone/WorkPhone | Número de telefone com formato inesperado. Formatos aceitos: (DDD)999999999 ou DDI(DDD)999999999 |
| Buyer.Email | Informe o endereço de e-mail do comprador |
| Buyer.PersonType | Informe o tipo do comprador |
| Buyer.TaxDocumentTypeEnum | Informe o tipo do documento |
| Buyer.TaxDocumentNumber | O campo do documento do cliente deve ter 11 dígitos para CPF ou 14 dígitos para CNPJ |
| Buyer.BuyerKey | A chave de comprador não é válida |
| Buyer.BuyerAddressCollection | Informe os dados de ao menos um endereço de cobrança |
| BuyerAddressCollection.Street | Informe o nome da rua |
| BuyerAddressCollection.Street | Tamanho máximo permitido para o campo Street é de 256 caractéres. |
| BuyerAddressCollection.Number | Informe o número do endereço |
| BuyerAddressCollection.Number | Tamanho máximo permitido para o campo Number é de 56 caractéres |
| BuyerAddressCollection.Complement | Tamanho máximo permitido para o campo Complement é de 256 caractéres |
| BuyerAddressCollection.District | Informe o nome do bairro |
| BuyerAddressCollection.District | Tamanho máximo permitido para o campo District é de 256 caractéres |
| BuyerAddressCollection.City | Informe o nome da cidade |
| BuyerAddressCollection.City | Tamanho máximo permitido para o campo City é de 256 caractéres |
| BuyerAddressCollection.State | Informe a UF do estado corretamente |
| BuyerAddressCollection.ZipCode | O campo código postal deve conter 8 dígitos |
| ShoppingCartCollection | Informe os dados do carrinho de compras |
| ShoppingCart.ShoppingCartItemCollection | Informe os dados dos produtos existentes no carrinho de compras |
| ShoppingCart.ShoppingCartItem.ItemReference | Informe o identificador do produto |
| ShoppingCart.ShoppingCartItem.ItemReference | O tamanho máximo permitido para o campo ItemReference é de 120 caractéres |
| ShoppingCart.ShoppingCartItem.Name | Informe o nome do produto |
| ShoppingCart.ShoppingCartItem.Name | O tamanho máximo permitido para o campo Name é de 256 caractéres |
| ShoppingCart.ShoppingCartItem.Quantity | Informe a quantidade do produto |
| ShoppingCart.ShoppingCartItem.UnitCostInCents | Informe o valor unitário do produto |