Guias

Pix

Como exibir o Pix, esperar o pagamento e saber que o débito foi liquidado.

Crie o pedido com "method": "pix". A cobrança fica em latest_attempt (e também na lista attempts). Os exemplos usam o mesmo pedido do começo ao fim.

No Postman, abra Import → Raw text e cole o JSON da aba Postman. Troque apiKey pela chave da marca. A aba OpenAPI é um trecho para colar em paths.

Passo a passo

Abra o pedido com method pix. A resposta 201 pode já trazer o copia e cola em latest_attempt. Guarde o id do pedido.

POST/api/v1/orders

Responde 201.

{
  "debt_item_ids": [
    "99aa88bb-77cc-66dd-55ee-4433221100ff"
  ],
  "method": "pix"
}

{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "awaiting_payment",
  "method": "pix",
  "purpose": "debts",
  "plate": "ABC1D23",
  "uf": "SP",
  "vehicle_id": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e",
  "debts_amount": "129.90",
  "service_fee": "9.90",
  "total_amount": "139.80",
  "refunded_amount": "0.00",
  "latest_attempt": {
    "method": "pix",
    "status": "pending",
    "pix_copy_paste": "00020126360014BR.GOV.BCB.PIX",
    "pix_expires_at": "2026-10-20T12:31:00-03:00"
  }
}

{
  "info": {
    "name": "Zera — Criar pedido Pix",
    "description": "Importe em Postman: Import, Raw text, e cole este JSON. Troque apiKey pela chave da marca.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.zera.mobi"
    },
    {
      "key": "apiKey",
      "value": "zera_live_SUBSTITUA"
    },
    {
      "key": "accountId",
      "value": "4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f"
    },
    {
      "key": "vehicleId",
      "value": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e"
    },
    {
      "key": "consultationId",
      "value": "11aa22bb-33cc-44dd-55ee-66ff77889900"
    },
    {
      "key": "orderId",
      "value": "55ee44dd-33cc-22bb-11aa-009988776655"
    }
  ],
  "item": [
    {
      "name": "Criar pedido Pix",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "X-Api-Key",
            "value": "{{apiKey}}"
          },
          {
            "key": "X-Account-Id",
            "value": "{{accountId}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{baseUrl}}/api/v1/orders",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"debt_item_ids\": [\n    \"99aa88bb-77cc-66dd-55ee-4433221100ff\"\n  ],\n  \"method\": \"pix\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [
        {
          "name": "201",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "X-Api-Key",
                "value": "{{apiKey}}"
              },
              {
                "key": "X-Account-Id",
                "value": "{{accountId}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/orders",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"debt_item_ids\": [\n    \"99aa88bb-77cc-66dd-55ee-4433221100ff\"\n  ],\n  \"method\": \"pix\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "status": "Created",
          "code": 201,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"id\": \"55ee44dd-33cc-22bb-11aa-009988776655\",\n  \"status\": \"awaiting_payment\",\n  \"method\": \"pix\",\n  \"purpose\": \"debts\",\n  \"plate\": \"ABC1D23\",\n  \"uf\": \"SP\",\n  \"vehicle_id\": \"8c1d9e2a-7b34-4f10-9a11-22b33c44d55e\",\n  \"debts_amount\": \"129.90\",\n  \"service_fee\": \"9.90\",\n  \"total_amount\": \"139.80\",\n  \"refunded_amount\": \"0.00\",\n  \"latest_attempt\": {\n    \"method\": \"pix\",\n    \"status\": \"pending\",\n    \"pix_copy_paste\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_expires_at\": \"2026-10-20T12:31:00-03:00\"\n  }\n}"
        }
      ]
    }
  ]
}

paths:
  /api/v1/orders:
    post:
      operationId: createOrder
      summary: Criar pedido
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [debt_item_ids, method]
              properties:
                debt_item_ids:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: uuid
                method:
                  type: string
                  enum: [pix, boleto, credit_card]
      responses:
        "201":
          description: Pedido criado
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum: [awaiting_payment, paying_detran, paid, partial, failed, needs_review, refunded]
                  total_amount:
                    type: string
                  latest_attempt:
                    type: object
                    nullable: true
        "429":
          description: Limite de 30 checkouts por hora

Se o POST ainda não trouxe pix_copy_paste, leia o pedido até o campo aparecer ou o pedido falhar. Estes são os dados da tela de pagamento.

GET/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655

Responde 200.

GET https://api.zera.mobi/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655
X-Api-Key: zera_live_...
X-Account-Id: 4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f

Sem corpo.

{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "awaiting_payment",
  "method": "pix",
  "total_amount": "139.80",
  "latest_attempt": {
    "method": "pix",
    "status": "pending",
    "pix_copy_paste": "00020126360014BR.GOV.BCB.PIX",
    "pix_qr_code": "00020126360014BR.GOV.BCB.PIX",
    "pix_qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\"/>",
    "pix_expires_at": "2026-10-20T12:31:00-03:00"
  }
}

{
  "info": {
    "name": "Zera — Ler cobrança Pix",
    "description": "Importe em Postman: Import, Raw text, e cole este JSON. Troque apiKey pela chave da marca.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.zera.mobi"
    },
    {
      "key": "apiKey",
      "value": "zera_live_SUBSTITUA"
    },
    {
      "key": "accountId",
      "value": "4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f"
    },
    {
      "key": "vehicleId",
      "value": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e"
    },
    {
      "key": "consultationId",
      "value": "11aa22bb-33cc-44dd-55ee-66ff77889900"
    },
    {
      "key": "orderId",
      "value": "55ee44dd-33cc-22bb-11aa-009988776655"
    }
  ],
  "item": [
    {
      "name": "Ler cobrança Pix",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-Api-Key",
            "value": "{{apiKey}}"
          },
          {
            "key": "X-Account-Id",
            "value": "{{accountId}}"
          }
        ],
        "url": "{{baseUrl}}/api/v1/orders/{{orderId}}"
      },
      "response": [
        {
          "name": "200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "X-Api-Key",
                "value": "{{apiKey}}"
              },
              {
                "key": "X-Account-Id",
                "value": "{{accountId}}"
              }
            ],
            "url": "{{baseUrl}}/api/v1/orders/{{orderId}}"
          },
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"id\": \"55ee44dd-33cc-22bb-11aa-009988776655\",\n  \"status\": \"awaiting_payment\",\n  \"method\": \"pix\",\n  \"total_amount\": \"139.80\",\n  \"latest_attempt\": {\n    \"method\": \"pix\",\n    \"status\": \"pending\",\n    \"pix_copy_paste\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_qr_code\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_qr_svg\": \"<svg xmlns=\\\"http://www.w3.org/2000/svg\\\"/>\",\n    \"pix_expires_at\": \"2026-10-20T12:31:00-03:00\"\n  }\n}"
        }
      ]
    }
  ]
}

paths:
  /api/v1/orders/{order_id}:
    get:
      operationId: getOrder
      summary: Ler pedido
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Pedido, itens e última tentativa
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [awaiting_payment, paying_detran, paid, partial, failed, needs_review, refunded]
                  total_amount:
                    type: string
                  latest_attempt:
                    type: object
                    nullable: true
                    properties:
                      pix_copy_paste:
                        type: string
                      pix_qr_code:
                        type: string
                      pix_qr_svg:
                        type: string
                      pix_expires_at:
                        type: string
                        format: date-time
                        nullable: true
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        liquidation_status:
                          type: string
                          enum: [pending, paid, failed, refunded]

Continue no GET, ou espere o webhook order.status_changed, até paid, partial, failed, needs_review ou refunded. Cada item traz liquidation_status.

GET/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655

Responde 200.

GET https://api.zera.mobi/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655
X-Api-Key: zera_live_...
X-Account-Id: 4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f

Sem corpo.

{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "paid",
  "method": "pix",
  "purpose": "debts",
  "plate": "ABC1D23",
  "uf": "SP",
  "vehicle_id": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e",
  "debts_amount": "129.90",
  "service_fee": "9.90",
  "total_amount": "139.80",
  "refunded_amount": "0.00",
  "review_reason": "",
  "items": [
    {
      "id": "bb22cc33-dd44-ee55-ff66-77889900aabb",
      "debt_item": "99aa88bb-77cc-66dd-55ee-4433221100ff",
      "description": "IPVA 2026",
      "amount": "129.90",
      "liquidation_status": "paid",
      "liquidation_error": ""
    }
  ],
  "latest_attempt": {
    "method": "pix",
    "status": "paid",
    "pix_copy_paste": "00020126360014BR.GOV.BCB.PIX",
    "pix_expires_at": "2026-10-20T12:31:00-03:00"
  }
}

{
  "info": {
    "name": "Zera — Ler liquidação",
    "description": "Importe em Postman: Import, Raw text, e cole este JSON. Troque apiKey pela chave da marca.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.zera.mobi"
    },
    {
      "key": "apiKey",
      "value": "zera_live_SUBSTITUA"
    },
    {
      "key": "accountId",
      "value": "4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f"
    },
    {
      "key": "vehicleId",
      "value": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e"
    },
    {
      "key": "consultationId",
      "value": "11aa22bb-33cc-44dd-55ee-66ff77889900"
    },
    {
      "key": "orderId",
      "value": "55ee44dd-33cc-22bb-11aa-009988776655"
    }
  ],
  "item": [
    {
      "name": "Ler liquidação",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-Api-Key",
            "value": "{{apiKey}}"
          },
          {
            "key": "X-Account-Id",
            "value": "{{accountId}}"
          }
        ],
        "url": "{{baseUrl}}/api/v1/orders/{{orderId}}"
      },
      "response": [
        {
          "name": "200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "X-Api-Key",
                "value": "{{apiKey}}"
              },
              {
                "key": "X-Account-Id",
                "value": "{{accountId}}"
              }
            ],
            "url": "{{baseUrl}}/api/v1/orders/{{orderId}}"
          },
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"id\": \"55ee44dd-33cc-22bb-11aa-009988776655\",\n  \"status\": \"paid\",\n  \"method\": \"pix\",\n  \"purpose\": \"debts\",\n  \"plate\": \"ABC1D23\",\n  \"uf\": \"SP\",\n  \"vehicle_id\": \"8c1d9e2a-7b34-4f10-9a11-22b33c44d55e\",\n  \"debts_amount\": \"129.90\",\n  \"service_fee\": \"9.90\",\n  \"total_amount\": \"139.80\",\n  \"refunded_amount\": \"0.00\",\n  \"review_reason\": \"\",\n  \"items\": [\n    {\n      \"id\": \"bb22cc33-dd44-ee55-ff66-77889900aabb\",\n      \"debt_item\": \"99aa88bb-77cc-66dd-55ee-4433221100ff\",\n      \"description\": \"IPVA 2026\",\n      \"amount\": \"129.90\",\n      \"liquidation_status\": \"paid\",\n      \"liquidation_error\": \"\"\n    }\n  ],\n  \"latest_attempt\": {\n    \"method\": \"pix\",\n    \"status\": \"paid\",\n    \"pix_copy_paste\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_expires_at\": \"2026-10-20T12:31:00-03:00\"\n  }\n}"
        }
      ]
    }
  ]
}

paths:
  /api/v1/orders/{order_id}:
    get:
      operationId: getOrder
      summary: Ler pedido
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Pedido, itens e última tentativa
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [awaiting_payment, paying_detran, paid, partial, failed, needs_review, refunded]
                  total_amount:
                    type: string
                  latest_attempt:
                    type: object
                    nullable: true
                    properties:
                      pix_copy_paste:
                        type: string
                      pix_qr_code:
                        type: string
                      pix_qr_svg:
                        type: string
                      pix_expires_at:
                        type: string
                        format: date-time
                        nullable: true
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        liquidation_status:
                          type: string
                          enum: [pending, paid, failed, refunded]

Se o código venceu e o pedido ainda está awaiting_payment, gere outra cobrança. Não crie um pedido novo para o mesmo débito.

POST/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655/pix

Responde 200.

POST https://api.zera.mobi/api/v1/orders/55ee44dd-33cc-22bb-11aa-009988776655/pix
X-Api-Key: zera_live_...
X-Account-Id: 4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f

Sem corpo.

{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "awaiting_payment",
  "method": "pix",
  "total_amount": "139.80",
  "latest_attempt": {
    "method": "pix",
    "status": "pending",
    "pix_copy_paste": "00020126360014BR.GOV.BCB.PIX",
    "pix_qr_code": "00020126360014BR.GOV.BCB.PIX",
    "pix_qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\"/>",
    "pix_expires_at": "2026-10-20T13:01:00-03:00"
  }
}

{
  "info": {
    "name": "Zera — Reapresentar Pix",
    "description": "Importe em Postman: Import, Raw text, e cole este JSON. Troque apiKey pela chave da marca.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.zera.mobi"
    },
    {
      "key": "apiKey",
      "value": "zera_live_SUBSTITUA"
    },
    {
      "key": "accountId",
      "value": "4b6e0c2a-1d4f-4a8b-9c3e-1a2b3c4d5e6f"
    },
    {
      "key": "vehicleId",
      "value": "8c1d9e2a-7b34-4f10-9a11-22b33c44d55e"
    },
    {
      "key": "consultationId",
      "value": "11aa22bb-33cc-44dd-55ee-66ff77889900"
    },
    {
      "key": "orderId",
      "value": "55ee44dd-33cc-22bb-11aa-009988776655"
    }
  ],
  "item": [
    {
      "name": "Reapresentar Pix",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "X-Api-Key",
            "value": "{{apiKey}}"
          },
          {
            "key": "X-Account-Id",
            "value": "{{accountId}}"
          }
        ],
        "url": "{{baseUrl}}/api/v1/orders/{{orderId}}/pix"
      },
      "response": [
        {
          "name": "200",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "X-Api-Key",
                "value": "{{apiKey}}"
              },
              {
                "key": "X-Account-Id",
                "value": "{{accountId}}"
              }
            ],
            "url": "{{baseUrl}}/api/v1/orders/{{orderId}}/pix"
          },
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"id\": \"55ee44dd-33cc-22bb-11aa-009988776655\",\n  \"status\": \"awaiting_payment\",\n  \"method\": \"pix\",\n  \"total_amount\": \"139.80\",\n  \"latest_attempt\": {\n    \"method\": \"pix\",\n    \"status\": \"pending\",\n    \"pix_copy_paste\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_qr_code\": \"00020126360014BR.GOV.BCB.PIX\",\n    \"pix_qr_svg\": \"<svg xmlns=\\\"http://www.w3.org/2000/svg\\\"/>\",\n    \"pix_expires_at\": \"2026-10-20T13:01:00-03:00\"\n  }\n}"
        }
      ]
    }
  ]
}

paths:
  /api/v1/orders/{order_id}/pix:
    post:
      operationId: refreshPix
      summary: Reapresentar Pix
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Pedido com a cobrança Pix vigente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  latest_attempt:
                    type: object
                    properties:
                      pix_copy_paste:
                        type: string
                      pix_qr_code:
                        type: string
                      pix_expires_at:
                        type: string
                        format: date-time
                        nullable: true
        "409":
          description: O pedido não é Pix ou não aguarda pagamento

Campos para a tela de pagamento

Campo	Uso
`latest_attempt.pix_copy_paste`	Código copia e cola
`latest_attempt.pix_qr_code`	Payload do QR, quando vier separado
`latest_attempt.pix_qr_svg`	SVG do QR, quando a API já renderiza
`latest_attempt.pix_expires_at`	Validade do código
`total_amount`	Valor que o cliente paga, já com a taxa de serviço

Se a primeira resposta do POST /orders ainda não tiver o copia e cola, leia GET /api/v1/orders/{order_id} até o campo aparecer ou o pedido falhar.

Status do pedido

awaiting_paymentMostre o Pix e continue lendo.
paying_detranPago. A baixa está em curso.
paidLiquidado.

partialSó parte dos itens liquidou.
failedNão concluiu.
needs_reviewLeia review_reason.
refundedCompare refunded_amount.

status	O que fazer
`awaiting_payment`	Mostrar o Pix e continuar lendo o pedido
`paying_detran`	Pagamento recebido; liquidação em curso
`paid`	Liquidado
`partial`	Parte dos itens liquidou
`failed`	Não concluiu
`needs_review`	A Zera segurou o pedido para revisão. Leia `review_reason`
`refunded`	Estornado. Compare `refunded_amount` com `total_amount`

Cada item do pedido tem liquidation_status e, quando a baixa não fecha, liquidation_error com uma frase pronta para suporte.

Aviso ao seu backend

Se a marca tiver webhook ativo, a Zera envia order.status_changed a cada mudança de status. O guia de webhooks mostra como validar a assinatura. O polling do GET continua válido se a entrega do webhook falhar.

A aba Renovar é o POST /api/v1/orders/{order_id}/pix. Use essa chamada quando o código vencer. Não crie outro pedido para o mesmo débito só para gerar um QR novo.