API Reference

Códigos de Erros

Ao fazer requisições para a API de Pagamentos Recorrentes do PagBank, parâmetros incorretos podem gerar erros que impedem o fornecimento de uma resposta com os dados esperados. Nesse caso, erros serão retornados como resposta à sua requisição para ajudá-lo a entender o problema.

Tratamento de erros

Você receberá um HTTP Status 400, 401, 403, 404, 406ou 415 como resposta quando não conseguirmos prosseguir com a operação devido há um parâmetro mal formatado ou valor inesperado. Nesse caso você deve verificar o conteúdo enviado e corrigir o erro para realizar uma nova requisição. No corpo da resposta você encontrará informações sobre o erro enfrentado e sobre o seu tipo, conforme exemplificado no bloco de código abaixo.

{
  "error_messages": [
    {
      "error": "invalid_value",
      "description": "Field has an invalid value. Please check the documentation.",
      "parameter_name": "customer.tax_id"
    }
  ]
}

Lista de erros da API de Pagamento Recorrente

Os códigos de erro apresentados na tabela abaixo podem ocorrer durante a interação com a API de Pagamento Recorrentedo PagBank. Esses códigos são acompanhados por pequenas descrições. Consulte a tabela abaixo para obter mais informações sobre cada código de erro e o respectivo cenário.

CódigoParâmetro associado ao erroDescriçãoCenário
invalid_authorization_headerInvalid credential. Review AUTHORIZATION header.O header Authorization não adere às especificações da documentação.
allowlist_access_requiredAllowlist access required. Contact PagBank.O vendedor não foi homologado pelo PagBank. Contate-nos para mais informações.
access_deniedAccess denied.Acesso negado. Contate-nos para mais informações.
invalid_request_bodyThere are some syntax errors in the request payload. Please check the documentation.Existem erros de sintaxe no corpo da requisição. Os dados estão em um formato inválido.
field_cannot_be_emptyDepende da origem do erro.Field cannot be empty.O campo referenciado pelo parameter_name não pode ser vazio.
invalid_lengthDepende da origem do erro.Field with invalid length. Please check the documentation.O campo referenciado pelo parameter_name está com um tamanho inválido.
invalid_list_element_lengthDepende da origem do erro.List has at least one element with invalid length. Please check the documentation.A lista referenciada pelo parameter_name contém pelo menos um elemento com tamanho inválido.
invalid_enumDepende da origem do erro.Field with invalid value. Please check the documentation.O valor informado no campo referenciado pelo parameter_name não é aceito. O campo é do tipo enum e só aceita determinados valores.
invalid_formatDepende da origem do erro.Field has an invalid format. Please check the documentation.O campo referenciado pelo parameter_name contém um valor que não adere às especificações da documentação.
invalid_valueDepende da origem do erro.Field has an invalid value. Please check the documentation.O campo referenciado pelo parameter_name contém um valor inválido.
invalid_list_element_valueDepende da origem do erro.List has at least one element with invalid value. Please check the documentation.A lista referenciada pelo parameter_name contém pelo menos um elemento que não adere às especificações da documentação.
invalid_shipping_configshippingField shipping has an invalid configuration. Please check the documentation.O campo shipping possui uma configuração que não adere às especificações da documentação.
checkout_not_foundThe requested checkout was not found.O ID de checkout informado no query param é inexistente.
checkout_expiredThe requested checkout has expired.O checkout está expirado.
invalid_discount_valuediscountAmountInformed discount value is invalid. Please check the documentation.O valor informado de desconto é maior que o valor da compra. O valor da compra é dado por: soma do valor dos itens + valor adicional.
invalid_cart_total_valueTotal cart value exceeds the maximum value allowed. Please check the documentation.O valor do carrinho ultrapassa o valor máximo permitido. O valor do carrinho é dado por: soma do valor dos itens + valor do frete + valor adicional - desconto.
invalid_calculate_shipping_configDepende da origem do erro.It is not possible to calculate the shipping cost with the chosen service type. Please check the documentation.O shipping.service_type informado é inválido para frete calculado. O valor deve ser PAC, SEDEX ou nulo.
inconsistent_brand_configurationspaymentMethodsConfigsThere are repeated card brands in the paymentMethodConfigs field.Existe mais de uma configuração para a mesma bandeira de cartão.
invalid_payment_methodpayment_methods_configs[].typeThe payment method is not valid to be configured.O meio de pagamento informado não tem suporte a configurações customizadas.
field_brands_is_not_compatible_with_payment_methodpayment_methods[].typeThe field brands cannot be in request with the given payment method.O meio de pagamento informado não tem bandeiras.
invalid_config_optionpayment_methods_configs[].config_options[]The option field or value field are invalid. Please check the documentation.A configuração de meio de pagamento referenciada pelo parameter_name não adere às especificações da documentação.
repeated_optionspayment_methods_configs[].config_optionsThere are payment method configuration options repeated.A configuração de meio de pagamento referenciada pelo parameter_name está repetida.
inconsistent_checkout_payment_method_configspaymentMethodConfigsThere are inconsistent payment method configurations.Existem configurações de meio de pagamento conflitantes.
invalid_fixed_shipping_configurationshipping.amountField has an invalid configuration for fixed shipping. Please check documentation.O valor do frete deve ser informado caso o shipping.type contenha o valor FIXED.
invalid_unmodifiable_addressshipping.addressAddress must be complete when it's unmodifiable.O endereço deve estar completo caso shipping.address_modifiable contenha o valor false.
card_cannot_be_storedCard cannot be stored.Ocorre quando a bandeira do cartão retorna que o cartão não é válido ou não pode realizar transações.
card_brand_not_supportedCard brand is not supported.Ocorre quando o integrador envia um cartão de uma bandeira não suportada pela API.
payment_method_not_supportedPayment method is not supported.Ocorre quando o integrador envia um cartão de um meio de pagamento não suportado.
number_is_requiredParameter ‘number’ is a required parameter.Ocorre quando o integrador não envia o número do cartão ou envia o campo vazio.
number_is_invalidParameter ‘number’ has an invalid value, see documentation.Ocorre quando o integrador envia a numeração do cartão com um valor inválido.
number_invalid_lengthParameter 'number' should have between 14 and 19 digits.Ocorre quando o integrador envia a numeração do cartão com valor fora do intervalo entre 14 e 19 dígitos.
exp_month_is_requiredParameter ‘exp_year’ is a required parameter.Ocorre quando o integrador não envia o ano de expiração do cartão ou envia o campo vazio.
exp_year_is_invalidParameter ‘exp_year’ has an invalid value, see documentation.Ocorre quando o integrador envia o ano de expiração do cartão com um valor inválido.
security_code_is_requiredParameter 'exp_year' should have 4 digits.Ocorre quando o integrador envia o ano de expiração do cartão com valor diferente de 4 dígitos.
security_code_is_invalidParameter 'security_code' is a required parameter.Ocorre quando o integrador não envia o código de segurança do cartão ou envia o campo vazio.
security_code_invalid_lengthParameter ‘security_code’ has an invalid value, see documentation.Ocorre quando o integrador envia o código de segurança do cartão com um valor inválido.
internal_server_errorParameter 'security_code' should have 3 or 4 digits.Ocorre quando o integrador envia o código de segurança do cartão com valor diferente de 3 ou 4 dígitos.