> For the complete documentation index, see [llms.txt](https://docs.4p.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.4p.finance/on-ramp/criando-uma-transacao.md).

# Criando uma transação

Esta página contém instruções de como solicitar a criação de uma transação na API da 4P Finance.

#### Serviço

• Envia um JSON contendo os dados necessários para a criação de uma cobrança imediata.

• Retorna um JSON contendo os dados da cobrança criada, inclusive Pix Copia-e-Cola.

#### Titular da transação

Toda transação é registrada em nome de um titular. Quem é o titular depende do perfil da sua conta na API, que é definido pela 4P Finance junto com você:

| Perfil      | Titular da transação                                                                                            | CPF/CNPJ no payload                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Padrão**  | O titular da conta dona da chave API (`x-api-key`).                                                             | Opcional. Se for enviado, o formato é validado, mas o documento não muda o titular. |
| **Revenda** | O CPF/CNPJ enviado no payload. Esse documento precisa ter uma conta na 4P Finance com KYC/KYB aprovado e ativa. | Obrigatório.                                                                        |

O perfil também define quem pode pagar a cobrança:

* **Padrão:** o PIX pode ser pago por qualquer pessoa ou empresa.
* **Revenda:** o PIX precisa ser pago pelo mesmo CPF/CNPJ enviado no payload de criação da transação. Se o pagamento vier de outro documento, a transação não é concluída e o valor é estornado ao pagador.

> Se você não sabe qual é o perfil da sua conta, fale com o suporte da 4P Finance. Contas sem perfil definido seguem o perfil Padrão.

#### Solicitação de registro/transação

A requisição para criar ou registrar uma transação deve trazer no corpo um JSON com os dados da transação.

#### Exemplo de payload

```json
{
  "cpf": "01234567899", // Troque esta chave para "cnpj" no caso de CNPJ / Pessoa Jurídica. Obrigatório no perfil Revenda, opcional no perfil Padrão.
  "email": "usuario@example.com",
  "amount": 1.10,
  "expires": 3600,
  "custom_id": "PN123",
  "custom_data": {
    "chain": "Arbitrum", // Opcional (Default: Arbitrum)
    "asset": "USDT", // Opcional (Default: USDT)
    "receiver_wallet": "0x4328...edFB995B6I"
  },
  "description": "Cobrança de assinatura #PN123",
  "notification_url": "https://seu-dominio-webhook.com.br/param=tes&token=abcd-dfg"
}
```

#### Requisição

### Solicita a criação/registro de uma transação.

<mark style="color:green;">`PUT`</mark> `https://api.4p.finance/v1/pix/transaction`

Realiza a solicitação do registro de uma transação.

**Headers**

| Name                                        | Type   | Description    |
| ------------------------------------------- | ------ | -------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | Sua chave API. |

**Request Body**

<table><thead><tr><th width="202.765625">Name</th><th width="129.25">Type</th><th>Description</th></tr></thead><tbody><tr><td>cpf / cnpj</td><td>String</td><td>CPF (pessoa física) ou CNPJ (pessoa jurídica) do titular da transação. Envie apenas um dos dois. <strong>Perfil Revenda:</strong> obrigatório, e o documento precisa ter conta na 4P Finance com KYC/KYB aprovado e ativa. <strong>Perfil Padrão:</strong> opcional. Se for enviado, o formato é validado, mas a transação continua em nome do titular da conta dona da chave API.</td></tr><tr><td>email<mark style="color:red;">*</mark></td><td>String</td><td>E-mail do cliente associado à transação.</td></tr><tr><td>expires<mark style="color:red;">*</mark></td><td>Integer</td><td>Tempo de vida da cobrança, em segundos, a partir da data de criação. Deve ser igual ou maior do que 300. Máximo: 259200 segundos.</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>Number</td><td>Valor original da cobrança. Deve ser informado um valor maior ou igual a 0.01, com casas decimais.</td></tr><tr><td>custom_id <mark style="color:red;">*</mark></td><td>String</td><td>Id da transação ou Id do Pix. Permite que o usuário recebedor faça a conciliação dos pagamentos. Deve ser único por transação PIX e conter no máximo 255 caracteres.</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Representa um texto ( campo solicitacaoPagador do PIX ), a ser apresentado ao usuário pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao usuário recebedor. Máximo 140 caracteres.</td></tr><tr><td>notification_url <mark style="color:red;">*</mark></td><td>String</td><td>URL que receberá as notificações POST encaminhadas pelo serviço de webhook logo após o PIX ser pago.</td></tr><tr><td>custom_data<mark style="color:red;">*</mark></td><td>Object</td><td>Objeto pai para dados customizados.</td></tr><tr><td>receiver_wallet<mark style="color:red;">*</mark></td><td>String</td><td>Chave filha de <em>custom_data</em> para envio da carteira do cliente pagador do PIX, no qual receberá as criptomoedas. Usado para compras de criptomoedas através de API PIX para (P2P).</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Retorno após criar/registrar uma transação." %}

```json
{
    "http_code": 200,
    "success": true,
    "info": {
        "result": "pix_transaction_created",
        "message": "The Pix transaction was successfully created.",
        "data": {
            "calendario": {
                "criacao": "2026-01-01T11:05:53.009Z",
                "expiracao": 3600
            },
            "devedor": {
                "cnpj": "00000000000000",
                "nome": ""
            },
            "valor": {
                "modalidadeAlteracao": 0,
                "original": 1.1
            },
            "chave": "4cf1bb22-71c1-4530-b735-d240c3c0f88a",
            "solicitacaoPagador": "Cobrança de assinatura #PN123",
            "infoAdicionais": [],
            "txid": "2ce3608c77264388b956c039",
            "location": "brcode.infra.com/v2/8657085674d44db288430cftb155ca62",
            "revisao": 0,
            "status": "ATIVA",
            "pixCopiaECola": "00010301021226190014br.gov.bcb.pix2557brcode.infra.com/v2/1652085674d33db965430cfab255ba405204000053039865802BR59254Pay Finance Prestadora d6106Recife62070503***6304F9E1",
            "code": 201
        }
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Conta do titular não validada (perfil Revenda)." %}

```json
{
    "http_code": 403,
    "success": false,
    "info": {
        "result": "holder_account_not_validated",
        "message": "The account of the CPF/CNPJ provided has not been validated (KYC/KYB).",
        "data": {}
    }
}
```

{% endtab %}
{% endtabs %}

#### Retorno

O objeto *data* traz os dados do PIX, incluindo o código Copia e Cola (pixCopiaECola). Com ele, você gera a imagem do QR Code dinâmico da cobrança.

A API não gera a imagem do QR Code. Essa geração fica a cargo de cada integrador.

O objeto *devedor* traz o titular da transação: no perfil Padrão, o titular da conta dona da chave API; no perfil Revenda, o titular do CPF/CNPJ enviado.

#### Erros de titular

Quando a API não consegue definir o titular da transação, ela não cria a cobrança e retorna um dos erros abaixo em `info.result`:

| HTTP | result                         | Quando ocorre                                                                                       |
| ---- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| 400  | `holder_document_required`     | Perfil Revenda: o payload não trouxe `cpf` nem `cnpj`.                                              |
| 400  | `holder_document_invalid`      | Perfil Revenda: o CPF/CNPJ enviado é inválido.                                                      |
| 404  | `holder_account_not_found`     | Perfil Revenda: não existe conta na 4P Finance para o CPF/CNPJ enviado.                             |
| 403  | `holder_account_not_validated` | Perfil Revenda: a conta do CPF/CNPJ enviado não tem KYC/KYB aprovado.                               |
| 403  | `holder_account_inactive`      | Perfil Revenda: a conta do CPF/CNPJ enviado não está ativa.                                         |
| 422  | `owner_document_invalid`       | Perfil Padrão: a conta dona da chave API não tem um CPF/CNPJ válido cadastrado. Fale com o suporte. |
| 500  | `order_holder_error`           | Não foi possível validar o titular. Tente novamente. Se o erro persistir, fale com o suporte.       |

#### Conclusão

Após a confirmação do pagamento, o valor convertido em criptomoeda será enviado automaticamente para a carteira informada no payload da requisição.

No perfil Revenda, essa etapa só acontece se o pagamento vier do mesmo CPF/CNPJ enviado no payload de criação da transação. Caso contrário, o valor é estornado ao pagador.

O tempo médio para envio e finalização da transação é de aproximadamente 10 segundos, podendo variar de acordo com a rede blockchain selecionada e as condições da própria rede no momento da operação.

Saiba mais sobre as notificações e callbacks na próxima seção.
