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

# Criar Payin

> Cria uma nova requisição de pagamento (Payin) usando Cartão de Crédito, Boleto ou PIX.

## Autorização

Você deve obrigatoriamente fornecer sua credencial no cabeçalho.

<ParamField header="Authorization" type="string" required>
  Use o Basic Auth base64 de suas chaves de produção. Ex: `Basic cGtf...`
</ParamField>

## Body

<ParamField body="paymentMethod" type="string" required>
  Os valores aceitos são: `"CREDIT_CARD"`, `"PIX"` ou `"BOLETO"`
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor total da transação em **centavos**. Exemplo: para R\$100,00 envie `10000`
</ParamField>

<ParamField body="referenceId" type="string" required>
  ID único ou número do pedido dentro do banco de dados da sua aplicação associada à cobrança.
</ParamField>

<ParamField body="webhookUrl" type="string">
  Opcional. Uma URL do seu backend (`https://...`) que deverá ser notificada quando o status deste pagamento mudar (Ex: o Pix for pago).
</ParamField>

<ParamField body="isPhysicalProduct" type="boolean" required>
  Indica se o item cobrado exige entrega física (`true`) ou se é digital ou serviço (`false`).
</ParamField>

<ParamField body="payerIp" type="string" required>
  Endereço de IPv4 de quem está efetuando o pagamento originário (Necessário para a prevenção de Fraudes e Anti-Chargeback).
</ParamField>

***

### Customer (Cliente)

Objeto encapsulando quem está comprando de você.

<ParamField body="customer" type="object" required>
  <Expandable title="propriedades" defaultOpen>
    <ParamField body="name" type="string" required>
      Nome completo.
    </ParamField>

    <ParamField body="document" type="string" required>
      CPF ou CNPJ válido apenas em números.
    </ParamField>

    <ParamField body="email" type="string" required>
      E-mail autêntico do pagador.
    </ParamField>

    <ParamField body="phone" type="string" required>
      DDD + Número (Ex: 11999999999).
    </ParamField>

    <ParamField body="address" type="object" required>
      <Expandable title="propriedades do endereço">
        <ParamField body="street" type="string" required>
          Logradouro/Rua
        </ParamField>

        <ParamField body="number" type="string" required>
          Número residencial
        </ParamField>

        <ParamField body="complement" type="string">
          Opcional. Complemento como Bloco B.
        </ParamField>

        <ParamField body="zipCode" type="string" required>
          CEP
        </ParamField>

        <ParamField body="city" type="string" required>
          Cidade (Ex: São Paulo)
        </ParamField>

        <ParamField body="state" type="string" required>
          Sigla do Estado (Ex: SP)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

### Items (Carrinho)

Array de objetos especificando o que está sendo comprado e taxado.

<ParamField body="items" type="array" required>
  <Expandable title="item propriedades">
    <ParamField body="title" type="string" required>
      Nome ou Título legível do produto.
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Mínimo de 1.
    </ParamField>

    <ParamField body="unitPrice" type="integer" required>
      Preço de 1 único item da lista (em centavos).
    </ParamField>

    <ParamField body="description" type="string">
      Descrição opcional.
    </ParamField>
  </Expandable>
</ParamField>

***

### Card (Cartão de Crédito)

Se o `paymentMethod` escolhido foi `"CREDIT_CARD"`, o objeto `card` é **obrigatório**. Para PIX e Boleto, omita este objeto por inteiro.

<Tip>
  **Recomendado:** envie apenas `card.token` (gerado pelo SDK LegacyPay — veja [Tokenização](/tokenizacao)). Com o token, os campos de PAN bruto (`number`, `cvv`, etc.) são preenchidos com segurança pela plataforma e podem ser omitidos. Quando a tokenização é exigida, PAN bruto é rejeitado com `400 INVALID_DATA`.
</Tip>

<ParamField body="card" type="object">
  <Expandable title="propriedades do cartão">
    <ParamField body="token" type="string">
      Token opaco do cartão (`cvt_*`) gerado pelo SDK. Quando presente, substitui os campos de PAN bruto abaixo.
    </ParamField>

    <ParamField body="holderName" type="string">
      Nome impresso no plástico do cartão. Obrigatório quando não houver `token`.
    </ParamField>

    <ParamField body="number" type="string">
      Os dezesseis dígitos do cartão. Obrigatório quando não houver `token`.
    </ParamField>

    <ParamField body="expirationMonth" type="string">
      Exemplo: `08`. Obrigatório quando não houver `token`.
    </ParamField>

    <ParamField body="expirationYear" type="string">
      Exemplo: `2027` ou `27`. Obrigatório quando não houver `token`.
    </ParamField>

    <ParamField body="cvv" type="string">
      Três ou quatro dígitos de trás. Pode ser exigido mesmo com `token` (veja `capabilities.tokenization.cvvRequired`).
    </ParamField>

    <ParamField body="installments" type="integer" required>
      Quantidade de parcelas sem juros (Ex: 1 a 12).
    </ParamField>

    <ParamField body="threeDSecure" type="object">
      Opcional. Dados de autenticação 3D Secure. Normalmente preenchido automaticamente pelo SDK (`prepareCardPayment()`).

      <Expandable title="propriedades 3DS">
        <ParamField body="cavv" type="string">Cardholder Authentication Verification Value retornado pelo banco.</ParamField>
        <ParamField body="eci" type="string">Electronic Commerce Indicator (Ex: `05`).</ParamField>
        <ParamField body="xid" type="string">Transaction identifier do fluxo 3DS.</ParamField>
        <ParamField body="version" type="string">Versão do protocolo 3DS (Ex: `2.2.0`).</ParamField>
        <ParamField body="referenceId" type="string">Identificador da sessão 3DS (ex.: `operationSessionId` retornado pela sessão de 3DS).</ParamField>
        <ParamField body="authenticationId" type="string">ID de autenticação emitido pelo provedor de 3DS.</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

### Antifraud (Antifraude)

Opcional. Identificador da sessão de device fingerprint coletada pelo SDK. Veja [Antifraude](/antifraude).

<ParamField body="antifraud" type="object">
  <Expandable title="propriedades">
    <ParamField body="sessionId" type="string">
      ID da sessão de fingerprint do comprador para esta transação.
    </ParamField>
  </Expandable>
</ParamField>

***

## Response

A resposta varia ligeiramente dependendo do método de pagamento escolhido. A API sempre tentará devolver um `201 Created`.

### Sucesso: Criação de PIX

```json theme={null}
{
  "id": "payin_12345",
  "externalId": "tx_998877",
  "referenceId": "meu-pedido-1234",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "PIX",
  "createdAt": "2026-03-02T12:00:00.000Z",
  "pix": {
    "qrcode": "00020101021126360014br.gov.bcb.pix0114+5511999999999520400005303986540510.0058..."
  }
}
```

### Sucesso: Criação de Boleto

```json theme={null}
{
  "id": "payin_12346",
  "externalId": "tx_998878",
  "referenceId": "meu-pedido-1235",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "BOLETO",
  "createdAt": "2026-03-02T12:05:00.000Z",
  "boleto": {
    "barcode": "34191.09008 00000.000004 00000.000006 1 800000000010000",
    "url": "https://adquirente.holdinglegacy.io/boleto/12346"
  }
}
```

### Sucesso: Cartão de Crédito

```json theme={null}
{
  "id": "payin_12347",
  "externalId": "tx_998879",
  "referenceId": "meu-pedido-1236",
  "status": "APPROVED",
  "amount": 10000,
  "paymentMethod": "CREDIT_CARD",
  "createdAt": "2026-03-02T12:10:00.000Z"
}
```

### Pendente: Desafio 3DS (pós-ordem)

Quando a adquirente exige um desafio 3D Secure após a criação do payin, a resposta vem com `status: "PENDING_3DS"` e os campos do desafio. Use o SDK (`client.handlePendingThreeDS()`) para concluir.

```json theme={null}
{
  "id": "payin_12348",
  "externalId": "tx_998880",
  "referenceId": "meu-pedido-1237",
  "status": "PENDING_3DS",
  "amount": 10000,
  "paymentMethod": "CREDIT_CARD",
  "threeDSecurePending": true,
  "threeDSecureSession": "eyJhbGciOiJIUzI1NiJ9...",
  "threeDSecureTransactionId": "05a1f7e4-d8c9-4c5e-b2a3-1f2e3d4c5b6a",
  "threeDSecureSdkUrl": "https://cdn.provider.com/3ds-sdk.min.js",
  "createdAt": "2026-03-02T12:15:00.000Z"
}
```

<Warning>
  `status: "APPROVED"` na resposta do `/payin` **não** garante liquidação. Confirme sempre a venda final via [webhook](/webhooks) ou `GET /payin/{id}`.
</Warning>

### Exemplo de request com cartão tokenizado

```json theme={null}
{
  "paymentMethod": "CREDIT_CARD",
  "amount": 29900,
  "referenceId": "pedido-003",
  "isPhysicalProduct": false,
  "payerIp": "200.100.50.3",
  "customer": { "name": "João Oliveira", "document": "12345678900", "email": "joao@email.com", "phone": "5511988887777" },
  "items": [{ "title": "Plano Mensal", "quantity": 1, "unitPrice": 29900 }],
  "card": {
    "token": "cvt_live_5XY8...",
    "installments": 1,
    "threeDSecure": { "cavv": "jJ2CBDUHAA0CAwECBQYGBAECBAE=", "eci": "05" }
  },
  "antifraud": { "sessionId": "mfp_live_abc123xyz" }
}
```