> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status da transação e códigos de erro

Esta seção detalha os formatos de resposta da API, os códigos de status HTTP e uma referência completa de todos os códigos de status e erro de transação usados pela API Localpayment. Dominar esses padrões e códigos de resposta é essencial para criar integrações robustas, rastrear com precisão os ciclos de vida das transações, lidar com diversos cenários e fornecer feedback claro ao usuário.

As respostas da API Localpayment fornecem indicadores claros dos resultados das solicitações por meio de códigos de status HTTP e objetos de status estruturados. Embora as estruturas de resposta possam variar de acordo com o endpoint, elas sempre incluem informações essenciais para o processamento adequado.

> [card] Códigos de status HTTP
>
> Códigos de status HTTP padrão que indicam sucesso ou falha na solicitação.

> [card] Objetos de status
>
> Informações detalhadas sobre o status dos resultados das transações.

> [card] Tratamento de erros claro
>
> Informações de erro estruturadas para depuração e resolução.

***

## Códigos de status HTTP

A API utiliza códigos de status HTTP padrão para indicar os resultados das solicitações no nível do protocolo. Esses códigos fornecem a primeira indicação de se a sua solicitação foi bem-sucedida.

### Códigos de sucesso (2xx)

| Código de status | Descrição | Casos de uso típicos |
| - | - | - |
| 200 OK | Solicitação concluída com sucesso | Requisições GET, operações bem-sucedidas, recuperação de dados |
| 201 Criado | Recurso criado com sucesso | Novos pagamentos, Virtual Accounts, payouts |

### Erros do cliente (4xx)

| Código de status | Descrição | Causas comuns |
| - | - | - |
| 400 Solicitação Inválida | Solicitação malformada ou parâmetros inválidos | Campos obrigatórios ausentes, formatos de dados inválidos, erros de validação |
| 401 Não autorizado | Autenticação necessária ou inválida | Token de acesso ausente/inválido, tokens expirados, credenciais inválidas |
| 403 Proibido | Permissões insuficientes | IP não incluído na lista de permissões, restrições de conta, acesso não autorizado. |
| 404 Não encontrado | Recurso não encontrado | IDs de transação inválidos, endpoints incorretos, recursos excluídos |
| 429 Pedidos em Excesso | Limite de taxa excedido | Muitas chamadas à API em um curto período, excedendo a cota. |

### Erros do servidor (5xx)

| Código de status | Descrição | Ação recomendada |
| - | - | - |
| 500 Erro interno do servidor | Erro inesperado do servidor | Tente novamente com recuo exponencial. Se o problema persistir, entre em contato com o suporte. |
| 502 Bad Gateway | Serviço upstream indisponível | Tente novamente após um breve intervalo e verifique o status do sistema. |
| 503 Serviço indisponível | Interrupção temporária do serviço | Verifique a página de status, tente novamente mais tarde, acione o disjuntor. |

***

## Objeto de status

O objeto `status` fornece informações detalhadas e específicas do Localpayment sobre os resultados das transações e está incluído na maioria das respostas da API que envolvem operações financeiras.

### Estrutura do Objeto de Status

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  }
}
```

### Campos do objeto de status

| Campo | Tipo | Descrição | Exemplo |
| - | - | - | - |
| `code` | string | Código de status específico do Localpayment | `103`, `200`, `701` |
| `description` | string | Resumo do status em linguagem acessível a humanos | `Approved`, "Completed", "Rejected" |
| `detail` | string | Contexto ou explicação adicional | `The payin is pending the confirmation` |

***

## Padrões de resposta comuns

### Resposta de pagamento bem-sucedido

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "dd616d71-f5cd-4bb5-9c2c-f421241ab301",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1099",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 2300,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 2300,
    "fxQuote": 1
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 2300
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "USD",
    "fxSource": 1,
    "fxQuote": 1020.72259627,
    "amount": 0.6,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "LTDA",
    "document": {
      "type": "CUIL",
      "id": "30-31.145.201-7"
    },
    "email": "email@email.com",
    "phone": {
      "countryCode": "countryCode",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "City",
      "state": "state",
      "country": "Argentina",
      "zipCode": "1688",
      "comment": "port 801"
    },
    "birthdate": "2000-01-01",
    "nationality": "nationality"
  },
  "payer": {
    "bank": {
      "name": "Bank Name",
      "code": "191",
      "account": {
        "type": "S",
        "number": "1910119655111901676653"
      }
    },
    "type": "INDIVIDUAL",
    "name": "Prueba",
    "lastname": "Test",
    "document": {
      "type": "CUIT",
      "id": "20276201078"
    },
    "email": "email@email.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "City",
      "state": "state",
      "country": "Country",
      "zipCode": "1686",
      "comment": "May the force be with you, always!"
    },
    "birthdate": "01/01/1990",
    "nationality": "American"
  },
  "intermediaries": [],
  "wireInstructions": {
    "beneficiary": {
      "bank": {
        "name": "BANCO MACRO S.A.",
        "code": "0118",
        "branch": {},
        "account": {
          "type": "S",
          "number": "2850328631194198460271"
        }
      },
      "type": "INDIVIDUAL",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      }
    },
    "referenceCode": "1022000084"
  },
  "date": {
    "creationDate": "2024-12-30T18:50:10.124+00:00",
    "processedDate": "2024-12-30T18:50:10.6159529",
    "expirationDate": "2025-01-06T18:50:10.5803114"
  },
  "errors": []
}
```

### Padrão de resposta de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "8c0b537a-e907-4d87-93db-5dab9807e093",
  "internalId": "dddfde6c-b61c-4b0e-8916-d88886133c4d",
  "status": {
    "code": "701",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "701",
      "detail": "Invalid bank account number. Account number verification failed."
    }
  ]
}
```

***

## Guia de Status e Erros de Transações

Selecione um tipo de transação específico abaixo para obter uma lista detalhada de seus status e códigos de erro.

> [card] [Payin](https://docs.localpayment.com/pt-br/reference/payin-status-error-codes.md)
>
> Códigos de status e erro para recebimento de fundos via Virtual Accounts, Columns cols=2 e APMs.

> [card] [Payout](https://docs.localpayment.com/pt-br/reference/payout-status-error-codes.md)
>
> Códigos de status e erro para o envio de fundos aos beneficiários.

> [card] [Reembolso](https://docs.localpayment.com/pt-br/reference/refund-status-error-codes.md)
>
> Códigos de status e erro para devolução de fundos a um cliente.

> [card] [Estorno](https://docs.localpayment.com/pt-br/reference/chargeback-status-error-codes.md)
>
> Códigos de status e erro para transações contestadas e estornos forçados.

> [card] [Devolução](https://docs.localpayment.com/pt-br/reference/return-status-error-codes.md)
>
> Códigos de status e erro para pagamentos devolvidos e liquidações não realizadas.

> [card] [Recall](https://docs.localpayment.com/pt-br/reference/recall-status-error-codes.md)
>
> Códigos de status e erro para estornos e reversões de pagamentos.

> [card] [Crédito](https://docs.localpayment.com/pt-br/reference/credit-status-error-codes.md)
>
> Códigos de status e erro para transações e ajustes de crédito.

> [card] [Débito](https://docs.localpayment.com/pt-br/reference/debit-status-error-codes.md)
>
> Códigos de status e erro para transações de débito e deduções de fundos.

> [card] [Assinaturas](https://docs.localpayment.com/pt-br/reference/subscriptions-status-error-codes.md)
>
> Códigos de status e erro para faturamento recorrente e ciclos de assinatura.

> [card] [Câmbio de Moedas](https://docs.localpayment.com/pt-br/reference/currency-exchange-status-error-codes.md)
>
> Códigos de status e erro para transações cambiais.

> [card] [Wire In](https://docs.localpayment.com/pt-br/reference/wire-in-status-error-codes.md)
>
> Códigos de status e erro para transferências bancárias recebidas.

> [card] [Wire Out](https://docs.localpayment.com/pt-br/reference/wire-out-status-error-codes.md)
>
> Status e códigos de erro para transferências bancárias de saída.

> [card] [Despesas](https://docs.localpayment.com/pt-br/reference/expenses-status-error-codes.md)
>
> Códigos de status e erro para deduções de taxas e transações de despesas.

> [card] [Taxa recorrente](https://docs.localpayment.com/pt-br/reference/recurring-fee-status-error-codes.md)
>
> Códigos de status e erro para cobranças de taxas periódicas.

***

## Recursos relacionados

> [card] [Guia de Webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Aprenda como receber atualizações de status em tempo real.

> [card] [Tratamento de erros](https://docs.localpayment.com/pt-br/docs/error-handling.md)
>
> Guia para lidar com transações falhas

> [card] [Suporte](mailto:support@localpayment.com)
>
> Obtenha ajuda com problemas de status específicos

> [!NOTE]
>
> **Dica profissional**
>
> Implemente um sistema de registro abrangente que capture tanto os códigos de status quanto os códigos de erro com seus respectivos registros de data e hora. Isso cria trilhas de auditoria claras para atender aos requisitos de conformidade e torna a depuração de problemas significativamente mais rápida. Inclua a resposta de erro completa nos registros, e não apenas o código de erro.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.