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

# Entrega automática

> Como buscar a chave, a conta ou o link que o comprador recebeu.

Quando a cobrança está amarrada a um produto da loja, o conteúdo (chave, conta, link) é
liberado no instante em que o pagamento confirma. `GET /v1/deliveries/{paymentId}` é como
você lê esse conteúdo do seu lado, para reenviar por e-mail, mostrar numa tela de pedido ou
registrar no seu banco.

## Amarrando o produto

A ligação é feita na **criação** da cobrança, pelo campo `supplier`. Ele funciona igual em
`POST /v1/charges` e em `POST /v1/payments`:

```bash theme={null}
curl -X POST https://api.purin.cash/v1/charges \
  -H "Authorization: Bearer $PURINCASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "valueCents": 1990,
    "description": "Conta Premium",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "supplier": {
      "productId": "prod_aim_assist",
      "variationIndex": 0
    }
  }'
```

**supplier.productId** `string`

ID **público** do produto da loja, no formato `prod_xxx`. Você pega no painel, no
produto. Não é o `_id` que aparece em `GET /v1/store/products`, e não é o `productId` de
produto de cobrança.

**supplier.variationIndex** `integer` (default: 0)

Qual variação, pela posição na lista: `0` é a primeira, `1` a segunda. Índice que não
existe devolve `400` dizendo quantas variações o produto tem.

> [!WARNING]
>
> O `supplier` **não** define o preço. Quem manda no valor continua sendo `valueCents` (ou
> o produto de cobrança, se você usou `productId`). Amarrar um produto de R\$ 50 numa
> cobrança de R\$ 5 não corrige o valor: gera uma cobrança de R\$ 5.

Quando a variação vem de fornecedor externo, a API valida duas coisas na criação e recusa
na hora se algo não fecha:

| Código | Motivo |
| - | - |
| `403` | Você não tem acesso aprovado àquele fornecedor |
| `400` | O valor da cobrança é menor que o custo do fornecedor. O erro diz o custo exato |

Isso evita vender abaixo do custo por engano, que é um erro que só apareceria no
fechamento do mês.

> [!NOTE]
>
> O fornecedor externo só entra em cobrança PIX: é no pagamento PIX que o item é buscado nele
> e a divisão é feita. Em `ltc` ou `btc` a cobrança é criada normalmente, mas sem o
> fornecedor: o item dele não é entregue, não há divisão, e a resposta traz o aviso em
> `warnings`. Para o fornecedor entregar, use `paymentMethod: "pix"` (ou deixe o campo de fora).

## Lendo o que foi entregue

```bash theme={null}
curl https://api.purin.cash/v1/deliveries/psa_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $PURINCASH_KEY"
```

```json theme={null}
{
  "paymentId": "psa_a1b2c3d4e5f6",
  "status": "paid",
  "amountCents": 4990,
  "paidAt": "2026-03-18T12:05:00.000Z",
  "deliveredContent": "LICENSE-KEY-ABC-123",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "externalId": "user_42"
  }
}
```

Aceita tanto ID de pagamento (`psa_`) quanto de cobrança (`psc_`).

## Quando `deliveredContent` vem `null`

> [accordion] O pagamento ainda não foi confirmado
>
> Enquanto o `status` for `pending`, não existe entrega. Espere o webhook.

> [accordion] O produto tem entrega manual
>
> Nesse caso o conteúdo não é gerado automaticamente, e não há nada para esta rota
> devolver.

> [accordion] A cobrança não tinha produto vinculado
>
> Sem `supplier` na criação, não existe o que entregar. É só um valor.
>
> Esse é o caso mais comum de "criei tudo certo e `deliveredContent` vem `null`": o
> vínculo precisa ser feito na criação, não dá pra amarrar depois.

Nenhum desses casos é erro: a resposta é `200` com `deliveredContent: null`. `404` só
acontece quando o pagamento não existe ou não é da sua conta.

## O conteúdo também chega no webhook

O evento `payment.paid` traz `deliveredContent` quando há entrega automática. Se você já
processa o webhook, normalmente não precisa chamar esta rota.

Ela é útil em dois momentos: quando o cliente pede a chave de novo e você não quer guardar
o conteúdo no seu banco, e quando você está reconciliando um pagamento antigo cujo webhook
se perdeu.

> [!WARNING]
>
> `deliveredContent` costuma ser exatamente o que o cliente comprou: licença, credencial
> ou link. Trate como dado sensível, não jogue em log e não exponha em endpoint público
> sem autenticação.


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