Pagamentos com cartão

Aceite Visa, Mastercard, American Express, Elo, Hipercard e as outras grandes bandeiras por uma página de pagamento hospedada pela Liqfy — nenhum dado de cartão passa pelos seus servidores, e o 3D Secure é tratado automaticamente.

#O fluxo, de relance

1. POST /v1/payments  ──────▶  a Liqfy devolve o pagamento: id, status WAITING_PAYMENT, cardRedirectUrl + checkoutUrl
2. Redirecione o cliente (ou abra num iframe) para o cardRedirectUrl
3. O cliente digita os dados do cartão e conclui o desafio 3DS na página segura da Liqfy
4. O cliente volta para o seu returnUrl (com sucesso ou com falha)
5. O webhook charge.paid (ou charge.failed) confirma o resultado — confie no webhook, não no redirect

Por que um redirect? Ele mantém os dados do portador do cartão totalmente fora da sua infraestrutura. A sua aplicação — backend ou frontend — nunca vê PAN, CVV nem validade. O processador da Liqfy cuida do 3DS, da tokenização e da análise antifraude do nosso lado.

#1. Criar a cobrança

Endpoint POST /v1/payments

curl -X POST https://api.liqfy.com.br/v1/payments \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Idempotency-Key: ORD-9821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8990,
    "currency": "EUR",
    "paymentMethods": ["CREDIT_CARD"],
    "customerName": "João Costa",
    "customerEmail": "joao@example.com",
    "customerPhone": "+351912345678",
    "returnUrl": "https://shop.example.com/orders/9821/return",
    "cancelUrl": "https://shop.example.com/cart",
    "metadata": { "orderId": "ORD-9821" }
  }'

Idempotência. O POST /v1/payments aceita o cabeçalho Idempotency-Key (preferido) ou o campo de corpo idempotencyKey como alternativa quando o cabeçalho está ausente; envie pelo menos um. Se enviar os dois, eles precisam ser iguais — valores divergentes são 400, e nenhum dos dois também é 400 nesta rota. Qualquer string não vazia (espaços nas pontas são removidos), com escopo por lojista ((merchant, key)): repetir a mesma chave e o mesmo corpo devolve a resposta guardada; a mesma chave com corpo diferente é 409 (idempotency_key_reused). O cabeçalho Idempotency-Replayed não é emitido nesta rota — não monte lógica de retry em cima dele.

Resposta 201 Created — a resposta de criação já traz os artefatos do método (aqui o cardRedirectUrl) e o checkoutUrl; não é preciso um GET depois para vê-los.

{
  "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "status": "WAITING_PAYMENT",
  "amount": 8990,
  "currency": "EUR",
  "paymentMethods": ["CREDIT_CARD"],
  "customerName": "João Costa",
  "customerEmail": "joao@example.com",
  "customerPhone": "+351912345678",
  "cardRedirectUrl": "https://checkout.liqfy.com.br/c/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "checkoutUrl": "https://checkout.liqfy.com.br/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "createdAt": "2026-04-25T15:50:11.000Z"
}

O checkoutUrl só existe na criação e na consulta — nas linhas da listagem e na resposta do cancelamento ele não vem.

#Erros na criação

Os erros 4xx do lado do provedor mantêm o status HTTP devolvido pela camada de roteamento. As mensagens são neutras de propósito — nunca citam o provedor nem os códigos internos dele; informe o request id ao suporte se precisar do detalhe.

Com o SDK oficial (o mesmo pacote neutro para qualquer marca — configure-o com https://api.liqfy.com.br):

payments.list (GET /v1/payments) devolve o envelope de página { data, total, page, limit }. Parâmetros de query: page (padrão 1), limit (padrão 20, máximo 100), status, currency, startDate / endDate (data-hora ISO-8601), source (API, PANEL, MANUAL, INDEFINIDO), sortBy, sortOrder (asc / desc).

#2. Redirecionar o cliente

O cardRedirectUrl vem na resposta de criação (e em todo GET /v1/payments/{id}), então dá para redirecionar na hora:

curl https://api.liqfy.com.br/v1/payments/b2c3d4e5-f6a7-4890-9bcd-ef0123456789 \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "status": "WAITING_PAYMENT",
  "amount": 8990,
  "currency": "EUR",
  "cardRedirectUrl": "https://checkout.liqfy.com.br/c/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "createdAt": "2026-04-25T15:50:11.000Z"
}

Mande o cliente para o cardRedirectUrl:

<a href="{{ cardRedirectUrl }}">Pagar com cartão</a>

Ou faça um 303 See Other no servidor:

res.redirect(303, transaction.cardRedirectUrl);

Quando o cliente conclui o fluxo (ou desiste), ele volta para o returnUrl que você informou (o checkout hospedado lê o mesmo redirect em metadata.returnUrl) — com ?transactionId=...&status=... no final. Não confie nesses parâmetros de query. Eles são só informativos — espere o webhook antes de liberar o pedido.

#3. Confirmar pelo webhook

{
  "id": "evt_00000000000000000000000000000001",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-04-25T15:52:34.000Z",
  "data": {
    "object": {
      "id": "ch_b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
      "object": "charge",
      "status": "paid",
      "amount": 8990,
      "currency": "EUR",
      "payment_method": "card",
      "settlement": {}
    }
  }
}

O status público da cobrança é paid para pagamentos com cartão aprovados. O vocabulário público de status é pending, processing, paid, failed, expired, cancelled, refunded, disputed.

Recusas chegam como charge.failed; expiração usa preferencialmente charge.expired. Leia data.object.status para o resultado público. O evento não expõe os motivos de recusa do emissor.

#Ciclo de vida

WAITING_PAYMENT  ──▶  PROCESSING  ──▶  APPROVED    ✓ libere o pedido
                                  ──▶  REFUSED     o emissor recusou
                                  ──▶  CANCELLED   o cliente desistiu
                                  ──▶  EXPIRED     o link de redirect venceu (24h)

Depois da liquidação (D+1 a D+30, conforme a bandeira e o seu contrato), você também pode ver:

APPROVED  ──▶  CHARGEBACK   o emissor abriu um chargeback
APPROVED  ──▶  DISPUTE      o portador do cartão abriu uma disputa
APPROVED  ──▶  REFUNDED     você (ou a Liqfy) fez um reembolso

Cada um dispara um webhook, para você sincronizar o estado do pedido.

#Outras operações sobre o pagamento

#Cartões de teste

No sandbox, a página de redirect aceita estes números determinísticos (qualquer validade futura, qualquer CVV):

Cobranças de sandbox rodam no simulador: nunca creditam a sua carteira e ficam fora dos números de volume, receita e métricas (continuam aparecendo nas listas e no detalhe da cobrança). Use POST /v1/payments/{id}/confirm-sandbox para disparar o webhook de conclusão de ponta a ponta com uma chave de teste.

Veja a lista completa em Sandbox.

#Perguntas frequentes

P: Dá para manter o cliente no meu domínio? R: Na fase 2 vamos lançar um widget incorporável (iframe + tokenizador) que mantém a sua marca e continua deixando os dados do portador do cartão fora da sua infraestrutura. Por enquanto: redirect hospedado.

P: Vocês aceitam cartão salvo? R: Sim, mas isso exige que o seu lado tenha a própria certificação de conformidade de segurança de dados de cartão. Escreva para suporte@liqfy.com.br para habilitar a Vault API.

P: Qual versão do 3DS é usada? R: 3DS 2.x, com fluxo sem fricção quando o emissor permite. A Autenticação Forte do Cliente (SCA) é obrigatória em EUR — isso é imposto no servidor.

P: E reembolso? R: Reembolso hoje é solicitado pelo painel administrativo, total ou parcial — a API não expõe um endpoint de reembolso utilizável pelo lojista: POST /v1/payments/{id}/refund com chave de API devolve 403 REFUND_ADMIN_ONLY. O histórico de reembolsos continua disponível em GET /v1/payments/{id}/refunds.

P: Meu cliente foi cobrado, mas o webhook nunca chegou. R: Confira GET /v1/webhooks/deliveries — provavelmente tentamos e o seu endpoint respondeu algo fora de 2xx. Fazemos até 15 retentativas. Depois disso, use POST /v1/payments/{id}/resend-webhook ou fale com o suporte para reenviar.

#Próximo

→ MB WAY · Multibanco · Referência da API