Client Api

Pagamentos

Endpoints para criar, listar, consultar e acompanhar status de pagamentos. O formato recomendado da Uway usa um payload enxuto com blocos opcionais `checkout`, `payment_options` e `payment_source`. Campos antigos em formato plano continuam aceitos por compatibilidade, mas a recomendacao e usar o shape simplificado daqui para frente. Pix e boleto seguem o mesmo fluxo padronizado; em cartao, o provider pode aceitar `card_token` ou dados brutos dependendo da capability da conta selecionada.

Todas as secoes

POST

Criar pagamento

/api/client/api/payments

Produção R$ 0,10 /req SANDBOX gratis

Cria um pagamento com roteamento inteligente, callback global configurado no api client, idempotencia, installments, split e suporte a reutilizacao de um customer ja cadastrado via `gateway_customer_id`. O formato recomendado e manter o corpo simples: dados principais na raiz, `checkout` para redirect, `payment_options` para parcelas/split e `payment_source` para cartao/token. Para cartao, o mesmo endpoint aceita `card_token` (cartao ja tokenizado) ou `card` + `holder` + `remote_ip` para cobranca direta quando o provider suportar. No Asaas, a cobranca direta com os dados do cartao e suportada. No Mercado Pago, o fluxo recomendado e usar `card_token`, pois a tokenizacao pertence ao modelo do provider.

Pix Request

Sucesso Response

{
  "message": "Pagamento criado com sucesso.",
  "payment": {
    "id": "uuid",
    "api_client_id": "uuid",
    "gateway_account_id": "uuid",
    "provider": "asaas",
    "provider_meta": {
      "label": "Asaas"
    },
    "reference": "pay_1001",
    "status": "pending",
    "status_meta": {
      "label": "Pendente"
    },
    "payment_method": "pix",
    "payment_method_meta": {
      "label": "Pix"
    },
    "idempotency_key": "payment-order-1001",
    "external_id": "ext_pay_123",
    "external_reference": "order_1001",
    "currency": "BRL",
    "amount": 150.75,
    "fee": 0,
    "net_amount": 150.75,
    "customer": {
      "name": "Carlos Silva",
      "email": "cliente@uway.com.br"
    },
    "callback_url": "https://cliente.com/callbacks/gateway",
    "checkout": {},
    "metadata": {
      "order_id": "1001"
    },
    "paid_at": null,
    "failed_at": null,
    "failure_reason": null,
    "created_at": "2026-03-07T15:00:00-03:00",
    "updated_at": "2026-03-07T15:00:00-03:00"
  },
  "routing": {
    "rule": "pix_default",
    "matched_provider": "asaas",
    "gateway_account_id": "uuid",
    "attempt_errors": []
  },
  "idempotent_replay": false
}

Erros comuns

billing.insufficient_balance A carteira do usuario nao possui saldo suficiente para operacoes em production.
gateway_customer.not_found O `gateway_customer_id` informado nao pertence ao api client autenticado.
gateway_customer.provider_conflict O provider informado conflita com o customer reutilizado.
gateway_customer.gateway_account_conflict A conta de gateway informada conflita com a conta do customer reutilizado.
gateway.provider_validation_failed Quando o provider exigir dados adicionais para cobranca com cartao, envie `card_token` ou o bloco `card` conforme a compatibilidade da conta e do gateway selecionado.
gateway.unavailable Nenhum provider ativo conseguiu processar a cobranca.
request.duplicated A mesma idempotency_key foi enviada em uma requisicao ainda em processamento.

GET

Listar pagamentos

/api/client/api/payments

Produção R$ 0,01 /req SANDBOX gratis

Retorna a lista paginada dos pagamentos do api client.

Sucesso Response

GET

Consultar pagamento

/api/client/api/payments/{payment}

Produção R$ 0,02 /req SANDBOX gratis

Busca um pagamento pelo uuid ou reference.

Sucesso Response

GET

Consultar status

/api/client/api/payments/{payment}/status

Produção R$ 0,02 /req SANDBOX gratis

Sincroniza e retorna o status atual do pagamento.

Sucesso Response

GET

Consultar QR Code Pix

/api/client/api/payments/{payment}/pix-qrcode

Produção R$ 0,02 /req SANDBOX gratis

Retorna o QR Code Pix atualizado da cobranca, incluindo imagem codificada e payload copia e cola.

Sucesso Response

GET

Consultar boleto

/api/client/api/payments/{payment}/bank-slip

Produção R$ 0,02 /req SANDBOX gratis

Retorna PDF/URL do boleto, invoice URL, linha digitavel e codigo de barras da cobranca.

Sucesso Response

POST

Criar refund para pagamento

/api/client/api/payments/{payment}/refunds

Solicita estorno total ou parcial de um pagamento existente.

Request

Sucesso Response