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

# Gere sua primeira transação

> Crie sua primeira cobrança Pix (Cash In) na Super Finance

Com os certificados de **Cash In** e o **Bearer Token** em mãos, vamos criar a sua primeira transação.

<Info>
  Toda requisição de Cash In usa a base URL `https://api.pix.basspago.com.br` e os certificados de Cash In. Precisa do token? Volte para [Autenticação](/autenticacao).
</Info>

## Endpoint

```
POST https://api.pix.basspago.com.br/cob
```

## Certificados e headers

Envie os certificados de Cash In e a senha na requisição:

```bash theme={null}
--cert ./client.crt \
--key ./client.key \
--pass "SUA_SENHA_DO_CERTIFICADO"
```

E os headers de autenticação:

```bash theme={null}
-H "Content-Type: application/json" \
-H "Authorization: Bearer {access_token}"
```

## Parâmetros do body

<ParamField body="calendario.expiracao" type="integer" required>
  Tempo em segundos para a cobrança expirar.
</ParamField>

<ParamField body="devedor.cpf" type="string">
  CPF do cliente.
</ParamField>

<ParamField body="devedor.nome" type="string">
  Nome do cliente.
</ParamField>

<ParamField body="valor.original" type="string" required>
  Valor da cobrança em reais. Exemplo: `"50.00"`.
</ParamField>

<ParamField body="chave" type="string" required>
  Chave Pix cadastrada na conta (Ao gerar as credenciais Cash In, a chave pix é retornada lá).
</ParamField>

<ParamField body="solicitacaoPagador" type="string">
  Descrição do pagamento. Fica visível para o cliente.
</ParamField>

<ParamField body="infoAdicionais" type="array">
  Informações internas opcionais.
</ParamField>

## Exemplo de requisição

```bash theme={null}
curl -X POST "https://api.pix.basspago.com.br/cob" \
  --cert ./client.crt \
  --key ./client.key \
  --pass "SUA_SENHA_DO_CERTIFICADO" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "calendario": {
      "expiracao": 3600
    },
    "devedor": {
      "cpf": "11144477735",
      "nome": "Maria Oliveira"
    },
    "valor": {
      "original": "49.90"
    },
    "chave": "e3b0c442-98fc-4c1a-b2d6-9a7f5e10c3d4",
    "solicitacaoPagador": "Pagamento do pedido #90210"
  }'
```

## Exemplo de resposta

```json theme={null}
{
  "calendario": {
    "criacao": "2026-07-21T13:05:12.000Z",
    "expiracao": 3600
  },
  "txid": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "revisao": 0,
  "loc": {
    "id": 4821,
    "location": "pix.basspago.com/qr/v2/9f8e7d6c5b4a",
    "tipoCob": "cob"
  },
  "location": "pix.basspago.com/qr/v2/9f8e7d6c5b4a",
  "status": "ATIVA",
  "devedor": {
    "cpf": "11144477735",
    "nome": "Maria Oliveira"
  },
  "valor": {
    "original": "49.90"
  },
  "chave": "e3b0c442-98fc-4c1a-b2d6-9a7f5e10c3d4",
  "solicitacaoPagador": "Pagamento do pedido #90210",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "90210"
    }
  ],
  "pixCopiaECola": "00020126580014br.gov.bcb.pix..."
}
```

O campo `pixCopiaECola` é o código que o cliente usa para pagar. Use `location` para gerar o QR Code.

## Webhooks de transações

Se você cadastrou os webhooks corretamente no FINANCE, receberá notificações sempre que o status de uma transação mudar. Veja abaixo os principais eventos e seus campos.

<Tabs>
  <Tab title="Transação paga">
    ```json theme={null}
    {
      "data": {
        "id": 731045,
        "txId": "7b3c9f21a84e5d60c1f2a3b4c5d6e7f8",
        "pixKey": "a1c2e3f4-5678-49ab-b0cd-1122334455ee",
        "status": "LIQUIDATED",
        "payment": {
          "amount": "49.90",
          "currency": "BRL"
        },
        "refunds": [],
        "createdAt": "2026-07-21T13:05:43.290+00:00",
        "errorCode": null,
        "endToEndId": "E12345678202607211305a1b2c3d4e5f",
        "ticketData": {},
        "webhookType": "RECEIVE",
        "debtorAccount": {
          "ispb": "12345678",
          "name": "CARLOS HENRIQUE SOUZA",
          "issuer": "0000",
          "number": "0000",
          "document": "11144477735",
          "accountType": "SVGS"
        },
        "idempotencyKey": null,
        "creditDebitType": "CREDIT",
        "creditorAccount": {
          "ispb": "87654321",
          "name": "SUA LOJA LTDA",
          "issuer": "0000",
          "number": "0000",
          "document": "12345678000199",
          "accountType": "TRAN"
        },
        "localInstrument": "QRDN",
        "transactionType": "PIX",
        "remittanceInformation": null
      },
      "type": "RECEIVE"
    }
    ```

    | Campo                        | Tipo           | Descrição                                    |
    | ---------------------------- | -------------- | -------------------------------------------- |
    | `data.id`                    | integer        | Identificador da transação na Super Finance. |
    | `data.txId`                  | string         | Identificador da cobrança (txid).            |
    | `data.pixKey`                | string         | Chave Pix que recebeu o pagamento.           |
    | `data.status`                | string         | Status da transação (ex.: `LIQUIDATED`).     |
    | `data.payment.amount`        | string         | Valor pago.                                  |
    | `data.payment.currency`      | string         | Moeda (ex.: `BRL`).                          |
    | `data.refunds`               | array          | Reembolsos associados à transação.           |
    | `data.createdAt`             | string         | Data e hora do evento (ISO 8601).            |
    | `data.errorCode`             | string \| null | Código de erro, quando houver.               |
    | `data.endToEndId`            | string         | Identificador end-to-end do Pix.             |
    | `data.webhookType`           | string         | Tipo do webhook (`RECEIVE`).                 |
    | `data.debtorAccount`         | object         | Dados da conta pagadora.                     |
    | `data.idempotencyKey`        | string \| null | Chave de idempotência, quando enviada.       |
    | `data.creditDebitType`       | string         | `CREDIT` ou `DEBIT`.                         |
    | `data.creditorAccount`       | object         | Dados da conta recebedora.                   |
    | `data.localInstrument`       | string         | Forma do Pix (ex.: `QRDN`).                  |
    | `data.transactionType`       | string         | Tipo da transação (ex.: `PIX`).              |
    | `data.remittanceInformation` | string \| null | Informação de remessa, quando houver.        |
    | `type`                       | string         | Tipo do evento (`RECEIVE`).                  |
  </Tab>

  <Tab title="Contestação recebida">
    ```json theme={null}
    {
      "data": {
        "id": "b2d4f6a8-1357-4ace-9bdf-024681357900",
        "type": "REFUND_REQUEST",
        "status": "WAITING_PSP",
        "endToEndId": "E12345678202607211856a1b2c3d4e5f",
        "reportedBy": "DEBITED_PARTICIPANT",
        "creationDate": "2026-07-21T18:56:00.130+00:00",
        "reportDetails": "Motivo da contestação informado pelo pagador...",
        "transactionId": "731045",
        "analysisResult": null,
        "analysisDetails": null,
        "transactionAmount": {
          "amount": 49.9,
          "currency": "BRL"
        },
        "lastModificationDate": "2026-07-21T18:56:00.143+00:00"
      },
      "type": "INFRACTION"
    }
    ```

    Possíveis status:

    | Status        | Significado                               |
    | ------------- | ----------------------------------------- |
    | `WAITING_PSP` | Contestação aberta e aguardando resposta. |
    | `CLOSED`      | Contestação encerrada após análise.       |
    | `CANCELED`    | Contestação cancelada.                    |

    <Warning>
      Todo MED recebido exige resposta em até **24 horas**. Sempre que você receber um evento de contestação com o status `WAITING_PSP`, significa que estamos aguardando a sua resposta para esse MED — trate esse webhook com extrema prioridade. Não responder aos MEDs pode implicar em restrições para a sua conta.
    </Warning>

    | Campo                             | Tipo           | Descrição                                                    |
    | --------------------------------- | -------------- | ------------------------------------------------------------ |
    | `data.id`                         | string         | Identificador da contestação (MED).                          |
    | `data.type`                       | string         | Tipo da contestação (ex.: `REFUND_REQUEST`).                 |
    | `data.status`                     | string         | Status da contestação (`WAITING_PSP`, `CLOSED`, `CANCELED`). |
    | `data.endToEndId`                 | string         | Identificador end-to-end do Pix contestado.                  |
    | `data.reportedBy`                 | string         | Quem abriu a contestação.                                    |
    | `data.creationDate`               | string         | Data e hora de abertura (ISO 8601).                          |
    | `data.reportDetails`              | string         | Motivo informado pelo pagador.                               |
    | `data.transactionId`              | string         | Identificador da transação relacionada.                      |
    | `data.analysisResult`             | string \| null | Resultado da análise, quando concluída.                      |
    | `data.analysisDetails`            | string \| null | Detalhes da análise, quando concluída.                       |
    | `data.transactionAmount.amount`   | number         | Valor contestado.                                            |
    | `data.transactionAmount.currency` | string         | Moeda (ex.: `BRL`).                                          |
    | `data.lastModificationDate`       | string         | Última modificação (ISO 8601).                               |
    | `type`                            | string         | Tipo do evento (`INFRACTION`).                               |
  </Tab>

  <Tab title="Pagamento reembolsado">
    ```json theme={null}
    {
      "data": {
        "id": 731050,
        "txId": null,
        "pixKey": null,
        "status": "REFUNDED",
        "payment": {
          "amount": "150.00",
          "currency": "BRL"
        },
        "endToEndId": "E87654321202607211200f6e5d4c3b2a",
        "webhookType": "REFUND",
        "debtorAccount": {
          "ispb": "12345678",
          "name": "MARIANA COSTA LIMA",
          "issuer": "0001",
          "number": "45678912",
          "document": "22255588896",
          "accountType": "CACC"
        },
        "creditorAccount": {
          "ispb": "87654321",
          "name": "SUA LOJA LTDA",
          "issuer": "0000",
          "number": "0000",
          "document": "12345678000199",
          "accountType": "TRAN"
        },
        "creditDebitType": "CREDIT",
        "localInstrument": "DICT",
        "transactionType": "PIX",
        "createdAt": "2026-07-21T12:00:00.000Z"
      },
      "type": "REFUND"
    }
    ```

    | Campo                   | Tipo           | Descrição                                        |
    | ----------------------- | -------------- | ------------------------------------------------ |
    | `data.id`               | integer        | Identificador da transação na Super Finance.     |
    | `data.txId`             | string \| null | Identificador da cobrança (txid), quando houver. |
    | `data.pixKey`           | string \| null | Chave Pix envolvida, quando houver.              |
    | `data.status`           | string         | Status da transação (`REFUNDED`).                |
    | `data.payment.amount`   | string         | Valor reembolsado.                               |
    | `data.payment.currency` | string         | Moeda (ex.: `BRL`).                              |
    | `data.endToEndId`       | string         | Identificador end-to-end do Pix.                 |
    | `data.webhookType`      | string         | Tipo do webhook (`REFUND`).                      |
    | `data.debtorAccount`    | object         | Dados da conta pagadora.                         |
    | `data.creditorAccount`  | object         | Dados da conta recebedora.                       |
    | `data.creditDebitType`  | string         | `CREDIT` ou `DEBIT`.                             |
    | `data.localInstrument`  | string         | Forma do Pix (ex.: `DICT`).                      |
    | `data.transactionType`  | string         | Tipo da transação (ex.: `PIX`).                  |
    | `data.createdAt`        | string         | Data e hora do evento (ISO 8601).                |
    | `type`                  | string         | Tipo do evento (`REFUND`).                       |
  </Tab>
</Tabs>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Realize sua primeira transferência" icon="money-bill-transfer" href="/primeira-transferencia">
    Faça sua primeira transferência (Cash Out) via API de Contas.
  </Card>

  <Card title="Saiba mais sobre webhooks" icon="webhook" href="/webhooks">
    Entenda os tipos de evento e como tratar cada notificação.
  </Card>
</CardGroup>