API publica do gateway

Gere cobrancas PIX pela API da GrandePay

Esta pagina documenta a integracao publica do checkout em POST /v1/checkout, executada pela elysia-api. A chamada cria a cobranca, retorna o codigo PIX e usa postbacks para avisar mudancas de status.

Comecar integracao Acessar painel

Endpoint de integracao

Use a base da Elysia API no checkout publico

Base Elysia: https://api-gateway.grandepay.com.br

Base Laravel administrativa: https://api.grandepay.com.br

POST https://api-gateway.grandepay.com.br/v1/checkout

Autenticacao

2 headers

X-Public-Key e X-Secret-Key em toda chamada.

Formato

JSON

Valores financeiros sempre em centavos.

Confirmacao

Postback

Mudancas de status chegam no seu endpoint com assinatura HMAC.

Primeira chamada

Suba a cobranca com uma requisicao simples

Os exemplos abaixo ja usam a base da Elysia API e o formato real esperado pelo checkout.

shellRequisicao completa

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_live_sua_empresa' \
  --header 'X-Secret-Key: sk_live_sua_empresa' \
  --data '{
    "amount": 1500,
    "paymentMethod": "pix",
    "postbackUrl": "https://empresa.com/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
    }
  }'

Autenticacao

Envie as chaves da empresa em headers

A Elysia API localiza a empresa pela public key e valida a secret key com comparacao timing-safe. Sem as duas chaves, a requisicao retorna 401.

Header	Obrigatorio	Descricao
`X-Public-Key`	Sim	Chave publica da empresa usada para identificar a conta integradora.
`X-Secret-Key`	Sim	Chave secreta validada pela Elysia API com comparacao timing-safe.
`Accept: application/json`	Recomendado	Mantem as respostas padronizadas em JSON.
`Content-Type: application/json`	Sim	Obrigatorio para o envio do body do checkout.

Armazene as chaves no backend

Nao exponha X-Secret-Key no front-end do cliente final. O ideal e a sua aplicacao servidora ser a responsavel por criar o checkout.

Conta precisa estar ativa

Se a empresa estiver desativada, a API responde 403 Enterprise inactive.

Payload

Estrutura aceita pelo checkout

O backend exige um body JSON com valor, itens e dados do pagador. O campo paymentMethod precisa ser exatamente pix.

jsonBody do POST /v1/checkout

{
  "amount": 1500,
  "paymentMethod": "pix",
  "postbackUrl": "https://empresa.com/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
  }
}

Campo	Tipo	Obrigatorio	Descricao
`amount`	integer	Sim	Valor da cobranca em centavos.
`paymentMethod`	"pix"	Sim	Hoje o checkout publico aceita apenas PIX.
`postbackUrl`	string	Nao	URL publica para receber atualizacoes de status da transacao.
`items`	array	Sim	Lista de itens da compra. Minimo de 1 item.
`items[].title`	string	Sim	Descricao curta do item.
`items[].unitPrice`	integer	Sim	Preco unitario em centavos.
`items[].quantity`	integer	Sim	Quantidade do item.
`items[].tangible`	boolean	Nao	Sinaliza se o item e fisico.
`items[].externalRef`	string	Nao	Referencia do item no seu ERP ou CRM.
`customer.name`	string	Sim	Nome do pagador.
`customer.email`	string	Nao	E-mail valido do pagador.
`customer.phone`	string	Nao	Telefone com 10 ou 11 digitos.
`customer.document.number`	string	Sim	CPF ou CNPJ apenas com numeros.
`customer.document.type`	"cpf" \| "cnpj" \| "CPF" \| "CNPJ"	Sim	Tipo do documento do pagador.
`customer.address`	object	Nao	Endereco opcional. Todos os subcampos sao opcionais.
`pix.expiresInDays`	integer	Nao	Validade do PIX em dias, entre 1 e 30.

Resposta

A API retorna os dados do checkout criado

Em caso de sucesso, a resposta traz o identificador da transacao, o codigo PIX e os metadados principais do provider.

200 okResposta de sucesso

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

Campo	Tipo	Descricao
`uuid`	uuid	Identificador da transacao na GrandePay.
`status`	integer	Status numerico da transacao. Na criacao, normalmente retorna 0.
`amount_cents`	integer	Valor da cobranca em centavos.
`pix_code`	string \| null	Codigo copia e cola do PIX retornado pelo provider.
`pix_expiration`	string \| null	Data ISO 8601 de expiracao do QR Code, quando aplicavel.
`provider_transaction_id`	string \| null	ID da operacao no provider.
`external_id`	string	Referencia interna da GrandePay no formato GP-uuid.
`created_at`	string	Timestamp ISO 8601 de criacao da transacao.

Codigo	Rotulo	Significado
0	pending	Checkout criado e aguardando o pagamento.
2	paid	Pagamento confirmado por webhook do provider.
3	failed	Falha definitiva na cobranca.
4	refunded	Transacao estornada.
5	cancelled	Transacao cancelada ou expirada.
6	chargeback	Transacao entrou em disputa/chargeback.

Erros

Falhas comuns da integracao

A Elysia diferencia erro de autenticacao, regra de negocio, validacao e indisponibilidade do provider.

HTTP	Quando acontece	Mensagem exemplo
401	Headers ausentes.	Missing X-Public-Key / X-Secret-Key
401	Chaves invalidas.	Invalid credentials
403	Empresa inativa.	Enterprise inactive
422	Payload invalido.	Validation failed
422	Sem roteamento ativo.	No active provider route for operation: pix_cash_in
502	Falha retornada pelo provider.	Provider Medusa: upstream timeout

422 validationErro de validacao

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

422 routeSem roteamento ativo

{
  "error": "No active provider route for operation: pix_cash_in",
  "code": "ROUTE_NOT_FOUND"
}

Postbacks

Atualizacoes de status chegam no seu endpoint

A URL enviada em postbackUrl tem prioridade. Se ela nao for informada, a GrandePay usa o webhook_url configurado na empresa.

Origem

POST

O postback sempre e enviado com Content-Type application/json.

Assinatura

HMAC

Valide o header X-Signature-256 usando a secret key da sua empresa.

Eventos

Status

paid, failed, refunded, cancelled, chargeback e eventos de disputa.

transaction.paidtransaction.failedtransaction.refundedtransaction.cancelledtransaction.chargeback

Eventos de disputa tambem podem ser enviados no formato transaction.status_normalizado, conforme o status mapeado a partir do webhook recebido do provider.

Header	Valor	Descricao
`Content-Type`	application/json	Payload JSON normalizado pela GrandePay.
`X-Signature-256`	sha256 hmac	Assinatura HMAC-SHA256 do corpo usando a secret key da empresa.
`X-Event`	transaction.paid	Nome do evento enviado.
`X-Postback-Id`	uuid	Identificador unico da tentativa do postback.
`X-Timestamp`	ISO 8601	Momento do disparo do postback.
`User-Agent`	GrandePay-Postback/1.0	Identificacao do emissor do postback.

paidPostback de pagamento confirmado

{
  "event": "transaction.paid",
  "timestamp": "2026-03-13T17:05:32.000Z",
  "data": {
    "id": "4d78d8ca-a9f1-4c2a-bf15-7f8ca71e3a70",
    "external_id": "GP-9a5f1eb3-6885-4f26-93f3-3c0954d0f42f",
    "type": "cash_in",
    "status": "paid",
    "amount_cents": 1500,
    "fee_cents": 15,
    "net_amount_cents": 1485,
    "currency": "BRL",
    "payment_method": "pix",
    "end_to_end_id": "E123456782026031317000000001",
    "description": "Assinatura mensal",
    "payer": {
      "name": "Maria de Souza",
      "document": "12345678901",
      "email": "maria@example.com"
    },
    "paid_at": "2026-03-13T17:05:32.000Z",
    "created_at": "2026-03-13T17:00:00.000Z"
  }
}

failedPostback de falha

{
  "event": "transaction.failed",
  "timestamp": "2026-03-13T17:10:00.000Z",
  "data": {
    "id": "4d78d8ca-a9f1-4c2a-bf15-7f8ca71e3a70",
    "external_id": "GP-9a5f1eb3-6885-4f26-93f3-3c0954d0f42f",
    "type": "cash_in",
    "status": "failed",
    "amount_cents": 1500,
    "currency": "BRL",
    "payment_method": "pix",
    "error_code": "PROVIDER_FAILED",
    "error_message": "Payment failed via webhook",
    "failed_at": "2026-03-13T17:10:00.000Z",
    "created_at": "2026-03-13T17:00:00.000Z"
  }
}

Retry e confirmacao

Responda 200 rapidamente para evitar novas tentativas

O worker de postbacks considera sucesso quando o seu endpoint devolve 2xx. Na pratica, responda 200 assim que persistir o evento e processe o restante de forma assincrona.

Fluxo recomendado

1. Valide a assinatura.
2. Grave o payload e marque o evento como recebido.
3. Retorne HTTP 200 imediatamente.
4. Processe conciliacao, notificacoes internas e regras de negocio em background.

Quando ha retry

Timeout, erro de conexao e qualquer resposta fora de 2xxentram na politica automatica de retry. Depois do limite maximo, o postback vai para dead-letter.

Politica atual de retries

O worker usa backoff progressivo e para apos 8 tentativas.

Tentativa	Backoff	Observacao
1	5s	Primeiro retry apos falha, timeout ou resposta fora de 2xx.
2	10s	Retry rapido para indisponibilidade curta.
3	30s	Mantem a fila responsiva sem bombardear o endpoint.
4	60s	Escalada de reconfirmacao.
5	120s	Retry com intervalo maior.
6	300s	Retry apos 5 minutos.
7	600s	Retry apos 10 minutos.
8	1800s	Ultima janela antes do dead-letter.

Checklist

Checklist de producao

Antes de liberar o checkout para os seus clientes finais, valide estes pontos.

Checkout

Guardar X-Public-Key e X-Secret-Key com seguranca.
Trabalhar valores em centavos no seu backend e front-end.
Renderizar o pix_code retornado sem alterar o conteudo.

Postbacks

Validar o header X-Signature-256 com a secret key da empresa.
Responder 200 rapido para evitar retry automatico.
Salvar X-Postback-Id e o payload para auditoria e idempotencia.

Pronto para integrar?

Use a documentacao como referencia publica e gerencie chaves e configuracoes no painel do gateway.

Entrar no painel Voltar ao inicio