Começando

Começar em 5 minutos

Crie uma chave de API, faça o primeiro pagamento Pix e receba a confirmação.

1. Crie a chave de API

  1. Entre no painel em https://app.goiabapay.com.
  2. Abra Integração > Chaves de API e clique em Nova chave.
  3. Marque os escopos PAYMENT:CREATE e PAYMENT:READ.
  4. Copie a chave. Ela aparece uma única vez.

Guarde a chave numa variável de ambiente do seu servidor:

export PAYMENTS_API_KEY='dk_000000000000_EXEMPLONAOUSE'

2. Cadastre o webhook

Abra Integração > Webhooks no painel e cadastre a URL HTTPS do seu servidor que vai receber os avisos. Guarde o segredo de assinatura que aparece na criação. Veja Webhooks.

3. Crie o primeiro pagamento

Faça a chamada do seu servidor. O valor vem do seu pedido, nunca do navegador.

curl --request POST \
  --url 'https://api.goiabapay.com/v1/payments' \
  --header "Authorization: Bearer $PAYMENTS_API_KEY" \
  --header 'Idempotency-Key: pedido-1234' \
  --header 'Content-Type: application/json' \
  --data '{"amount_cents": 15000, "external_id": "pedido-1234", "payer": {"name": "Maria Silva", "document": "12345678909"}}'

A resposta traz o id do pagamento, o status pending e o código Pix em pix.copy_paste. Guarde o id junto com o pedido.

4. Mostre o Pix ao cliente

Mostre o código copia e cola na sua tela, ou envie o payment_url: é uma página pronta com QR Code e código copia e cola.

5. Receba a confirmação

Quando o cliente pagar, você recebe o evento payment.paid no seu webhook. Só então libere o produto. Veja Consultar o status da forma correta.