Pular para o conteúdo
SimPixSimPix Docs

Quickstart

Neste guia você cria sua primeira cobrança Pix de ponta a ponta: criar a transação → exibir o qr_code → receber o webhook de confirmação.

Pré-requisitos

Seção intitulada “Pré-requisitos”
  • Sua x-api-key e seu x-token.
  • Um endpoint HTTPS público para receber webhooks (opcional, mas recomendado).

  1. Registre um webhook (opcional, recomendado)

    Assim você recebe a confirmação do pagamento em tempo real, sem precisar fazer polling.

    POST /api/webhooks
    curl --request POST \
      --url https://api.simpixpagamentos.com/api/webhooks \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: <API_KEY>' \
      --header 'x-token: <TOKEN>' \
      --header 'x-timezone: America/Sao_Paulo' \
      --header 'idempotency-key: <UNIQUE_KEY>' \
      --data '{
        "url": "https://your-server.com/webhooks/hub",
        "events": ["transaction", "withdraw", "dispute"]
      }'

    Guarde o secret retornado — ele é usado para validar a assinatura HMAC dos webhooks:

    Resposta 201
    {
      "code": 201,
      "content": {
        "magic_id": "wh_03UdoKvLNLHg",
        "url": "https://your-server.com/webhooks/hub",
        "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
        "events": ["transaction", "withdraw", "dispute"],
        "active": true,
        "created_at": "2025-02-19T17:15:25.688Z",
        "updated_at": "2025-02-19T17:15:26.703Z"
      },
      "message": "Webhook created",
      "timestamp": "2025-02-19T17:15:26.703Z"
    }

  2. Crie a transação Pix

    Envie o valor, uma referência sua (external_ref) e os dados do pagador:

    POST /api/transactions
    curl --request POST \
      --url https://api.simpixpagamentos.com/api/transactions \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: <API_KEY>' \
      --header 'x-token: <TOKEN>' \
      --header 'x-timezone: America/Sao_Paulo' \
      --header 'idempotency-key: <UNIQUE_KEY>' \
      --data '{
        "amount": 4.00,
        "external_ref": "external_ref_order",
        "requester": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "11999999999",
          "document": "12468239008"
        },
        "payment_method": "Pix",
        "expires_in": 3600,
        "description": "Order payment"
      }'

    A resposta vem com status PENDING e o código copia-e-cola do Pix:

    Resposta 201
    {
      "code": 201,
      "content": {
        "magic_id": "18017579377364992",
        "amount": 4.00,
        "currency": "BRL",
        "status": "PENDING",
        "decline_reason": null,
        "description": "Order payment",
        "payment_method": "Pix",
        "qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode...",
        "end_to_end": "38169107220140032",
        "requester": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "11999999999",
          "document": "12468239008"
        },
        "external_ref": "external_ref_order",
        "created_at": "2025-02-19T17:15:25.688Z",
        "updated_at": "2025-02-19T17:15:26.703Z"
      },
      "message": "Transaction created",
      "timestamp": "2025-02-19T17:15:26.703Z"
    }

  3. Exiba o qr_code para o pagador

    O campo qr_code é o payload Pix copia-e-cola (BR Code). Você pode:

    • Renderizá-lo como QR code na sua interface (qualquer biblioteca de QR code serve); e/ou
    • Oferecer um botão “copiar código” para o pagador colar no app do banco.

    A cobrança expira após o tempo definido em expires_in (em segundos).

  4. Receba o webhook de confirmação

    Quando o pagador concluir o Pix, a SimPix envia um POST para o seu endpoint com o evento TRANSACTION e o status CONFIRMED:

    Webhook de transação (payload)
    {
      "data": {
        "magic_id": "T_123JKL114HJHDKSAH1JK23",
        "amount": 1.0,
        "currency": "BRL",
        "status": "CONFIRMED",
        "decline_reason": null,
        "description": "optional",
        "payment_method": "Pix",
        "qr_code": "00020101021126700014br.gov.bcb.pix...",
        "end_to_end": "E607894312025071873189DAHJSKH12",
        "external_ref": "external_ref_order",
        "requester": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "11999999999",
          "document": "12468239008"
        },
        "movement": {
          "payer": {
            "name": "Payer Name",
            "document": "12345678901",
            "bank": "BANCO INTER S.A.",
            "agency": "0001",
            "account": "123456-7"
          },
          "payee": {
            "name": "Payee Name",
            "document": "12345678000190",
            "bank": "BANCO INTER S.A.",
            "agency": "0001",
            "account": "765432-1"
          }
        },
        "created_at": "2025-12-14T01:03:06.467Z",
        "updated_at": "2025-12-14T01:03:06.467Z"
      },
      "event": "TRANSACTION"
    }

    Valide o header x-webhook-signature com HMAC SHA256 antes de processar — veja o guia de webhooks.

  5. (Alternativa) Consulte o status por polling

    Se preferir, consulte a transação pela sua referência:

    GET /api/transactions
    curl --request GET \
      --url 'https://api.simpixpagamentos.com/api/transactions?external_ref=external_ref_order&limit=20' \
      --header 'x-api-key: <API_KEY>' \
      --header 'x-token: <TOKEN>' \
      --header 'x-timezone: America/Sao_Paulo'

Próximos passos

Seção intitulada “Próximos passos”