City

Documentação

API Pública v1

Ir para início

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-07-10",
    "name": "Cliente Teste",
    "email": "cliente@teste.com",
    "documentType": "CPF",
    "documentNumber": "12345678901",
    "fineAmount": 2,
    "fineType": "valor_fixo", // valor_fixo ou percentual
    "interestAmount": 1,
    "interestType": "valor_dia", // valor_dia ou percentual
    "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://...",
  "pix": "pix_copia_e_cola"
}

Tipos aceitos no boleto avulso

fineType

Tipo da multa. Aceita valor_fixo ou percentual. Padrão: valor_fixo.

interestType

Tipo da mora. Aceita valor_dia ou percentual. Padrão: valor_dia.

price, fineAmount e interestAmount aceitam somente número. Para interestType: valor_dia, a mora diária multiplicada por 30 não pode passar de 60% do valor do boleto.

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"
}

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
{
  "event": "ticket.created",
  "data": {
    "id": "ticket_id",
    "reference": "inter_ref",
    "price": 100,
    "dueDate": "30/05/2026",
    "status": "pending",
    "pdf": "https://..."
  }
}

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 provider invalid
O meio de pagamento boleto recusou os dados.
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.

Tratamento de erro em boleto

message é a mensagem legível, paymentMethod indica o meio de pagamento e details[] aparece quando houver campo, motivo e valor rejeitado.

{
  "error": "ticket provider invalid",
  "message": "dueDate: O valor deve ser igual ou maior à data atual (valor: 2026-05-30)",
  "paymentMethod": "boleto",
  "details": [
    {
      "field": "dueDate",
      "message": "O valor deve ser igual ou maior à data atual",
      "value": "2026-05-30"
    }
  ]
}
{
  "error": "ticket provider invalid",
  "message": "boleto: Não foi possível processar o boleto agora. Tente novamente mais tarde.",
  "paymentMethod": "boleto"
}

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.