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>"
}Checkout Sessions
Criar Checkout Session
Crie links de pagamento programaticamente com dados do cliente pré-preenchidos
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
string
required
Sua chave de API (
Bearer YOUR_API_KEY)string
required
application/jsonstring
Chave única para evitar requisições duplicadas (válida por 24h)
Request Body
Campo Obrigatório
integer
required
ID do produto a ser vendido
Campos Opcionais
string
ID do preço de assinatura (para pagamentos recorrentes)
object
Dados do cliente para pré-preencher o formulário de checkout
Show Campos do customer
Show Campos do customer
string
Nome completo do cliente (máx 255 caracteres)
string
Email do cliente (máx 255 caracteres)
string
CPF ou CNPJ (máx 14 caracteres, apenas números)
string
Telefone (máx 11 caracteres, apenas números)
string
CEP (máx 8 caracteres, apenas números)
string
Rua (máx 255 caracteres)
string
Número do endereço (máx 20 caracteres)
string
Complemento (máx 255 caracteres)
string
Bairro (máx 100 caracteres)
string
Cidade (máx 100 caracteres)
string
Estado (2 letras, ex: “SP”)
array
Restringe os métodos de pagamento disponíveis. Valores aceitos:
pix, creditCard, boletoobject
Dados personalizados para seu uso (máx 50 chaves, 500 caracteres por valor)
string
URL de redirecionamento após pagamento bem-sucedido (máx 500 caracteres). Use
{SESSION_ID} como placeholder.string
URL de redirecionamento se o cliente cancelar (máx 500 caracteres)
string
Seu ID de referência interno (máx 200 caracteres)
integer
ID do afiliado para atribuição de comissão
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)string
Status da session:
open, complete ou expiredstring
URL do checkout para redirecionar o cliente
integer
ID do produto
string
ID do preço de assinatura (se aplicável)
string
Email do cliente pré-preenchido
string
Nome do cliente pré-preenchido
object
Seus metadados personalizados
string
URL de redirecionamento de sucesso
string
URL de redirecionamento de cancelamento
string
Seu ID de referência
integer
ID do afiliado
integer
ID da transação (preenchido quando completa)
string
Data de expiração (ISO 8601)
string
Data de conclusão (ISO 8601, null se não completa)
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
400 - product_id obrigatório
{
"statusCode": 400,
"message": "product_id is required",
"error": "Bad Request"
}
product_id na requisição.400 - Método de pagamento inválido
400 - Método de pagamento inválido
{
"statusCode": 400,
"message": "Invalid payment method",
"error": "Bad Request"
}
payment_methods: pix, creditCard, boleto.401 - Não autorizado
401 - Não autorizado
{
"statusCode": 401,
"message": "Unauthorized"
}
Authorization está correto.404 - Produto não encontrado
404 - Produto não encontrado
{
"statusCode": 404,
"message": "Product not found"
}
product_id existe e pertence ao seu vendedor.429 - Rate limit excedido
429 - Rate limit excedido
{
"statusCode": 429,
"message": "Too Many Requests"
}
Próximos Passos
Guia de Checkout Sessions
Entenda quando e como usar
Listar Sessions
Consulte suas sessions
Was this page helpful?