Skip to main content
POST
/
api
/
checkout
/
sessions
Criar Checkout Session
curl --request POST \
  --url https://garu.com.br/api/checkout/sessions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "product_id": 123,
  "price_id": "<string>",
  "customer": {
    "customer.name": "<string>",
    "customer.email": "<string>",
    "customer.document": "<string>",
    "customer.phone": "<string>",
    "customer.zip_code": "<string>",
    "customer.street": "<string>",
    "customer.number": "<string>",
    "customer.complement": "<string>",
    "customer.neighborhood": "<string>",
    "customer.city": "<string>",
    "customer.state": "<string>"
  },
  "payment_methods": [
    {}
  ],
  "metadata": {},
  "success_url": "<string>",
  "cancel_url": "<string>",
  "client_reference_id": "<string>",
  "affiliate_id": 123,
  "expires_at": "<string>"
}
'
{
  "id": "<string>",
  "status": "<string>",
  "url": "<string>",
  "product_id": 123,
  "price_id": "<string>",
  "customer_email": "<string>",
  "customer_name": "<string>",
  "metadata": {},
  "success_url": "<string>",
  "cancel_url": "<string>",
  "client_reference_id": "<string>",
  "affiliate_id": 123,
  "transaction_id": 123,
  "expires_at": "<string>",
  "completed_at": "<string>",
  "created_at": "<string>"
}

​
Visão Geral

Cria uma nova checkout session e retorna uma URL de pagamento. Para entender quando e como usar Checkout Sessions, consulte o guia completo.

​
Headers

​
Authorization
string
required
Sua chave de API (Bearer YOUR_API_KEY)
​
Content-Type
string
required
application/json
​
X-Idempotency-Key
string
Chave única para evitar requisições duplicadas (válida por 24h)

​
Request Body

​
Campo Obrigatório

​
product_id
integer
required
ID do produto a ser vendido

​
Campos Opcionais

​
price_id
string
ID do preço de assinatura (para pagamentos recorrentes)
​
customer
object
Dados do cliente para pré-preencher o formulário de checkout
​
payment_methods
array
Restringe os métodos de pagamento disponíveis. Valores aceitos: pix, creditCard, boleto
​
metadata
object
Dados personalizados para seu uso (máx 50 chaves, 500 caracteres por valor)
​
success_url
string
URL de redirecionamento após pagamento bem-sucedido (máx 500 caracteres). Use {SESSION_ID} como placeholder.
​
cancel_url
string
URL de redirecionamento se o cliente cancelar (máx 500 caracteres)
​
client_reference_id
string
Seu ID de referência interno (máx 200 caracteres)
​
affiliate_id
integer
ID do afiliado para atribuição de comissão
​
expires_at
string
Data de expiração da session (ISO 8601). Padrão: 24 horas após criação

​
Exemplo de Requisição

curl -X POST https://api.garu.com.br/api/checkout/sessions \
  -H "Authorization: Bearer sk_test_sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order_12345_checkout" \
  -d '{
    "product_id": 123,
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "success_url": "https://seusite.com/sucesso?session_id={SESSION_ID}",
    "cancel_url": "https://seusite.com/cancelado",
    "metadata": {
      "order_id": "12345"
    }
  }'

​
Resposta de Sucesso

​
id
string
Identificador único da session (ex: cs_ABC123xyz)
​
status
string
Status da session: open, complete ou expired
​
url
string
URL do checkout para redirecionar o cliente
​
product_id
integer
ID do produto
​
price_id
string
ID do preço de assinatura (se aplicável)
​
customer_email
string
Email do cliente pré-preenchido
​
customer_name
string
Nome do cliente pré-preenchido
​
metadata
object
Seus metadados personalizados
​
success_url
string
URL de redirecionamento de sucesso
​
cancel_url
string
URL de redirecionamento de cancelamento
​
client_reference_id
string
Seu ID de referência
​
affiliate_id
integer
ID do afiliado
​
transaction_id
integer
ID da transação (preenchido quando completa)
​
expires_at
string
Data de expiração (ISO 8601)
​
completed_at
string
Data de conclusão (ISO 8601, null se não completa)
​
created_at
string
Data de criação (ISO 8601)

​
Exemplo de Resposta (201 Created)

{
  "data": {
    "id": "cs_ABC123xyz",
    "status": "open",
    "url": "https://pay.garu.com.br/pay/session/abc123...",
    "product_id": 123,
    "price_id": null,
    "customer_email": "joao@email.com",
    "customer_name": "João Silva",
    "metadata": {
      "order_id": "12345"
    },
    "success_url": "https://seusite.com/sucesso?session_id={SESSION_ID}",
    "cancel_url": "https://seusite.com/cancelado",
    "client_reference_id": null,
    "affiliate_id": null,
    "transaction_id": null,
    "expires_at": "2025-01-20T12:00:00.000Z",
    "completed_at": null,
    "created_at": "2025-01-19T12:00:00.000Z"
  }
}

​
Erros Comuns

{
  "statusCode": 400,
  "message": "product_id is required",
  "error": "Bad Request"
}
Solução: Inclua o campo product_id na requisição.
{
  "statusCode": 400,
  "message": "Invalid payment method",
  "error": "Bad Request"
}
Solução: Use apenas valores válidos em payment_methods: pix, creditCard, boleto.
{
  "statusCode": 401,
  "message": "Unauthorized"
}
Solução: Verifique se o header Authorization está correto.
{
  "statusCode": 404,
  "message": "Product not found"
}
Solução: Verifique se o product_id existe e pertence ao seu vendedor.
{
  "statusCode": 429,
  "message": "Too Many Requests"
}
Solução: Aguarde antes de fazer novas requisições. Limite: 100 requisições por minuto.

​
Próximos Passos

Guia de Checkout Sessions

Entenda quando e como usar

Listar Sessions

Consulte suas sessions