Greenn — Payment Integration API (1.5.1-rc.1)

Antes de integrar, a Greenn entrega as suas credenciais:

Uma venda completa percorre estes passos:

1 — Colete o fingerprint no front do seu checkout: a coleta (fp.get()) gera um requestId (ver Fingerprint abaixo).

2 — Chame o priority (POST /api/checkout/priority) com os dados de pagamento e o header X-Fingerprint-RID. O cartão bruto trafega somente aqui — ele é tokenizado e você recebe { gateway, cards[].id, attempts, parent_id }.

3 — Colete um NOVO fingerprint. Cada chamada exige um requestId próprio — nunca reutilize o do priority.

4 — Chame o payment v2 (POST /api/v2/payment) repassando o retorno do priority + os dados da venda (produto, oferta, comprador, afiliados). A Greenn valida tudo de forma atômica, registra o que ainda não existir (produto, oferta, vínculos), cria a(s) venda(s) e processa a cobrança.

5 — Trate a resposta, conforme o método:

• Cartão → status: paid na hora, ou recusa de cobrança (PAYMENT_DECLINED — ver Retentativa de cobrança);
• PIX → status: waiting_payment + qrcode para o comprador pagar;
• Boleto → status: waiting_payment + boleto_url / boleto_barcode.

6 — Acompanhe os webhooks. Quando a venda é processada ou muda de status (ex.: PIX pago), a Greenn notifica a URL enviada em external_callback_url. Guarde o nano_id de cada venda — é a sua referência nas notificações (webhooks) e o mesmo id curto exibido no painel da Greenn. O payload, os eventos e as regras de entrega estão na seção Webhooks desta doc.

A coleta antifraude usa o Fingerprint (agente JavaScript). As duas chamadas — priority e payment v2 — exigem o identificador gerado pela coleta.

1 — Obtenha a public API key, fornecida pela Greenn no onboarding.

2 — Instale o agente JS no front do seu checkout (guia oficial). Integração mínima:

// carrega o agente (uma vez, no load da página)
const fpPromise = import('https://fpjscdn.net/v3/SUA_PUBLIC_API_KEY')
  .then(FingerprintJS => FingerprintJS.load());

// antes de CADA chamada (priority e payment v2), faça uma coleta NOVA
const { requestId } = await (await fpPromise).get();

3 — Envie o requestId no header X-Fingerprint-RID das duas chamadas. ⚠️ Cada chamada exige uma coleta nova: um requestId para o priority e outro para o payment v2 — nunca reutilize um requestId já enviado (cada um vale para uma única requisição, e expira — colete imediatamente antes do envio).

Ausente/inválido/reutilizado → a requisição é recusada com 401 (PARTNER_FINGERPRINT_INVALID).

O campo attempts. O priority devolve uma lista de identificadores opacos que representa o andamento daquela cobrança. Trate como um token — não interprete o conteúdo, apenas guarde e devolva ao reprocessar.

Como reprocessar uma recusa recuperável:

1. A resposta de recusa do payment v2 veio com retryable: true;
2. Reenvie o priority com o mesmo attempts preenchido, junto dos dados de pagamento;
3. Siga normalmente para o payment v2 com o novo retorno.

Se retryable: false (irreversível), reenviar não resolve: colete novos dados de pagamento e inicie um priority novo, com attempts vazio.

• Sem busca externa: dado obrigatório que não vem no body → erro 422.
• Seller já existe na Greenn: seller_id carrega o external ID Greenn do usuário vendedor (UUID — o usuário consulta no painel da Greenn e informa à integração; a mesma referência vale pra afiliados/co-sellers em affiliates[].external_id). Sem conta Greenn correspondente → 422 (o fluxo não cria usuários).
• Produto imutável: product_id (sua referência) existente → usa (não recadastra); não existe + dados de cadastro → cadastra; não existe + sem dados → 422. Valor diferente do registrado → 422 (a Greenn nunca edita produto de parceiro).
• Oferta: aninhada no produto (offer{}), pode vir vazia → usa a oferta default (= valor do produto). offer_id existente → valida amount; não bate → 422.
• Order bump: products[0] = produto principal; demais itens = bumps da mesma compra. Validação atômica: todas as validações de todos os produtos rodam ANTES de qualquer cobrança — qualquer falha → 422 e nada é cobrado.
• Cartão só tokenizado: o payment v2 aceita apenas os tokens do priority. Qualquer dado bruto de cartão (number/cvv/...) no body → 422 imediato.
• Métodos de pagamento: cartão de crédito (CREDIT_CARD), dois cartões (TWO_CREDIT_CARDS), boleto (BOLETO) e PIX (PIX).
• Parcelamento: em até 12x, disponível no momento somente para cartão e dois cartões (installments de 1 a 12). Boleto e PIX são à vista.
• external_callback_url: deve ser uma URL https pública do seu sistema (endereços internos/IP literais privados são recusados com 422 INVALID_CALLBACK_URL). É para ela que os webhooks de saída são enviados.
• Identificador da venda: cada venda devolve um nano_id (id curto público, o mesmo exibido no painel da Greenn) — é a referência única da venda na integração e nos webhooks.

Todos os erros do payment v2 (401/403/422/429) voltam no envelope padronizado:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product could not be resolved.",
    "status": 422,
    "request_id": "...",
    "errors": [ { "field": "products.0.product_id", "message": "..." } ]
  }
}

code é estável (use para tratamento programático); message é legível e pode mudar. Veja os códigos por resposta na operação.

Seleção de gateway + tokenização de cartão (priority)

Processamento de pagamento da integração (payment v2)

Notificações de saída enviadas pela Greenn para a sua external_callback_url

Consulta pré-pagamento da tabela de parcelamento (somente leitura)