Referência

Crie um checkout

O Checkout é a página segura onde o cliente finaliza o pagamento. Você envia os itens; a API devolve uma URL para redirecionar.

Criar checkout

Use /checkouts/create. O total é calculado a partir dos itens.

Campos obrigatórios

Só items é obrigatório (lista com id do produto e quantity).

O parâmetro frequency define o tipo de cobrança:

Valor	Descrição
ONE_TIME	Pagamento único (padrão). Não é necessário enviar ao criar um checkout.
MULTIPLE_PAYMENTS	Link de pagamento onde é possível pagar mais de uma vez. Veja Links de pagamento.
SUBSCRIPTION	Assinatura recorrente. Veja Assinaturas.

Exemplo (pagamento único — frequency não precisa ser enviado):

POST /checkouts/create
{
  "items": [                                    // obrigatório
    {
      "id": "prod_pro",                         // ID do produto na sua loja
      "quantity": 1                             // quantidade
    }
  ],
  "customerId": "cust_abc123xyz",              // opcional - ID do cliente já cadastrado
  "externalId": "pedido-123",                  // opcional - ID no seu sistema
  "returnUrl": "https://seusite.com/voltar",   // opcional - URL de retorno
  "completionUrl": "https://seusite.com/sucesso", // opcional - URL após pagamento
  "methods": ["PIX", "CARD"],                  // opcional - métodos de pagamento (padrão: PIX e CARD)
  "metadata": {                                 // opcional - dados adicionais
    "customField": "value"
  }
}

Resposta:

{
  "data": {
    "id": "bill_abc123xyz",
    "externalId": "pedido-123",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "prod_456",
        "quantity": 2
      }
    ],
    "status": "PENDING",
    "frequency": "ONE_TIME",
    "coupons": [],
    "devMode": false,
    "customerId": null,
    "returnUrl": null,
    "completionUrl": null,
    "receiptUrl": null,
    "metadata": {},
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}

Use a url retornada para levar o cliente ao checkout e concluir o pagamento.

Upsell

Você pode oferecer um produto adicional ao cliente após a conclusão do pagamento usando o campo upSellProductId. O produto é apresentado como uma oferta na página de confirmação — ideal para aumentar o ticket médio sem criar um novo checkout.

Regras do produto de upsell

O produto referenciado em upSellProductId precisa estar com status: ACTIVE e não pode ter cycle (deve ser avulso, sem assinatura).

Exemplo:

POST /checkouts/create
{
  "items": [
    { "id": "prod_principal", "quantity": 1 }
  ],
  "upSellProductId": "prod_bump456xyz"
}

Resposta (com upsell):

{
  "data": {
    "id": "bill_abc123xyz",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "upSellProductId": "prod_bump456xyz",
    "status": "PENDING",
    "frequency": "ONE_TIME",
    ...
  },
  "success": true,
  "error": null
}

O upSellProductId é retornado na resposta e ficará null caso nenhum produto de upsell tenha sido vinculado ao checkout.

Multa e juros no boleto

Para cobranças com methods: ["BOLETO"], você pode configurar juros por atraso (interest) e multa por atraso (fine) que serão aplicados se o cliente pagar após a data de vencimento. Ambos os campos são opcionais e independentes — pode-se enviar só interest, só fine, ambos ou nenhum.

Aplicação dos campos

Os campos só têm efeito quando o método de pagamento é BOLETO. Para PIX ou CARD são ignorados silenciosamente.

interest — juros por atraso / late interest

Campo	Tipo	Descrição
value	integer ≥ 0	Percentual de juros ao mês, em centésimos de percentual. 100 = 1% ao mês, 250 = 2,5% ao mês. Quando 0 ou omitido, não há juros.

Os juros seguem o padrão percentual ao mês, calculados pro rata die após o vencimento.

EN: interest.value is an integer in hundredths of a percent representing the monthly late interest rate (100 = 1%/month, 250 = 2.5%/month). It accrues pro rata die after the due date. Omit or use 0 to disable.

fine — multa por atraso / late fine

Campo	Tipo	Descrição
value	integer ≥ 0	Quando type = "PERCENTAGE": centésimos de percentual (200 = 2%). Quando type = "FIXED": valor em centavos (1000 = R$ 10,00). Quando 0 ou omitido, sem multa.
type	"PERCENTAGE" | "FIXED"	PERCENTAGE aplica percentual sobre o valor do boleto. FIXED aplica um valor fixo em centavos.

A multa é uma cobrança única aplicada uma vez após o vencimento.

EN: fine is a one-time charge added after the due date. With type: "PERCENTAGE", value is in hundredths of a percent (200 = 2%). With type: "FIXED", value is in cents (1000 = R$ 10.00).

Unidades resumidas / unit cheat sheet: interest.value e fine.value (quando type = "PERCENTAGE") são sempre em centésimos de percentual — 100 = 1%. fine.value (quando type = "FIXED") e amount seguem o restante da API e são em centavos — 1000 = R$ 10,00.

Exemplo — juros de 1% ao mês + multa de 2%:

POST /checkouts/create
{
  "methods": ["BOLETO"],
  "items": [
    { "id": "prod_abc123", "quantity": 1 }
  ],
  "interest": { "value": 100 },
  "fine": { "value": 200, "type": "PERCENTAGE" }
}

Exemplo — só multa fixa de R$ 10,00:

POST /checkouts/create
{
  "methods": ["BOLETO"],
  "items": [
    { "id": "prod_abc123", "quantity": 1 }
  ],
  "fine": { "value": 1000, "type": "FIXED" }
}

Resposta:

Os mesmos objetos interest e fine constam na resposta de GET /checkouts/get e GET /checkouts/list, ou ficam null quando nenhum dos campos foi configurado.

{
  "data": {
    "id": "bill_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "interest": { "value": 100 },
    "fine": { "value": 200, "type": "PERCENTAGE" },
    ...
  },
  "success": true,
  "error": null
}