Pular para o conteúdo

Docs Buscar na documentação

Criar pagamento

POSThttps://api.zwaybr.com/api/v1/payments

Uma rota para todas as moedas e métodos: currency e paymentMethod decidem o fluxo. Os campos exigidos mudam conforme o método.

Body

Corpo da requisição em JSON.

currencystringobrigatório
Moeda do pagamento (ISO 4217): BRL, MXN…
paymentMethodstringobrigatório
Método de pagamento da moeda escolhida.
amountintegerobrigatório
Valor em centavos da moeda (inteiro). R$ 99,90 = 9990.
namestringobrigatório
Nome completo do pagador.
emailstringobrigatório
E-mail do pagador.
document.typestringobrigatório
Tipo do documento: cpf ou cnpj (BRL), rfc (México)…
document.numberstringobrigatório
Número do documento.
phonestringobrigatório
Telefone do pagador (8 a 12 dígitos no Brasil).
itemsarrayobrigatório
Itens: title, unitPrice (centavos) e quantity.
externalIdstring
O id do pedido no seu sistema. Volta na consulta e no webhook.
postbackUrlstring
URL https para receber o status desta cobrança.

Headers

Authorization: Bearer $ZWAY_API_KEY — obrigatório.
Idempotency-Key — recomendado: repetir o pedido com a mesma chave nunca cobra duas vezes. Fora do Brasil, sem ele, o externalId vale como chave.

Linguagem

Shell

curl --request POST \
  --url https://api.zwaybr.com/api/v1/payments \
  --header "Authorization: Bearer $ZWAY_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-0001-tentativa-1' \
  --data '{
  "currency": "BRL",
  "paymentMethod": "PIX",
  "amount": 9990,
  "name": "Maria Souza",
  "email": "[email protected]",
  "document": {
    "type": "cpf",
    "number": "12345678909"
  },
  "phone": "11999999999",
  "items": [
    {
      "title": "Plano Pro",
      "unitPrice": 9990,
      "quantity": 1
    }
  ]
}'

Resposta 200

{
  "id": "zw_1760000000000_ab12cd34",
  "externalId": "pedido-0001",
  "status": "PENDING",
  "method": "PIX",
  "currency": "BRL",
  "amount": 9990,
  "pix": {
    "qrCode": "00020101021226…6304ABCD"
  },
  "timestamps": {
    "expiresAt": "2026-10-13T15:00:00.000Z",
    "createdAt": "2026-10-12T15:00:00.000Z",
    "updatedAt": "2026-10-12T15:00:00.000Z"
  }
}

Resposta 400

{
  "error": true,
  "code": "VALIDATION_ERROR",
  "message": "Dados inválidos",
  "details": [
    {
      "field": "email",
      "message": "Invalid email"
    }
  ],
  "timestamp": "2026-10-12T15:00:00.000Z"
}

Resposta 401

{
  "error": "Unauthorized",
  "code": "AUTH_FAILED",
  "message": "Chave de API inválida"
}

Resposta 422

{
  "error": true,
  "code": "IDEMPOTENCY_KEY_REUSED",
  "message": "Idempotency-Key (ou externalId) já usada com outro pedido",
  "timestamp": "2026-10-12T15:00:00.000Z"
}