# Visão Geral de Pagamentos

Com o Pluggy Payments, você pode facilmente criar links de pagamento para cobrar seus clientes e rastrear automaticamente seus pagamentos, aproveitando integrações OAuth seguras com instituições usando a infraestrutura de Iniciação de Pagamento do Open Finance.

Você também pode realizar [Pagamentos Agendados](/docs/scheduled-payments), que podem ser usados para coisas como cobrança mensal pré-acordada.

Nossa solução de Pagamentos lida com três conceitos principais:

- **Destinatário do Pagamento**: uma conta bancária que recebe pagamentos
- **Solicitação de Pagamento**: um pedido para pagar um determinado valor a um destinatário. Ele possui um link de pagamento que você pode enviar ao seu cliente para pagar.
- **Intenção de Pagamento**: uma tentativa de pagar uma Solicitação de Pagamento. É criada quando seu cliente clica em "Pagar" em nosso site de pagamento.

> **Recurso apenas por convite**
>
> Este recurso está em beta e deve ser habilitado especificamente para seu cliente. Se você estiver interessado em experimentá-lo, entre em contato com nossa equipe de Vendas!

## Fluxo de exemplo

1. Primeiro, criamos um Destinatário do Pagamento para indicar qual conta bancária receberá o pagamento (você só precisará fazer isso uma vez por conta).

```json title="POST /payments/recipients (request)"
{
  "taxNumber": "11111111111", // CPF ou CNPJ
  "name": "John Doe",
  "paymentInstitutionId": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
  "account": {
    "branch": "0001",
    "number": "123456",
    "type": "CHECKING_ACCOUNT"
  }
}
```

**Resposta**

```json title="POST /payments/recipients (response)"
{
    "type": "BANK_ACCOUNT",
    "id": "36fcb10f-825c-1111-b67c-93d0e47f4e77",
    "name": "John Doe",
    "taxNumber": "11111111111",
    "isDefault": false,
    "paymentInstitution": {
        "id": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
        "name": "SWAP MEIOS DE PAGAMENTOS INSTITUICAO DE PAGAMENTO S.A.",
        "tradeName": "SWAP MP IP SA",
        "ispb": "31680151",
        "compe": null,
        "createdAt": "2023-12-08T17:52:21.001Z",
        "updatedAt": "2023-12-08T17:52:21.001Z"
    },
    "account": {
        "type": "*******",
        "number": "****56",
        "branch": "0001"
    },
    "pixKey": null,
    "createdAt": "2025-06-25T14:09:44.717Z",
    "updatedAt": "2025-06-25T14:09:44.717Z"
}
```

Nota: você pode obter os IDs das instituições [neste endpoint](/reference/payment-recipient/payment-recipients-institution-list).

2. Crie uma Solicitação de Pagamento com o valor que deseja cobrar de seu cliente, juntamente com o ID do destinatário da etapa anterior.

```json title="POST /payments/requests (request)"
{
  "amount": 0.01,
  "description": "Meu pedido de pagamento",
  "recipientId": "ab276a3d-17ba-47eb-97bf-688475037ffe"
}
```

**Resposta**

```json title="POST /payments/requests (response)"
{
    "id": "bb236f8d-caa5-47eb-97bf-688475037f3e",
    "amount": 0.01,
    "description": "Meu pedido de pagamento",
    "status": "CREATED",
    "createdAt": "2023-11-14T16:57:17.511Z",
    "updatedAt": "2023-11-14T16:57:17.511Z",
    "callbackUrls": null,
    "paymentUrl": "https://pay.pluggy.ai/bb236f8d-caa5-47eb-97bf-688475037f3e"
}
```

3. Envie o `paymentUrl` da resposta para seu cliente.

4. O cliente visitará nosso site Pluggy Pagamentos.

> **URL de pagamento vs. URL de consentimento**
>
> O `paymentUrl` abre a página de pagamento do Pluggy. Ele não tem uma expiração fixa de cinco minutos; se pode ser usado depende do status e configuração da Solicitação de Pagamento. Depois que o cliente escolhe uma instituição e clica em **Pagar**, o Pluggy cria uma Intenção de Pagamento e retorna uma `consentUrl`. A `consentUrl` é a URL de autorização do banco e expira após cinco minutos. Essas são URLs diferentes com ciclos de vida diferentes.

## Reagindo a um pagamento

Você pode indicar para onde redirecionar o usuário após completar um pagamento usando o campo `callbackUrls`:

```json title="POST /payments/requests"
{
  "amount": 0.01,
  "description": "Transferência",
  "callbackUrls": {
    "success": "https://my-success-url.com",
    "error": "https://my-error-url.com",
    "pending": "https://my-pending-url.com"
  }
}
```

Também é possível reagir a um pagamento concluído para criar automações úteis, usando [webhooks](/docs/webhooks).

## Pré-preenchendo o CPF/CNPJ

O CPF/CNPJ do pagador é exigido pelo Open Finance para iniciar um pagamento. Para PF, é necessário CPF, e para PJ, são ambos CPF e CNPJ. Para melhorar a experiência de pagamento e reduzir erros do usuário, você pode pré-preencher criando um Cliente de Pagamento:

**Solicitação — PF**

```json title="POST /payments/customers (PF)"
{
  "type": "INDIVIDUAL",
  "cpf": "123.456.789-12"
}
```

**Solicitação — PJ**

```json title="POST /payments/customers (PJ)"
{
  "type": "BUSINESS",
  "cpf": "123.456.789-12",
  "cnpj": "12.345.678/9012-34"
}
```

Agora, ao criar a Solicitação de Pagamento, inclua o campo `customerId` apontando para o Cliente de Pagamento criado anteriormente.

## Pré-selecionando a instituição do pagador

Você pode definir uma instituição pré-selecionada para o pagador ao iniciar o fluxo de iniciação de pagamento. Isso pode ser útil se você quiser guiar o usuário a usar uma instituição específica para fazer o pagamento. Para fazer isso, você pode criar o cliente de pagamento fornecendo um `connectorId`:

```json title="POST /payments/customers"
{
  "type": "INDIVIDUAL",
  "cpf": "123.456.789-12",
  "connectorId": 612
}
```

## Envolvendo um QR PIX existente

Se você quiser usar o Pluggy para pagar um QR PIX para permitir o rastreamento de seu pagamento, pode criar um Destinatário a partir do QR PIX:

```json title="POST /payments/recipients/pix-qr"
{
  "pixQrCode": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20"
}
```

## Criando uma experiência de pagamento personalizada

Se você não quiser usar nosso fluxo `pay.pluggy.ai`, pode implementar sua experiência de pagamento personalizada usando nossa API.

Primeiramente, você precisa criar uma **Solicitação de Pagamento**. Lá, você especificará quanto dinheiro deseja receber. Além disso, você pode configurar uma descrição (a ser mostrada ao usuário final no momento em que ele autoriza o pagamento) e um conjunto de URLs de callback para onde o usuário será redirecionado após a autorização do pagamento ser concluída. Os campos `description`, `callbackUrl` e `isSandbox` são opcionais.

```json title="Solicitação"
{
  "amount": 100.50,
  "description": "Transferência",
  "callbackUrls": {
    "success": "https://my-success-url.com",
    "error": "https://my-error-url.com",
    "pending": "https://my-pending-url.com"
  },
  "isSandbox": true
}
```

**Resposta**

```json title="Resposta"
{
  "id": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "amount": 100.50,
  "description": "Transferência",
  "status": "CREATED",
  "createdAt": "2023-11-06T13:03:45.689Z",
  "updatedAt": "2023-11-06T13:03:45.689Z",
  "callbackUrls": {
    "success": "https://my-success-url.com",
    "error": "https://my-error-url.com"
  },
  "isSandbox": true
}
```

Você pode encontrar os detalhes do endpoint [aqui](/reference/payment-request-create).

### Criando uma Intenção de Pagamento

Após criar uma solicitação de pagamento, você precisa criar uma **Intenção de Pagamento**. Isso representa a intenção de uma pessoa de fazer aquele pagamento. Por exemplo, se você quiser cobrar um cliente R$10, primeiro precisa criar uma **Solicitação de Pagamento** para esse valor e, em seguida, uma **Intenção de Pagamento** quando o usuário quiser pagar.

Para criar uma **Intenção de Pagamento**, você precisa enviar o ID da instituição (`connectorId`) que o usuário usará para fazer o pagamento. Você pode encontrar a lista de conectores usando nosso [endpoint de conectores](/reference/connectors-list) e filtrar aqueles com a propriedade `supportsPaymentInitiation` com valor `true`. Além disso, você precisa enviar as credenciais exigidas da instituição no campo `parameters`. Essas credenciais também podem ser encontradas no [endpoint de conectores](/reference/connectors-list).

Esta é a solicitação para criar uma **Intenção de Pagamento**.

**Solicitação — Conector Pessoal**

```json title="Solicitação Conector Pessoal"
{
  "paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "connectorId": 601,
  "parameters": {
    "cpf": "76109277673"
  }
}
```

**Solicitação — Conector Empresarial**

```json title="Solicitação Conector Empresarial"
{
  "paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "connectorId": 618,
  "parameters": {
    "cpf": "76109277673",
    "cnpj": "11111111111111"
  }
}
```

**Resposta**

```json title="Resposta"
{
  "id": "4316602b-8fb5-4bfd-92dc-32921b7414f1",
  "status": "CONSENT_AWAITING_AUTHORIZATION",
  "createdAt": "2023-11-09T20:10:42.706Z",
  "updatedAt": "2023-11-09T20:10:42.706Z",
  "paymentRequest": {
    "id": "f6696d02-3583-47ae-b195-148d71b8ae9b",
    "amount": 100.50,
    "description": null,
    "status": "IN_PROGRESS",
    "createdAt": "2023-11-09T20:10:25.084Z",
    "updatedAt": "2023-11-09T20:10:42.706Z",
    "callbackUrls": {
      "success": "https://my-success-url.com",
      "error": "https://my-error-url.com"
    }
  },
  "connector": {
    "id": 601,
    "name": "Itaú",
    "primaryColor": "48be9d",
    "institutionUrl": "https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
        "validationMessage": "CPF deve ter 11 números.",
        "label": "CPF",
        "name": "cpf",
        "type": "number",
        "placeholder": "",
        "optional": false
      }
    ],
    "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/itau.svg",
    "hasMFA": false,
    "oauth": true,
    "health": {
      "status": "ONLINE",
      "stage": null
    },
    "products": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "IDENTITY",
      "CREDIT_CARDS",
      "PAYMENT_DATA",
      "LOANS",
      "INVESTMENTS"
    ],
    "createdAt": "2023-07-24T14:29:32.140Z",
    "isSandbox": true,
    "isOpenFinance": true,
    "updatedAt": "2023-11-09T19:17:08.495Z",
    "supportsPaymentInitiation": true
  },
  "consentUrl": "https://consent-url.com"
}
```

Existem propriedades importantes no objeto de resposta:

- **status**: Neste ponto, terá o valor `CONSENT_AWAITING_AUTHORIZATION`. Isso significa que o usuário precisa autorizá-lo na instituição. Você pode verificar os outros valores possíveis [aqui](/docs/payment-intent-statuses).
- **consentUrl**: É a URL para onde você precisa redirecionar o usuário para autorizar o pagamento. Esta URL de autorização do banco expira após 5 minutos. Essa expiração se aplica apenas à `consentUrl`; não significa que o `paymentUrl` tenha uma expiração de cinco minutos. Após a conclusão do pagamento, o usuário será redirecionado para as URLs especificadas nos `callbackUrls` definidos anteriormente, ou para uma URL padrão fornecida pelo Pluggy se não tiver sido especificada.

Você pode encontrar os detalhes do endpoint [aqui](/reference/payment-intent-create).

## Testando pagamentos com o banco Sandbox

Você pode usar nosso aplicativo de testes [playground](https://playground.pluggy.ai) para testar o fluxo sem nenhuma configuração!

> **Usando sandbox sem playground**
>
> Para testar pagamentos Sandbox em nosso App, basta criar sua **Solicitação de Pagamento** com `isSandbox: true`. Em seguida, acesse:
>
> `https://pay.pluggy.ai/<PAYMENT_REQUEST_ID>`
>
> A página detectará automaticamente o ambiente sandbox e listará apenas conectores sandbox para você completar o fluxo. Use o conector Sandbox com as seguintes credenciais:

```json
{
  "cpf": "76109277673",
  "user": "ralph.bragg@gmail.com",
  "password": "P@ssword01"
}
```

Use a credencial CPF na primeira entrada. Use **user** e **password** para fazer login no Mock Bank, e ele será redirecionado para a Página de Sucesso ou de Erro dependendo do resultado do Pagamento.