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.

​
Endpoint

POST /v1/checkouts

​
Headers

Obrigatorios:
  • x-client-id
  • x-client-secret
  • Idempotency-Key
Requisitados para assinatura (obrigatorios em production):
  • x-turbofy-timestamp
  • x-turbofy-signature
Scope obrigatorio: checkout:write.

​
Request

{
  "items": [
    {
      "id": "price_pro",
      "quantity": 1
    }
  ],
  "methods": ["PIX", "CARD"],
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "externalId": "pedido-123",
  "metadata": {
    "source": "landing-page"
  },
  "frequency": "ONE_TIME"
}

​
Regras do payload

  • items e obrigatorio, com minimo de 1 item.
  • items[].id e obrigatorio.
  • items[].quantity deve ser inteiro >= 1.
  • methods e opcional (PIX, CARD).
  • metadata aceita apenas valores string | number | boolean | null.
  • frequency aceita somente ONE_TIME no P0 (se omitido, o backend assume ONE_TIME).
  • customerId e aceito no schema, mas bloqueado no P0 com 422 CUSTOMER_NOT_ENABLED_IN_P0.
  • coupons e aceito no schema, mas bloqueado no P0 com 422 COUPONS_NOT_ENABLED_IN_P0.

​
Regras de negocio

O backend resolve os itens por CoursePriceRepository e calcula o valor internamente: amount = soma(coursePrice.amountCents * quantity) Validacoes aplicadas no backend:
  • CoursePrice existe.
  • CoursePrice esta ativo.
  • CoursePrice pertence ao merchant da credencial.
  • CoursePrice e do tipo ONE_TIME.

​
Response 201

{
  "data": {
    "id": "bill_session_abc123",
    "externalId": "pedido-123",
    "url": "https://checkout.turbofy.com.br/c/session/session_abc123",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "price_pro",
        "quantity": 1
      }
    ],
    "status": "PENDING",
    "frequency": "ONE_TIME",
    "coupons": [],
    "devMode": false,
    "customerId": null,
    "returnUrl": "https://seusite.com/voltar",
    "completionUrl": "https://seusite.com/sucesso",
    "receiptUrl": null,
    "metadata": {
      "source": "landing-page"
    },
    "createdAt": "2026-04-13T00:00:00.000Z",
    "updatedAt": "2026-04-13T00:00:00.000Z"
  },
  "success": true,
  "error": null
}

​
Idempotencia

Se o mesmo Idempotency-Key for reenviado para o mesmo merchant com o mesmo payload efetivo, a rota retorna o mesmo checkout.

​
Erros do recurso

HTTPcodeQuando ocorre
400IDEMPOTENCY_KEY_REQUIREDHeader de idempotencia ausente.
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 nao pertence ao merchant autenticado.
422COURSE_PRICE_TYPE_NOT_ENABLED_YETCoursePrice nao e ONE_TIME.

​
Erros de camada de seguranca

Podem ser retornados antes do handler do recurso:
  • 401 CREDENTIALS_REQUIRED
  • 401 INVALID_CREDENTIALS
  • 403 SCOPE_REQUIRED
  • 401 INVALID_SIGNATURE

​
Fora de escopo no create P0

  • frequency = MULTIPLE_PAYMENTS
  • frequency = SUBSCRIPTION
  • customerId funcional
  • coupons funcionais
Last modified on May 8, 2026