Comece aqui
Primeira chamada
Crie uma cobrança no servidor e obtenha o código PIX.
#Pré-requisitos
Rode o exemplo no backend, com as chaves da empresa só no servidor.
A empresa precisa estar ativa e com KYC aprovado.
#Faça a requisição
O JavaScript abaixo é código de servidor. Sucesso do checkout é HTTP 200.
cURL
curl --request POST 'https://api-gateway.grandepay.com.br/v1/checkout' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Public-Key: pk_sua_empresa' \
--header 'X-Secret-Key: sk_sua_empresa' \
--data '{"amount":1500,"paymentMethod":"pix","postbackUrl":"https://empresa.example/api/grandepay/postback","items":[{"title":"Assinatura mensal","unitPrice":1500,"quantity":1,"externalRef":"plan-pro-001"}],"customer":{"name":"Maria de Souza","email":"maria@example.com","phone":"11999999999","document":{"number":"12345678901","type":"cpf"}},"pix":{"expiresInDays":2}}'Node
const publicKey = process.env.GRANDEPAY_PUBLIC_KEY;
const secretKey = process.env.GRANDEPAY_SECRET_KEY;
if (!publicKey || !secretKey) {
throw new Error("Defina GRANDEPAY_PUBLIC_KEY e GRANDEPAY_SECRET_KEY no servidor.");
}
const response = await fetch("https://api-gateway.grandepay.com.br/v1/checkout", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
"X-Public-Key": publicKey,
"X-Secret-Key": secretKey,
},
body: JSON.stringify({
amount: 1500,
paymentMethod: "pix",
postbackUrl: "https://empresa.example/api/grandepay/postback",
items: [
{
title: "Assinatura mensal",
unitPrice: 1500,
quantity: 1,
},
],
customer: {
name: "Maria de Souza",
document: {
number: "12345678901",
type: "cpf",
},
},
pix: {
expiresInDays: 2,
},
}),
});
if (!response.ok) {
const errorBody = await response.json().catch(() => null);
const message = errorBody && errorBody.error ? errorBody.error : "resposta não JSON";
throw new Error("Checkout recusado (" + response.status + "): " + message);
}
const data = await response.json();PHP
<?php
$publicKey = getenv('GRANDEPAY_PUBLIC_KEY');
$secretKey = getenv('GRANDEPAY_SECRET_KEY');
if ($publicKey === false || $secretKey === false) {
throw new RuntimeException('Defina GRANDEPAY_PUBLIC_KEY e GRANDEPAY_SECRET_KEY no servidor.');
}
$payload = [
'amount' => 1500,
'paymentMethod' => 'pix',
'postbackUrl' => 'https://empresa.example/api/grandepay/postback',
'items' => [
[
'title' => 'Assinatura mensal',
'unitPrice' => 1500,
'quantity' => 1,
],
],
'customer' => [
'name' => 'Maria de Souza',
'document' => [
'number' => '12345678901',
'type' => 'cpf',
],
],
'pix' => [
'expiresInDays' => 2,
],
];
$ch = curl_init('https://api-gateway.grandepay.com.br/v1/checkout');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Accept: application/json',
'Content-Type: application/json',
'X-Public-Key: ' . $publicKey,
'X-Secret-Key: ' . $secretKey,
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($result === false) {
throw new RuntimeException('Falha de rede ao criar o checkout.');
}
$data = json_decode($result, true);
if ($status < 200 || $status >= 300) {
$message = is_array($data) && isset($data['error']) ? $data['error'] : 'resposta não JSON';
throw new RuntimeException('Checkout recusado (' . $status . '): ' . $message);
}CPF e QR dos exemplos são sintéticos.
#Leia a resposta
A resposta 200 traz oito campos. status inicial é 0; pix_code pode ser nulo.
Renderize o código PIX sem alterar o conteúdo.
200.json
{
"uuid": "4d78d8ca-a9f1-4c2a-bf15-7f8ca71e3a70",
"status": 0,
"amount_cents": 1500,
"pix_code": "00020101021226870014br.gov.bcb.pix2565qrcodes.example.com/pix/4d78d8ca",
"pix_expiration": "2026-03-15T17:00:00.000Z",
"provider_transaction_id": "prov_tx_123",
"external_id": "GP-9a5f1eb3-6885-4f26-93f3-3c0954d0f42f",
"created_at": "2026-03-13T17:00:00.000Z"
}#Confirme por postback
A criação não marca o pedido como pago. O evento transaction.paid confirma o pagamento. Valide a assinatura e persista o evento conforme Recebendo postbacks e HMAC.
Esta página foi útil?