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>"
}
'

import requests

url = "https://garu.com.br/api/checkout/sessions"

payload = {
    "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>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://garu.com.br/api/checkout/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://garu.com.br/api/checkout/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://garu.com.br/api/checkout/sessions"

	payload := strings.NewReader("{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://garu.com.br/api/checkout/sessions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://garu.com.br/api/checkout/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
}

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>"
}
'

import requests

url = "https://garu.com.br/api/checkout/sessions"

payload = {
    "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>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://garu.com.br/api/checkout/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://garu.com.br/api/checkout/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://garu.com.br/api/checkout/sessions"

	payload := strings.NewReader("{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://garu.com.br/api/checkout/sessions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://garu.com.br/api/checkout/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"product_id\": 123,\n  \"price_id\": \"<string>\",\n  \"customer\": {\n    \"customer.name\": \"<string>\",\n    \"customer.email\": \"<string>\",\n    \"customer.document\": \"<string>\",\n    \"customer.phone\": \"<string>\",\n    \"customer.zip_code\": \"<string>\",\n    \"customer.street\": \"<string>\",\n    \"customer.number\": \"<string>\",\n    \"customer.complement\": \"<string>\",\n    \"customer.neighborhood\": \"<string>\",\n    \"customer.city\": \"<string>\",\n    \"customer.state\": \"<string>\"\n  },\n  \"payment_methods\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"success_url\": \"<string>\",\n  \"cancel_url\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"affiliate_id\": 123,\n  \"expires_at\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

Show Campos do customer

customer.name

string

Nome completo do cliente (máx 255 caracteres)

customer.email

string

Email do cliente (máx 255 caracteres)

customer.document

string

CPF ou CNPJ (máx 14 caracteres, apenas números)

customer.phone

string

Telefone (máx 11 caracteres, apenas números)

customer.zip_code

string

CEP (máx 8 caracteres, apenas números)

customer.street

string

Rua (máx 255 caracteres)

customer.number

string

Número do endereço (máx 20 caracteres)

customer.complement

string

Complemento (máx 255 caracteres)

customer.neighborhood

string

Bairro (máx 100 caracteres)

customer.city

string

Cidade (máx 100 caracteres)

customer.state

string

Estado (2 letras, ex: “SP”)

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"
    }
  }'

const response = await fetch('https://api.garu.com.br/api/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.GARU_API_KEY,
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'order_' + Date.now()
  },
  body: JSON.stringify({
    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' }
  })
});

const { data } = await response.json();
// Redirecionar cliente para data.url

import requests
import os

response = requests.post(
    'https://api.garu.com.br/api/checkout/sessions',
    headers={
        'Authorization': 'Bearer ' + os.environ['GARU_API_KEY'],
        'X-Idempotency-Key': 'order_12345_checkout'
    },
    json={
        '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'}
    }
)

data = response.json()['data']
# Redirecionar cliente para data['url']

Resposta de Sucesso

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

400 - product_id obrigatório

{
  "statusCode": 400,
  "message": "product_id is required",
  "error": "Bad Request"
}

Solução: Inclua o campo product_id na requisição.

400 - Método de pagamento inválido

{
  "statusCode": 400,
  "message": "Invalid payment method",
  "error": "Bad Request"
}

Solução: Use apenas valores válidos em payment_methods: pix, creditCard, boleto.

401 - Não autorizado

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Solução: Verifique se o header Authorization está correto.

404 - Produto não encontrado

{
  "statusCode": 404,
  "message": "Product not found"
}

Solução: Verifique se o product_id existe e pertence ao seu vendedor.

429 - Rate limit excedido

{
  "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

Portal customizado por produto (B2B2C)Listar Checkout Sessions

​Visão Geral

​Headers

​Request Body

​Campo Obrigatório

​Campos Opcionais

​Exemplo de Requisição

​Resposta de Sucesso

​Exemplo de Resposta (201 Created)

​Erros Comuns

​Próximos Passos

Guia de Checkout Sessions

Listar Sessions

Visão Geral

Headers

Request Body

Campo Obrigatório

Campos Opcionais

Exemplo de Requisição

Resposta de Sucesso

Exemplo de Resposta (201 Created)

Erros Comuns

Próximos Passos