Criar Cobrança
curl --request POST \
--url https://garu.com.br/api/v1/charges \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>' \
--data '
{
"productId": "<string>",
"paymentMethod": "<string>",
"customer": {
"customer.name": "<string>",
"customer.email": "<string>",
"customer.document": "<string>",
"customer.phone": "<string>",
"customer.zipCode": "<string>",
"customer.street": "<string>",
"customer.number": "<string>",
"customer.complement": "<string>",
"customer.neighborhood": "<string>",
"customer.city": "<string>",
"customer.state": "<string>"
},
"card": {
"card.number": "<string>",
"card.holderName": "<string>",
"card.expirationDate": "<string>",
"card.cvv": "<string>",
"card.installments": 123
},
"checkoutSessionToken": "<string>",
"additionalInfo": "<string>"
}
'import requests
url = "https://garu.com.br/api/v1/charges"
payload = {
"productId": "<string>",
"paymentMethod": "<string>",
"customer": {
"customer.name": "<string>",
"customer.email": "<string>",
"customer.document": "<string>",
"customer.phone": "<string>",
"customer.zipCode": "<string>",
"customer.street": "<string>",
"customer.number": "<string>",
"customer.complement": "<string>",
"customer.neighborhood": "<string>",
"customer.city": "<string>",
"customer.state": "<string>"
},
"card": {
"card.number": "<string>",
"card.holderName": "<string>",
"card.expirationDate": "<string>",
"card.cvv": "<string>",
"card.installments": 123
},
"checkoutSessionToken": "<string>",
"additionalInfo": "<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({
productId: '<string>',
paymentMethod: '<string>',
customer: {
'customer.name': '<string>',
'customer.email': '<string>',
'customer.document': '<string>',
'customer.phone': '<string>',
'customer.zipCode': '<string>',
'customer.street': '<string>',
'customer.number': '<string>',
'customer.complement': '<string>',
'customer.neighborhood': '<string>',
'customer.city': '<string>',
'customer.state': '<string>'
},
card: {
'card.number': '<string>',
'card.holderName': '<string>',
'card.expirationDate': '<string>',
'card.cvv': '<string>',
'card.installments': 123
},
checkoutSessionToken: '<string>',
additionalInfo: '<string>'
})
};
fetch('https://garu.com.br/api/v1/charges', 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/v1/charges",
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([
'productId' => '<string>',
'paymentMethod' => '<string>',
'customer' => [
'customer.name' => '<string>',
'customer.email' => '<string>',
'customer.document' => '<string>',
'customer.phone' => '<string>',
'customer.zipCode' => '<string>',
'customer.street' => '<string>',
'customer.number' => '<string>',
'customer.complement' => '<string>',
'customer.neighborhood' => '<string>',
'customer.city' => '<string>',
'customer.state' => '<string>'
],
'card' => [
'card.number' => '<string>',
'card.holderName' => '<string>',
'card.expirationDate' => '<string>',
'card.cvv' => '<string>',
'card.installments' => 123
],
'checkoutSessionToken' => '<string>',
'additionalInfo' => '<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/v1/charges"
payload := strings.NewReader("{\n \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<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/v1/charges")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/charges")
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 \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyCobranças
Criar Cobrança
Crie uma cobrança PIX, boleto ou cartão e receba os dados para exibir o pagamento no seu próprio checkout
POST
/
api
/
v1
/
charges
Criar Cobrança
curl --request POST \
--url https://garu.com.br/api/v1/charges \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>' \
--data '
{
"productId": "<string>",
"paymentMethod": "<string>",
"customer": {
"customer.name": "<string>",
"customer.email": "<string>",
"customer.document": "<string>",
"customer.phone": "<string>",
"customer.zipCode": "<string>",
"customer.street": "<string>",
"customer.number": "<string>",
"customer.complement": "<string>",
"customer.neighborhood": "<string>",
"customer.city": "<string>",
"customer.state": "<string>"
},
"card": {
"card.number": "<string>",
"card.holderName": "<string>",
"card.expirationDate": "<string>",
"card.cvv": "<string>",
"card.installments": 123
},
"checkoutSessionToken": "<string>",
"additionalInfo": "<string>"
}
'import requests
url = "https://garu.com.br/api/v1/charges"
payload = {
"productId": "<string>",
"paymentMethod": "<string>",
"customer": {
"customer.name": "<string>",
"customer.email": "<string>",
"customer.document": "<string>",
"customer.phone": "<string>",
"customer.zipCode": "<string>",
"customer.street": "<string>",
"customer.number": "<string>",
"customer.complement": "<string>",
"customer.neighborhood": "<string>",
"customer.city": "<string>",
"customer.state": "<string>"
},
"card": {
"card.number": "<string>",
"card.holderName": "<string>",
"card.expirationDate": "<string>",
"card.cvv": "<string>",
"card.installments": 123
},
"checkoutSessionToken": "<string>",
"additionalInfo": "<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({
productId: '<string>',
paymentMethod: '<string>',
customer: {
'customer.name': '<string>',
'customer.email': '<string>',
'customer.document': '<string>',
'customer.phone': '<string>',
'customer.zipCode': '<string>',
'customer.street': '<string>',
'customer.number': '<string>',
'customer.complement': '<string>',
'customer.neighborhood': '<string>',
'customer.city': '<string>',
'customer.state': '<string>'
},
card: {
'card.number': '<string>',
'card.holderName': '<string>',
'card.expirationDate': '<string>',
'card.cvv': '<string>',
'card.installments': 123
},
checkoutSessionToken: '<string>',
additionalInfo: '<string>'
})
};
fetch('https://garu.com.br/api/v1/charges', 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/v1/charges",
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([
'productId' => '<string>',
'paymentMethod' => '<string>',
'customer' => [
'customer.name' => '<string>',
'customer.email' => '<string>',
'customer.document' => '<string>',
'customer.phone' => '<string>',
'customer.zipCode' => '<string>',
'customer.street' => '<string>',
'customer.number' => '<string>',
'customer.complement' => '<string>',
'customer.neighborhood' => '<string>',
'customer.city' => '<string>',
'customer.state' => '<string>'
],
'card' => [
'card.number' => '<string>',
'card.holderName' => '<string>',
'card.expirationDate' => '<string>',
'card.cvv' => '<string>',
'card.installments' => 123
],
'checkoutSessionToken' => '<string>',
'additionalInfo' => '<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/v1/charges"
payload := strings.NewReader("{\n \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<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/v1/charges")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/charges")
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 \"productId\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"customer\": {\n \"customer.name\": \"<string>\",\n \"customer.email\": \"<string>\",\n \"customer.document\": \"<string>\",\n \"customer.phone\": \"<string>\",\n \"customer.zipCode\": \"<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 \"card\": {\n \"card.number\": \"<string>\",\n \"card.holderName\": \"<string>\",\n \"card.expirationDate\": \"<string>\",\n \"card.cvv\": \"<string>\",\n \"card.installments\": 123\n },\n \"checkoutSessionToken\": \"<string>\",\n \"additionalInfo\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyVisão Geral
Cria uma cobrança e devolve tudo que você precisa para exibir o pagamento dentro da sua própria interface — sem redirecionar o cliente. É a base do checkout transparente. Se você não precisa desse controle, o caminho mais simples continua sendo o link de pagamento ou a Checkout Session, onde a Garu hospeda a página de pagamento.A cobrança é sempre feita em cima de um produto. Crie o produto uma vez com
POST /api/v1/products e use o uuid dele aqui.Headers
string
required
Sua chave de API (
Bearer sk_live_...)string
required
application/jsonstring
Chave única por cobrança. Reenviar a mesma requisição com a mesma chave devolve a cobrança já criada em vez de duplicar. Válida por 24h.
Request Body
string
required
UUID do produto a ser cobrado
string
required
Método de pagamento:
pix, boleto ou creditCardobject
required
Dados de quem está pagando
Show Campos do customer
Show Campos do customer
string
required
Nome completo (3 a 255 caracteres)
string
required
E-mail válido
string
required
CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
string
required
Telefone com DDD, 10 ou 11 dígitos, apenas números
string
CEP com 8 dígitos, sem hífen
string
Logradouro
string
Número do endereço
string
Complemento
string
Bairro
string
Cidade
string
Sigla do estado, 2 letras maiúsculas (ex:
SP)object
Dados do cartão. Obrigatório apenas quando
paymentMethod = creditCard.string
Token de uma Checkout Session criada previamente. Use quando quiser aproveitar
metadata e client_reference_id da session mantendo o checkout na sua interface.string
Texto livre anexado à cobrança
Cartão: servidor-para-servidor apenas. Este endpoint recebe o número do cartão e o CVV em texto claro. Chame-o exclusivamente do seu backend — nunca do navegador nem de um aplicativo, onde a sua chave de API e os dados do cartão ficariam expostos.Processar dados de cartão no seu servidor coloca a sua operação no escopo do PCI DSS. Se você prefere não assumir isso, use
pix e boleto aqui e deixe o cartão para a página hospedada da Garu.Exemplo de Requisição
curl -X POST https://garu.com.br/api/v1/charges \
-H "Authorization: Bearer sk_live_sua_chave_api" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: pedido-4472" \
-d '{
"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"paymentMethod": "pix",
"customer": {
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"document": "12345678909",
"phone": "11987654321"
}
}'
const response = await fetch('https://garu.com.br/api/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GARU_API_KEY}`,
'Content-Type': 'application/json',
'X-Idempotency-Key': 'pedido-4472'
},
body: JSON.stringify({
productId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
paymentMethod: 'pix',
customer: {
name: 'Maria Silva',
email: 'maria@exemplo.com.br',
document: '12345678909',
phone: '11987654321'
}
})
});
const charge = await response.json();
console.log(charge.pix.code); // código PIX copia-e-cola
import os
import requests
response = requests.post(
"https://garu.com.br/api/v1/charges",
headers={
"Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
"Content-Type": "application/json",
"X-Idempotency-Key": "pedido-4472",
},
json={
"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"paymentMethod": "pix",
"customer": {
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"document": "12345678909",
"phone": "11987654321",
},
},
)
charge = response.json()
print(charge["pix"]["code"])
Resposta de Sucesso (201 Created)
{
"uuid": "6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f",
"status": "pending",
"paymentMethod": "pix",
"amount": 349.00,
"chargedTotal": 349.00,
"installments": 1,
"product": {
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Curso de Marketing Digital"
},
"customer": {
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"document": "***456789**"
},
"pix": {
"code": "00020101021226840014br.gov.bcb.pix..."
},
"boleto": null,
"card": null,
"refund": null,
"createdAt": "2026-07-22T14:03:11.000Z",
"expiresAt": null
}
Blocos por método de pagamento
Exatamente um dos três vem preenchido, conforme opaymentMethod:
"pix": { "code": "00020101021226840014br.gov.bcb.pix..." }
"boleto": {
"barcodeLine": "34191.79001 01043.510047 91020.150008 1 98650000034900",
"pdfUrl": "https://garu.com.br/api/v1/charges/6f1c9b2e-.../boleto.pdf"
}
"card": {
"brand": "visa",
"last4": "1111",
"authorizationCode": "123456"
}
pix.code é o copia-e-cola (padrão EMV). Renderize-o como QR Code com qualquer biblioteca do seu stack — não devolvemos imagem justamente para que nada no seu checkout venha de um domínio de terceiros.
O boleto.pdfUrl aponta para o domínio da Garu e pode ser entregue direto ao seu cliente: é uma URL pública, que não exige chave de API.
Sobre o expiresAt
O
expiresAt só vem preenchido para boleto, com o vencimento (8 dias após a criação). Para PIX e cartão ele vem null.Motivo: hoje a Garu não define uma janela de expiração própria para o código PIX. Em vez de devolver um valor que não corresponde a nada, devolvemos null. Se o seu fluxo precisa de um prazo para o PIX, controle-o do seu lado.Valores: amount e chargedTotal
amount é o preço base do produto. chargedTotal é o que o cliente foi efetivamente cobrado.Eles são iguais em PIX, boleto e cartão em 1×. Em parcelamento no cartão o chargedTotal é maior, porque inclui o acréscimo do parcelamento: um produto de R$ 349,00 em 2× resulta em amount: 349.00 e chargedTotal: 358.52.Use chargedTotal para reconciliar o que foi cobrado e amount para casar com o seu catálogo.Erros
| Código | Quando acontece |
|---|---|
400 | Dados inválidos (documento, telefone, cartão) ou pagamento recusado pela operadora |
401 | Chave de API ausente ou inválida |
404 | O productId não existe ou não pertence à conta da chave usada |
Próximos passos
Depois de criar a cobrança, acompanhe o pagamento por webhook ou consultandoGET /api/v1/charges/{uuid}.Was this page helpful?
⌘I