> ## 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.

# Pagamentos únicos

A Localpayment permite que os comerciantes processem pagamentos únicos usando cartões de crédito e débito, em vários países e moedas.

Este guia descreve o processo para iniciar um pagamento único com cartão através da API da Localpayment, detalhando os parâmetros necessários, o tratamento de respostas e a interpretação dos códigos de status.

## Antes de começar

Antes de começar, certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Passo 1: Solicitar um pagamento com cartão

Para iniciar um pagamento único com cartão, você precisará enviar uma solicitação `POST` para o endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md).

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `payer` | Informações do pagador para fins de conformidade | ✅ |
| `merchant` | Detalhes do comerciante/empresa | ✅ |
| `paymentMethod` | Configuração do método de pagamento | ✅ |
| `amount` | Valor da transação | ✅ |
| `currency` | Código da moeda da transação | ✅ |
| `country` | Código do país de destino | ✅ |

O `paymentMethod.code` depende do país, da bandeira do cartão e do produto (crédito ou débito). No Peru, ele também depende da moeda. Consulte os [Códigos de métodos de pagamento com cartão](https://docs.localpayment.com/pt-br/docs/card-payment-methods.md) para ver a lista completa.

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/payins.md) na solicitação.

### Pagamento com cartão tokenizado

Se você já tiver tokenizado o cartão de um cliente, poderá usar o token em vez de enviar os dados completos do cartão para processar um pagamento único. Isso aumenta a segurança e simplifica o fluxo de pagamento, eliminando a necessidade de solicitar novamente as informações do cartão.

Para obter informações detalhadas sobre a tokenização de cartões, consulte a documentação de [Tokenização](https://docs.localpayment.com/pt-br/docs/tokenization.md).

### Pagamento com 3D Secure

Se o titular do cartão exigir autenticação adicional, o fluxo prosseguirá pelo 3D Secure. Nesse caso, o Localpayment retorna o URL de desafio do emissor na resposta da API, e é responsabilidade do comerciante redirecionar o cliente ou exibir o desafio durante o processo de finalização da compra. Isso permite que o titular do cartão conclua a verificação necessária. A experiência exata com o 3D Secure pode variar dependendo do emissor e do país do cliente.

Para obter informações detalhadas sobre pagamentos 3D Secure, consulte a documentação do [3D Secure](https://docs.localpayment.com/pt-br/docs/3d-secure.md).

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma resposta bem-sucedida inclui informações detalhadas sobre a transação e identificadores de rastreamento:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "john.doe@example.com",
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": []
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador único de transação do Localpayment. | Rastreamento e suporte de transações. |
| `externalId` | Seu número de referência. | Conciliação interna. |
| `status.code` | Código de status da transação atual. | Monitoramento de status. |
| `date.creationDate` | Quando a transação foi criada. | Registro de auditoria. |
| `date.processedDate` | Quando o processamento da transação começou. | Cálculo do tempo de processamento. |

### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

***

## Etapa 3: Rastrear o status da transação

Após iniciar um pagamento único, monitore seu progresso através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | O Payin foi confirmado, mas ainda não foi creditado. |
| `200` | `Completed` | O Payin foi concluído. |
| `300` | `Rejected` | Parâmetro inválido + \[nome do parâmetro] + \[motivo]. |

> [!NOTE]
>
> **APPROVED não é o status final.** Significa que o pagamento com cartão foi confirmado, mas os fundos ainda não foram creditados no seu saldo. Você pode ver o pagamento, mas não pode sacar os fundos até que o status mude para Completed. Isso costuma levar de 1 a 2 dias, dependendo do provedor.

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Transação concluída com sucesso**: Fluxo padrão de Payin
2. **Erros de validação**: conta bancária inválida, campos ausentes
3. **Atrasos no processamento**: transações que levam tempo para serem processadas.
4. **Transações com falha**: Fundos insuficientes, beneficiários bloqueados
5. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após o processamento de um pagamento único, você poderá precisar realizar ações adicionais, como:

> [card] [Reembolsar a transação](https://docs.localpayment.com/pt-br/docs/refund-card-payment)
>
> Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

> [card] [Gerenciar estornos](https://docs.localpayment.com/pt-br/docs/chargebacks.md)
>
> Em caso de disputa, você poderá precisar lidar com estornos. Consulte a documentação para obter informações sobre esse processo.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Você pode obter informações detalhadas sobre as transações usando a API Localpayment.


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