Primeiro Pix

Do zero até um Pix pago no sandbox, em 4 passos. Nenhum dinheiro roda.

1. Pegue sua chave de teste. A SwitchPay te entrega uma chave que começa com swp_test_. Guarde numa variável de ambiente:

export SWP_KEY="swp_test_xxxxxxxxxxxxxxxxxxxxxxxx"

2. Crie a cobrança. Uma chamada só. O confirm: true faz ela criar e já gerar o Pix:

curl -X POST https://api.sandbox.switchpay.app.br/v2/payment-intents \
  -H "Authorization: Bearer $SWP_KEY" \
  -H "Idempotency-Key: pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1500,
    "paymentMethod": "PIX",
    "confirm": true,
    "referenceId": "pedido-0001",
    "buyer": {
      "name": "Maria Souza",
      "document": "12345678909",
      "email": "maria@exemplo.com",
      "phone": { "country": "55", "area": "11", "number": "987654321" }
    }
  }'

amountCents: 1500 é R$ 15,00 (sempre centavos). O Idempotency-Key é o id do pedido do seu lado: se a chamada cair e você repetir com a mesma chave, não gera cobrança em dobro.

3. Pegue o QR Code na resposta. Dois campos importam:

A transação nasce PENDING, esperando o pagamento.

4. Simule o pagamento. No sandbox ninguém paga de verdade; você avisa a API que o Pix foi pago:

curl -X POST https://api.sandbox.switchpay.app.br/v2/sandbox/transactions/SEU_TRANSACTION_ID/pay \
  -H "Authorization: Bearer $SWP_KEY"

A transação volta PAID. Pronto: primeiro Pix do começo ao fim.

E agora?

• Saber do pagamento sem perguntar: cadastre uma URL em POST /v2/webhooks e receba o aviso transaction.paid na hora. Veja Webhooks.
• Dividir o valor da venda: mande splitRules no passo 2. Veja Split.
• Boleto: igual ao Pix, com paymentMethod: "BOLETO" e o endereço do comprador.
• Cartão: tem um passo a mais, pra o número do cartão nunca passar pelo seu servidor. Veja Cartão: cofre e cifra.
• Produção: mesmas chamadas, trocando o endereço por https://api.switchpay.app.br e a chave por uma swp_live_. A rota de simular pagamento não existe lá.