Links de pagamento

Um link de pagamento é uma página de checkout hospedada pela OrcaPay: você cria o link, envia ao cliente e ele escolhe pagar com Pix ou cartão. Ideal para vendas sem integração de checkout própria.

Todas as operações exigem o escopo payments:link.

Criando um link

curl -X POST https://api.orcapay.com.br/payments/links \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "description": "Consulta - Julho/2026",
    "allowPix": true,
    "allowCard": true,
    "maxInstallments": 3,
    "reusable": false,
    "expiresAt": "2026-07-25T23:59:59Z",
    "externalId": "fatura-2026-07",
    "callbackUrl": "https://minhaloja.com.br/obrigado",
    "customerName": "Maria Silva",
    "customerEmail": "maria@exemplo.com.br",
    "customerDocument": "12345678900",
    "items": [
      { "name": "Consulta", "quantity": 1, "totalAmount": 250.00 }
    ]
  }'

A resposta 201 inclui a url pronta para compartilhar com o cliente.

Campos importantes:

• allowPix / allowCard — métodos de pagamento aceitos no checkout (padrão: ambos).
• maxInstallments — máximo de parcelas no cartão (padrão 1).
• reusable — quando true, o link aceita múltiplos pagamentos; quando false, é desativado após o primeiro pagamento.
• expiresAt — data opcional de expiração do link.
• callbackUrl — URL para onde o cliente é redirecionado após pagar.
• customerName / customerEmail / customerDocument — quando informados, pré-preenchem os dados no checkout.

Status do link

Status	Significado
ACTIVE	Disponível para pagamento
PAID	Pago (links não reutilizáveis)
EXPIRED	Expirou sem pagamento
CANCELLED	Cancelado

Quando um link é pago, o campo paymentId da resposta aponta para o pagamento gerado, e os webhooks de pagamento são disparados normalmente.

Consultando e cancelando

curl https://api.orcapay.com.br/payments/links \
  -H "X-Api-Key: op_live_..."

curl https://api.orcapay.com.br/payments/links/{id} \
  -H "X-Api-Key: op_live_..."

curl -X POST https://api.orcapay.com.br/payments/links/{id}/cancel \
  -H "X-Api-Key: op_live_..."

A listagem é paginada no mesmo formato da listagem de pagamentos.