Zera

Guias

Cartão

Como cobrar um pedido de cartão e o que não pode ir para o log.

Cartão são duas chamadas: o pedido nasce com method: "credit_card" e o PAN segue em POST /api/v1/orders/{order_id}/pay-card. A resposta devolve o pedido, sem o número do cartão.

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

O pedido nasce com method credit_card e fica awaiting_payment. A resposta traz a grade installments para você mostrar as parcelas antes de cobrar. O PAN não entra nesta chamada.

POST/api/v1/orders

Responde 201.

{
  "debt_item_ids": [
    "99aa88bb-77cc-66dd-55ee-4433221100ff"
  ],
  "method": "credit_card"
}
{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "awaiting_payment",
  "method": "credit_card",
  "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": null,
  "installments": [
    {
      "months": 1,
      "installment_amount": "139.80",
      "total_amount": "139.80",
      "interest_amount": "0.00"
    }
  ]
}
{
  "info": {
    "name": "Zera — Criar pedido de cartã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": "Criar pedido de cartão",
      "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\": \"credit_card\"\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\": \"credit_card\"\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\": \"credit_card\",\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\": null,\n  \"installments\": [\n    {\n      \"months\": 1,\n      \"installment_amount\": \"139.80\",\n      \"total_amount\": \"139.80\",\n      \"interest_amount\": \"0.00\"\n    }\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

Cobre um pedido que nasceu como credit_card e ainda está awaiting_payment. O número abaixo é de teste. A resposta é o pedido, sem PAN, validade ou CVC.

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

Responde 200.

{
  "holder_name": "MARIA SILVA",
  "number": "4111111111111111",
  "expiry": "12/30",
  "cvc": "123",
  "installments": 1
}
{
  "id": "55ee44dd-33cc-22bb-11aa-009988776655",
  "status": "paying_detran",
  "method": "credit_card",
  "debts_amount": "129.90",
  "service_fee": "9.90",
  "total_amount": "139.80",
  "refunded_amount": "0.00",
  "latest_attempt": {
    "method": "credit_card",
    "status": "paid"
  }
}
{
  "info": {
    "name": "Zera — Pagar com cartã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": "Pagar com cartão",
      "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/{{orderId}}/pay-card",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"holder_name\": \"MARIA SILVA\",\n  \"number\": \"4111111111111111\",\n  \"expiry\": \"12/30\",\n  \"cvc\": \"123\",\n  \"installments\": 1\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [
        {
          "name": "200",
          "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/{{orderId}}/pay-card",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"holder_name\": \"MARIA SILVA\",\n  \"number\": \"4111111111111111\",\n  \"expiry\": \"12/30\",\n  \"cvc\": \"123\",\n  \"installments\": 1\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"id\": \"55ee44dd-33cc-22bb-11aa-009988776655\",\n  \"status\": \"paying_detran\",\n  \"method\": \"credit_card\",\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\": \"credit_card\",\n    \"status\": \"paid\"\n  }\n}"
        }
      ]
    }
  ]
}
paths:
  /api/v1/orders/{order_id}/pay-card:
    post:
      operationId: payOrderWithCard
      summary: Pagar pedido com cartão
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [holder_name, number, expiry, cvc]
              properties:
                holder_name:
                  type: string
                number:
                  type: string
                expiry:
                  type: string
                cvc:
                  type: string
                installments:
                  type: integer
                  minimum: 1
                  maximum: 12
                  default: 1
      responses:
        "200":
          description: Pedido após a tentativa. O PAN não volta.
        "409":
          description: Pedido fora de awaiting_payment ou method diferente de credit_card
        "429":
          description: Limite de 30 checkouts por hora

Corpo do pagamento

Campo Regra
holder_name Nome impresso, até 120 caracteres
number 13 a 19 dígitos. Espaços são ignorados
expiry MM/AA
cvc 3 ou 4 dígitos
installments Inteiro de 1 a 12. O padrão é 1

O pedido precisa estar awaiting_payment e ter nascido como credit_card. Caso contrário a API responde 409.

O pedido também devolve installments: a grade de parcelas calculada sobre total_amount, para você mostrar as opções antes do pay-card.

Boleto usa o mesmo POST /orders, com "method": "boleto". A linha digitável fica em latest_attempt.boleto_line e o PDF ou link em boleto_url, no mesmo ritmo de polling do Pix.