API Pública v1 • City Pay

Documentação

API Pública v1

Visão Geral

Todos os endpoints públicos começam com /v1.

Base URL: https://api.citypay.com.br

A API pública opera por empresa e usa a mesma lógica interna da dashboard. Tudo que for criado/alterado via API aparece na UI: links, boletos, extrato, saldo e movimentações.

Autenticação

Use API key única da empresa.

Envie em x-api-key ou Authorization: Bearer <token>.

curl -X GET 'https://api.citypay.com.br/v1/payment-links?page=1' \
  -H 'x-api-key: cp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'

A API key é configurada na dashboard da empresa em Configurações > Integrações.

Payouts

Compliance não intervém na API pública /v1.

POST/v1/payout/pix

Realiza pagamento via Pix.

curl -X POST 'https://api.citypay.com.br/v1/payout/pix' \
  -H 'x-api-key: cp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "key",
    "key": "email@destino.com",
    "amount": 120.50
  }'

Exemplo de sucesso

{
  "balance": 875.4,
  "history": {
    "id": "mov_id",
    "name": "Pix enviado",
    "status": "realized",
    "reference": "inter_ref"
  }
}

Exemplo de erro

{
  "error": "this account does not have sufficient funds"
}

POST/v1/payout/ticket

Realiza pagamento por código de barras.

curl -X POST 'https://api.citypay.com.br/v1/payout/ticket' \
  -H 'x-api-key: cp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "34191790010104351004791020150008291770026000",
    "amount": 260.00,
    "dueDate": "20/05/2026"
  }'

Exemplo de sucesso

{
  "balance": 1530.2,
  "history": {
    "id": "mov_id",
    "name": "Pagamento de Boleto",
    "status": "processing"
  }
}

Exemplo de erro

{
  "error": "your code not is valid"
}

POST/v1/payout/transfer-city

Transferência entre empresas City.

curl -X POST 'https://api.citypay.com.br/v1/payout/transfer-city' \
  -H 'x-api-key: cp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "12.345.678/0001-90",
    "amount": 300.00,
    "description": "Repasse operacional"
  }'

Exemplo de sucesso

{
  "balance": 1100.0,
  "history": {
    "name": "Transferência City enviada",
    "status": "realized",
    "reference": "transfer_uuid"
  }
}

Exemplo de erro

{
  "error": "this destination business not exists"
}

Boletos Avulsos

Criar, listar e deletar tickets avulsos.

GET/v1/tickets?page=1&status=pending

Lista boletos avulsos com paginação e filtros.

curl -X GET 'https://api.citypay.com.br/v1/tickets?page=1&status=pending' \
  -H 'x-api-key: cp_live_xxx'

Exemplo de sucesso

{
  "totalPages": 3,
  "page": 1,
  "totalItems": 52,
  "data": []
}

POST/v1/tickets

Cria boleto avulso com mora/multa.

curl -X POST 'https://api.citypay.com.br/v1/tickets' \
  -H 'x-api-key: cp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "price": 100,
    "dueDate": "2026-05-30",
    "name": "Cliente Teste",
    "email": "cliente@teste.com",
    "documentType": "CPF",
    "documentNumber": "12345678901",
    "fineAmount": 2,
    "fineType": "valor_fixo",
    "interestAmount": 1,
    "interestType": "valor_dia",
    "description": "Boleto via API",
    "address": {
      "streetName": "Rua A",
      "streetNumber": "100",
      "zipCode": "97010500",
      "neighborhood": "Centro",
      "state": "Rio Grande do Sul",
      "stateCode": "RS",
      "city": "Santa Maria"
    }
  }'

Exemplo de sucesso

{
  "id": "ticket_id",
  "reference": "inter_ref",
  "status": "pending",
  "price": 100,
  "copy": "linha_digitavel",
  "barcode": "codigo_barras",
  "pdf": "https://..."
}

DELETE/v1/tickets/:id

Deleta boleto avulso pendente.

curl -X DELETE 'https://api.citypay.com.br/v1/tickets/TICKET_ID' \
  -H 'x-api-key: cp_live_xxx'

Exemplo de sucesso

{}

Exemplo de erro

{
  "error": "ticket cannot delete"
}

Links de Pagamento

Criar, listar e deletar links.

GET/v1/payment-links?page=1

Lista links de pagamento.

curl -X GET 'https://api.citypay.com.br/v1/payment-links?page=1' \
  -H 'x-api-key: cp_live_xxx'

Exemplo de sucesso

{
  "page": 1,
  "totalPages": 2,
  "total": 25,
  "data": []
}

POST/v1/payment-links

Cria link com os mesmos campos da dashboard.

curl -X POST 'https://api.citypay.com.br/v1/payment-links' \
  -H 'x-api-key: cp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Link Produto A",
    "price": 150,
    "expirationDays": 7,
    "installments": 12,
    "withCard": true,
    "withPix": true,
    "withTicket": true,
    "ticketFineAmount": 2,
    "ticketFineType": "valor_fixo",
    "ticketInterestAmount": 1,
    "ticketInterestType": "valor_dia"
  }'

Exemplo de sucesso

{
  "id": "link_id",
  "name": "Link Produto A",
  "status": "pending",
  "price": 150,
  "withCard": true,
  "withPix": true,
  "withTicket": true
}

DELETE/v1/payment-links/:id

Deleta link de pagamento.

curl -X DELETE 'https://api.citypay.com.br/v1/payment-links/LINK_ID' \
  -H 'x-api-key: cp_live_xxx'

Exemplo de sucesso

{
  "id": "link_id",
  "status": "pending"
}

Webhooks

Endpoint único para todos os eventos da empresa.

Configure URL única no painel da empresa. Payload base:

{
  "id": "uuid",
  "event": "ticket.created",
  "createdAt": "2026-04-13T18:40:22.100Z",
  "businessId": "business_id",
  "data": {}
}

Eventos de boleto avulso

ticket.created
ticket.expired
ticket.paid
ticket.deleted

Eventos de link

payment_link.created
payment_link.expired
payment_link.deleted
payment_link.paid

Eventos de payout

payout.succeeded
payout.failed

{
  "event": "payout.failed",
  "data": {
    "method": "ticket",
    "reason": "payout error"
  }
}

Erros Possíveis

Mapa de erros retornados pela API /v1.

Comuns

Status

Erro

Quando acontece

401

you not have permission for to follow

API key ausente, inválida, empresa rejeitada/pendente ou sem permissão.

400

this data is invalid

Body/query inválido ou campo obrigatório faltando.

400

service pix payout disabled

Admin desativou payout Pix em manutenção.

400

service ticket payout disabled

Admin desativou payout por código de barras em manutenção.

400

service city transfer disabled

Admin desativou transferência City em manutenção.

Payouts

Status

Erro

Quando acontece

400

this account does not have sufficient funds

Saldo insuficiente na empresa.

400

amount must be greater than payout fee

Valor menor/igual à taxa fixa de envio configurada.

400

your pix key is invalid

Chave Pix inválida no provedor.

400

your pix amount is mismatch

Valor Pix recusado pelo provedor.

400

this payout is declined

Pagamento recusado pelo provedor.

400

your code not is valid

Código de barras inválido.

400

your due date not is valid

Data de vencimento inválida para pagamento de boleto.

400

please retry in other time

Horário não permitido pelo provedor para essa operação.

400

this destination business not exists

Destino City não encontrado pelo CNPJ.

400

you cannot transfer to the same business

Tentativa de transferir para a própria empresa.

400

this destination business is not active

Empresa destino City não está aceita.

Boletos avulsos

Status

Erro

Quando acontece

400

this data is invalid

Campos obrigatórios inválidos no create/list/delete.

400

ticket cancel failed on provider

Falha ao cancelar boleto no Banco Inter.

400

ticket cannot delete

Boleto não está pendente (pago/expirado) e não pode ser deletado.

Links de pagamento

Status

Erro

Quando acontece

400

this data is invalid

Body inválido no create/list/delete.

400

this payment not exists

Link de pagamento não encontrado para exclusão.