Referência da API

Criar checkout

POST/v1/checkout

Envie POST /v1/checkout para criar uma cobrança PIX.

#Endpoint

POST /v1/checkout cria uma cobrança PIX e devolve HTTP 200.

#Headers

X-Public-Keystringobrigatório

Identifica a empresa.

X-Secret-Keystringobrigatório

Valida a empresa com comparação timing-safe.

Acceptstring

Recomendado: application/json.

Content-Typestringobrigatório

application/json.

#Body

amountintegerobrigatório

Valor cobrado em centavos inteiros, positivo. Não é recalculado a partir de items.

inteiro em centavos · maior que 0

paymentMethod"pix"obrigatório

Único método do checkout público. Case-sensitive.

postbackUrlstring

Prioridade sobre o webhook da empresa. HTTPS público, sem credenciais, até 500 caracteres.

itemsarrayobrigatório

Mínimo de um item.

mínimo 1 item

titlestringobrigatório

Descrição do item.

1 a 255 caracteres

unitPriceintegerobrigatório

Preço unitário em centavos.

inteiro ≥ 1

quantityintegerobrigatório

Quantidade.

inteiro ≥ 1

tangibleboolean

Item físico.

externalRefstring

Referência do item no seu sistema, gravada em metadata.

até 255 caracteres

customerobjectobrigatório

Pagador. O objeto é obrigatório.

namestringobrigatório

Nome do pagador.

2 a 255 caracteres

emailstring

E-mail válido.

até 255 caracteres

phonestring

Somente dígitos.

10 ou 11 dígitos

document.numberstringobrigatório

CPF ou CNPJ numérico, 11 a 14 dígitos.

document.type"cpf" | "cnpj" | "CPF" | "CNPJ"obrigatório

Tipo do documento.

addressobject

Opcional. zipCode ≤10; street, neighborhood e city ≤255; streetNumber ≤20; state e country com 2 caracteres.

pix.expiresInDaysinteger

Validade em dias, convertida para segundos.

1 a 30

#Resposta 200

uuiduuid

Identificador público da transação na GrandePay.

statusinteger

Status numérico. Na criação é 0.

amount_centsinteger

Valor da cobrança em centavos inteiros.

pix_codestringnullable

Código copia e cola do PIX.

pix_expirationstringnullable

ISO 8601 de expiração do QR, se o provedor informar.

provider_transaction_idstringnullable

ID da operação no provedor.

external_idstring

Referência interna no formato GP-uuid.

created_atstring

Timestamp ISO 8601 de criação da transação.

No postback, data.id é o mesmo uuid. O postback omite campos nulos; esta resposta pode trazer null.

#Erros

A lista completa está em Erros.

403

{
  "error": "KYC approval required"
}

502

{
  "error": "Provider Medusa: upstream timeout",
  "code": "PROVIDER_ERROR"
}

Exemplos

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);
}

200

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

401

{
  "error": "Missing X-Public-Key / X-Secret-Key"
}

422

{
  "error": "Validation failed",
  "details": "Expected property 'paymentMethod' to be equal to 'pix'"
}

Esta página foi útil?