DOC

Quickstart

Send your first transaction and enable webhooks in minutes. Use these headers on every request: Content-Type: application/json, x-api-key: <MY_API_KEY>, and x-token: <MY_TOKEN>.

1) Create a PIX transaction

Create a Pix transaction by sending a POST request to /api/transactions with the required fields.

Required headers

  • Name
    Content-Type
    Type
    string
    Description

    Must be application/json.

  • Name
    x-api-key
    Type
    string
    Description

    Your project API key.

  • Name
    x-token
    Type
    string
    Description

    Your session token.

  • Name
    idempotency-key
    Type
    string
    Description

    Unique key for idempotent requests.

Required body fields

  • Name
    amount
    Type
    number
    Description

    Amount in BRL (two decimal places).

  • Name
    external_ref
    Type
    string
    Description

    Your unique reference for tracking.

  • Name
    requester
    Type
    object
    Description

    Customer details (name, email, phone, document).

  • Name
    payment_method
    Type
    enum
    Description

    Must be Pix.

Request

POST
/api/transactions
curl --request POST \
  --url https://my.domain.io/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <MY_API_KEY>' \
  --header 'x-token: <MY_TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
  "amount": 4.00,
  "external_ref": "external_ref_order",
  "expires_in": 3600,
  "description": "opcional",
  "requester": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "11 99999-9999",
    "document": "124.682.390-08"
  },
  "payment_method": "Pix"
}'

Response

{
  "code": 201,
  "content": {
    "magic_id": "03UdoKvLNLHg",
    "amount": 4.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "opcional",
    "payment_method": "Pix",
    "qr_code": "00020101021126700014br.gov.bcb.pix...",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11 99999-9999",
      "document": "12468239008"
    },
    "external_ref": "external_ref_order",
    "created_at": "2025-12-10 15:21:24.420",
    "updated_at": "2025-12-10 15:21:24.420"
  },
  "message": "Transaction created",
  "timestamp": "2025-12-10T15:21:24.449407114Z"
}

2) Receive the webhook

At the provided webhook URL, you'll receive events with statuses like PENDING, CONFIRMED, or FAILED. Validate the x-webhook-signature header using an HMAC SHA256 of the payload.

Webhook headers

  • Name
    x-webhook-signature
    Type
    string
    Description

    Payload signed with your webhook secret.

  • Name
    x-webhook-event
    Type
    string
    Description

    Event type (e.g., TRANSACTION, WITHDRAW).

  • Name
    x-user-reference
    Type
    string
    Description

    Your user reference identifier.

Use magic_id or external_ref to idempotently process and reconcile webhook deliveries.

Webhook payload

{
  "data": {
    "amount": 4.00,
    "currency": "BRL",
    "status": "CONFIRMED",
    "magic_id": "03UdoKvLNLHg",
    "external_ref": "external_ref_order",
    "payment_method": "Pix",
    "end_to_end": "E123456789...",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11 99999-9999",
      "document": "12468239008"
    },
    "created_at": "2025-12-10T15:21:24.420Z",
    "updated_at": "2025-12-10T15:25:00.000Z"
  },
  "event": "TRANSACTION"
}

3) Query the transaction

Use the external_ref or magic_id to query the transaction status at any time.

Query parameters

  • Name
    magic_id
    Type
    string
    Description

    Internal transaction identifier.

  • Name
    external_ref
    Type
    string
    Description

    Your external reference.

  • Name
    status
    Type
    string
    Description

    Filter by status.

  • Name
    limit
    Type
    integer
    Description

    Max results (default: 20).

Request

GET
/api/transactions
curl --request GET \
  "https://my.domain.io/api/transactions?external_ref=external_ref_order" \
  --header 'x-api-key: <MY_API_KEY>' \
  --header 'x-token: <MY_TOKEN>'

Response

{
  "code": 200,
  "content": [
    {
      "magic_id": "03UdoKvLNLHg",
      "amount": 4.00,
      "currency": "BRL",
      "status": "CONFIRMED",
      "payment_method": "Pix",
      "external_ref": "external_ref_order",
      "created_at": "2025-12-10T15:21:24.420Z",
      "updated_at": "2025-12-10T15:25:00.000Z"
    }
  ],
  "message": "Transactions listed",
  "timestamp": "2025-12-10T15:30:00.000Z"
}

Next steps

Use the returned magic_id or external_ref to reconcile and query status.

Was this page helpful?