Criar cobrança
curl --request POST \
--url https://api.sandbox.gravitypay.app/v1/charges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"currency": "<string>",
"items": [
{
"name": "<string>",
"quantity": 2,
"unitAmountInCents": 1
}
],
"amountInCents": 2,
"customer": {
"email": "jsmith@example.com",
"name": "<string>"
},
"description": "<string>",
"metadata": {},
"postbackUrl": "<string>",
"successUrl": "<string>",
"cancelUrl": "<string>",
"boletoDueInDays": 30,
"maxInstallments": 1,
"passInstallmentInterest": true
}
'import requests
url = "https://api.sandbox.gravitypay.app/v1/charges"
payload = {
"currency": "<string>",
"items": [
{
"name": "<string>",
"quantity": 2,
"unitAmountInCents": 1
}
],
"amountInCents": 2,
"customer": {
"email": "jsmith@example.com",
"name": "<string>"
},
"description": "<string>",
"metadata": {},
"postbackUrl": "<string>",
"successUrl": "<string>",
"cancelUrl": "<string>",
"boletoDueInDays": 30,
"maxInstallments": 1,
"passInstallmentInterest": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: '<string>',
items: [{name: '<string>', quantity: 2, unitAmountInCents: 1}],
amountInCents: 2,
customer: {email: 'jsmith@example.com', name: '<string>'},
description: '<string>',
metadata: {},
postbackUrl: '<string>',
successUrl: '<string>',
cancelUrl: '<string>',
boletoDueInDays: 30,
maxInstallments: 1,
passInstallmentInterest: true
})
};
fetch('https://api.sandbox.gravitypay.app/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://api.sandbox.gravitypay.app/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([
'currency' => '<string>',
'items' => [
[
'name' => '<string>',
'quantity' => 2,
'unitAmountInCents' => 1
]
],
'amountInCents' => 2,
'customer' => [
'email' => 'jsmith@example.com',
'name' => '<string>'
],
'description' => '<string>',
'metadata' => [
],
'postbackUrl' => '<string>',
'successUrl' => '<string>',
'cancelUrl' => '<string>',
'boletoDueInDays' => 30,
'maxInstallments' => 1,
'passInstallmentInterest' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.sandbox.gravitypay.app/v1/charges"
payload := strings.NewReader("{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.gravitypay.app/v1/charges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.gravitypay.app/v1/charges")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "chg_c7fb440eb3112525e35718d4488d66c8",
"object": "charge",
"status": "pending",
"amountInCents": 15900,
"currency": "brl",
"items": [],
"description": "Curso NR-35",
"customer": {
"email": null,
"name": null
},
"metadata": {},
"postbackUrl": "https://integrador.example/postback",
"successUrl": null,
"cancelUrl": null,
"maxInstallments": 1,
"passInstallmentInterest": true,
"boletoDueInDays": null,
"createdAt": "2026-10-03T13:47:55.024Z",
"checkoutUrl": "https://gravitypay.app/c/chg_c7fb440eb3112525e35718d4488d66c8",
"postbackSecret": "whsec_6dec1cf6..."
}Cobranças
Criar cobrança
Cria uma cobrança avulsa e devolve uma checkoutUrl para o cliente pagar. O postbackSecret (que valida os webhooks desta cobrança) é retornado apenas nesta resposta de criação.
Pagamento transparente: mande também o campo payment (mesmo formato de POST /v1/charges/{id}/payments) para criar a cobrança e o pagamento numa chamada só. O corpo inteiro é validado antes: dado faltando, inclusive o que só o gateway da loja exige, é 400 e nenhuma cobrança nasce. Criada a cobrança, a resposta é sempre 201, com payment quando o pagamento deu certo ou paymentError quando falhou (recusa, método indisponível, formato de cartão errado, gateway fora); nesse caso a cobrança segue pending e aceita nova tentativa. Replay com o mesmo Idempotency-Key devolve a cobrança e o último pagamento dela, sem postbackSecret e sem criar outro pagamento.
Escopo exigido: charges:write.
POST
/
v1
/
charges
Criar cobrança
curl --request POST \
--url https://api.sandbox.gravitypay.app/v1/charges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"currency": "<string>",
"items": [
{
"name": "<string>",
"quantity": 2,
"unitAmountInCents": 1
}
],
"amountInCents": 2,
"customer": {
"email": "jsmith@example.com",
"name": "<string>"
},
"description": "<string>",
"metadata": {},
"postbackUrl": "<string>",
"successUrl": "<string>",
"cancelUrl": "<string>",
"boletoDueInDays": 30,
"maxInstallments": 1,
"passInstallmentInterest": true
}
'import requests
url = "https://api.sandbox.gravitypay.app/v1/charges"
payload = {
"currency": "<string>",
"items": [
{
"name": "<string>",
"quantity": 2,
"unitAmountInCents": 1
}
],
"amountInCents": 2,
"customer": {
"email": "jsmith@example.com",
"name": "<string>"
},
"description": "<string>",
"metadata": {},
"postbackUrl": "<string>",
"successUrl": "<string>",
"cancelUrl": "<string>",
"boletoDueInDays": 30,
"maxInstallments": 1,
"passInstallmentInterest": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: '<string>',
items: [{name: '<string>', quantity: 2, unitAmountInCents: 1}],
amountInCents: 2,
customer: {email: 'jsmith@example.com', name: '<string>'},
description: '<string>',
metadata: {},
postbackUrl: '<string>',
successUrl: '<string>',
cancelUrl: '<string>',
boletoDueInDays: 30,
maxInstallments: 1,
passInstallmentInterest: true
})
};
fetch('https://api.sandbox.gravitypay.app/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://api.sandbox.gravitypay.app/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([
'currency' => '<string>',
'items' => [
[
'name' => '<string>',
'quantity' => 2,
'unitAmountInCents' => 1
]
],
'amountInCents' => 2,
'customer' => [
'email' => 'jsmith@example.com',
'name' => '<string>'
],
'description' => '<string>',
'metadata' => [
],
'postbackUrl' => '<string>',
'successUrl' => '<string>',
'cancelUrl' => '<string>',
'boletoDueInDays' => 30,
'maxInstallments' => 1,
'passInstallmentInterest' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.sandbox.gravitypay.app/v1/charges"
payload := strings.NewReader("{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.gravitypay.app/v1/charges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.gravitypay.app/v1/charges")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"<string>\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"unitAmountInCents\": 1\n }\n ],\n \"amountInCents\": 2,\n \"customer\": {\n \"email\": \"jsmith@example.com\",\n \"name\": \"<string>\"\n },\n \"description\": \"<string>\",\n \"metadata\": {},\n \"postbackUrl\": \"<string>\",\n \"successUrl\": \"<string>\",\n \"cancelUrl\": \"<string>\",\n \"boletoDueInDays\": 30,\n \"maxInstallments\": 1,\n \"passInstallmentInterest\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "chg_c7fb440eb3112525e35718d4488d66c8",
"object": "charge",
"status": "pending",
"amountInCents": 15900,
"currency": "brl",
"items": [],
"description": "Curso NR-35",
"customer": {
"email": null,
"name": null
},
"metadata": {},
"postbackUrl": "https://integrador.example/postback",
"successUrl": null,
"cancelUrl": null,
"maxInstallments": 1,
"passInstallmentInterest": true,
"boletoDueInDays": null,
"createdAt": "2026-10-03T13:47:55.024Z",
"checkoutUrl": "https://gravitypay.app/c/chg_c7fb440eb3112525e35718d4488d66c8",
"postbackSecret": "whsec_6dec1cf6..."
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Required string length:
3Show child attributes
Show child attributes
Required range:
x >= 1Show child attributes
Show child attributes
Maximum string length:
255Vencimento do boleto desta cobrança, em dias corridos. Use quando o cliente paga no checkout hospedado: ele não conhece o prazo que o seu sistema prometeu. Ausente = padrão da loja (1 dia, salvo configuração no painel).
Required range:
1 <= x <= 60Máximo de parcelas no cartão (1 = à vista).
Required range:
1 <= x <= 12true: o comprador paga o juro do parcelamento; false: a loja absorve.
Opcional. Cria o pagamento junto com a cobrança (pagamento transparente). Sem ele, nada muda.
Show child attributes
Show child attributes
Response
Cobrança criada. Com payment no corpo, traz payment (pagamento criado) ou paymentError (pagamento falhou; a cobrança segue pending).
Example:
"chg_2e59538f..."
Example:
"charge"
Available options:
pending, paid, failed, refunded, canceled Show child attributes
Show child attributes
Show child attributes
Show child attributes
Retornado apenas na criação.
Vencimento do boleto desta cobrança, em dias corridos. null = padrão da loja.
Só quando o corpo trouxe payment e ele deu certo. No replay do Idempotency-Key, o último pagamento da cobrança (ou null).
Show child attributes
Show child attributes
Só quando o corpo trouxe payment e ele falhou.
Show child attributes
Show child attributes