Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Contrato canonico

Este recurso documenta somente o Checkout P0 de parceiros:
  • POST /v1/checkouts
  • GET /v1/checkouts/:id
  • GET /v1/checkouts
Superficies legadas como /checkout/*, /charges/*, /c/* e /product-checkouts/* nao sao o contrato publico canonico novo para parceiros.

​
Autenticacao canonica

Headers obrigatorios para o recurso:
  • x-client-id
  • x-client-secret
Scopes canonicos:
  • POST /v1/checkouts -> checkout:write
  • GET /v1/checkouts/:id -> checkout:read
  • GET /v1/checkouts -> checkout:read

​
Seguranca adicional no POST

​
Idempotencia

Idempotency-Key e obrigatorio no POST /v1/checkouts. Compatibilidade atual: o backend tambem aceita x-idempotency-key, mas o header canonico para parceiros e Idempotency-Key.

​
Assinatura HMAC

No POST /v1/checkouts, os headers abaixo sao validados:
  • x-turbofy-timestamp
  • x-turbofy-signature
Politica real atual do backend:
  • Em production, a assinatura e obrigatoria.
  • Fora de production, a assinatura pode ser opcional.
Formato do payload assinado: 
{timestamp}.{METHOD}.{path}.{rawBody}

​
Semantica publica obrigatoria

  • bill_* e o identificador publico do checkout.
  • A url retornada aponta para a superficie renderizada atual do frontend (/c/session/:sessionId).
  • Isso nao redefine a semantica publica do recurso /v1/checkouts.

​
Modelo publico de resposta

Envelope padrao do recurso: 
{
  "data": {},
  "success": true,
  "error": null
}
No GET /v1/checkouts, alem do envelope, existe paginacao minima: 
{
  "pagination": {
    "hasMore": false,
    "next": null,
    "before": null
  }
}

​
Mapeamento do DTO publico (backend -> contrato)

Campos retornados no data do checkout:
  • id: bill_${session.id}
  • url: ${FRONTEND_URL}/c/session/${session.id}
  • amount: charge.amountCents
  • paidAmount: charge.amountCents quando charge.paidAt existe, senao null
  • items: session.metadata.publicContract.items
  • status: status publico mapeado de charge.status
  • frequency: sempre ONE_TIME no P0
  • coupons: sempre [] no P0
  • devMode: sempre false no P0
  • customerId: sempre null no P0
  • returnUrl: session.returnUrl
  • completionUrl: session.metadata.publicContract.completionUrl
  • receiptUrl: sempre null no P0
  • metadata: session.metadata.publicContract.publicMetadata ?? {}
  • createdAt: session.createdAt
  • updatedAt: charge.updatedAt

​
Erros tipados do recurso (P0)

HTTPcodeOrigem
400IDEMPOTENCY_KEY_REQUIREDCreate checkout sem idempotencia.
422FREQUENCY_NOT_ENABLED_YETfrequency diferente de ONE_TIME.
422CUSTOMER_NOT_ENABLED_IN_P0customerId enviado no P0.
422COUPONS_NOT_ENABLED_IN_P0coupons enviado no P0.
422COURSE_PRICE_NOT_FOUNDItem referencia CoursePrice inexistente.
422COURSE_PRICE_INACTIVECoursePrice inativo.
422COURSE_PRICE_NOT_OWNED_BY_MERCHANTCoursePrice fora do merchant autenticado.
422COURSE_PRICE_TYPE_NOT_ENABLED_YETCoursePrice nao e do tipo ONE_TIME.
422INVALID_CHECKOUT_IDid/after invalido para formato publico bill_*.
404CHECKOUT_NOT_FOUNDCheckout nao encontrado para o merchant autenticado.

​
Fora de escopo do P0

Itens abaixo nao estao habilitados no P0:
  • frequency = MULTIPLE_PAYMENTS
  • frequency = SUBSCRIPTION
  • customerId funcional
  • coupons funcionais
  • payment-links
  • subscriptions
  • customer prefill
  • recorrencia

​
Proximos passos

  1. Criar checkout
  2. Consultar checkout por id
  3. Listar checkouts
Last modified on May 8, 2026