Documentação da API

Visão geral

A API da PayFy é REST: você envia e recebe JSON por HTTPS. Tudo parte de um endereço base:

Endereço base

https://payfy.club

🔑

Autenticar

Troque suas credenciais por um token de acesso.

⚡

Receber por Pix

Crie uma cobrança e receba o QR Code / Pix copia e cola.

💸

Enviar dinheiro

Faça transferências Pix para qualquer chave.

📊

Consultar

Veja saldo, cobranças e transferências a qualquer momento.

🔔

Ser avisado

Receba um webhook assim que o status mudar.

Comece em 3 passos

Do zero até a primeira cobrança Pix.

Pegue o tokenChame POST /auth com seu clientId e clientSecret. A resposta traz o token.
Use o token em todas as outras chamadasEnvie o header Authorization: Bearer SEU_TOKEN.
Crie sua primeira cobrançaChame POST /order e mostre o pixCopiaECola (ou o QR Code) para o seu cliente pagar.

💡

Quer testar rápido? Use webhook.site como URL de webhook e acompanhe os avisos chegando em tempo real.

Autenticação e segurança

Dois cuidados simples mantêm sua integração protegida.

1. Token de acesso (Bearer)

Todos os endpoints, exceto /auth, exigem o header abaixo. O token tem validade limitada (a data aparece no campo expires da resposta). Quando expirar, gere outro com /auth.

Header

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

2. Assinatura das chamadas (headers de segurança)

Nossa borda valida cada chamada à API. Existem duas formas de ser liberado: IP autorizado (combinado com a PayFy) ou assinatura HMAC, enviando os 3 headers abaixo:

Header	O que enviar
`X-ClientId`	O mesmo `clientId` usado no `/auth`.
`X-Timestamp`	Hora atual em milissegundos (Unix, ex.: `1761600000000`). Aceitamos uma diferença de até 5 minutos.
`X-Signature`	`Base64( HMAC-SHA256( X-Timestamp + X-ClientId , chaveHmac ) )` A `chaveHmac` é uma chave própria para assinatura, fornecida pela PayFy junto com o `clientId`.

Node.js

const crypto = require('crypto');

const clientId = 'SEU_CLIENT_ID';
const secret   = 'SUA_CHAVE_HMAC';
const ts = Date.now().toString(); // milissegundos

const signature = crypto
  .createHmac('sha256', secret)
  .update(ts + clientId)
  .digest('base64');

Bash (openssl)

CLIENT_ID="SEU_CLIENT_ID"
SECRET="SUA_CHAVE_HMAC"
TS=$(date +%s%3N)   # milissegundos

SIG=$(printf "%s%s" "$TS" "$CLIENT_ID" \
  | openssl dgst -sha256 -hmac "$SECRET" -binary \
  | base64)

🔒

Nunca coloque o clientSecret em aplicativos de celular, sites (JavaScript no navegador) ou repositórios públicos. Use sempre no seu servidor.

Endpoints

Tudo que você pode fazer, em um só lugar.

Método	Rota	Para quê
POST	`/auth`	Obter o token de acesso
POST	`/order`	Criar uma cobrança Pix
POST	`/transfer`	Enviar um Pix (transferência)
GET	`/balance`	Consultar seu saldo
GET	`/order/byId/{id}`	Consultar cobrança pelo ID da PayFy
GET	`/order/externalid/{externalid}`	Consultar cobrança pelo seu código
GET	`/transfer/{id}`	Consultar transferência pelo ID da PayFy
GET	`/transfer/externalid/{id}`	Consultar transferência pelo seu código

Autenticar

Troque suas credenciais por um token.

POST/authNão precisa de token

Corpo da requisição

Campo	Tipo	Descrição
`clientId`obrigatório	texto	Identificador da sua empresa, fornecido pela PayFy.
`clientSecret`obrigatório	texto	Segredo da sua empresa, fornecido pela PayFy. Guarde com cuidado.

cURL

curl -X POST https://payfy.club/auth \
  -H "Content-Type: application/json" \
  -H "X-ClientId: SEU_CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d '{
    "clientId": "SEU_CLIENT_ID",
    "clientSecret": "SEU_CLIENT_SECRET"
  }'

Resposta 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires": "2026-10-26T18:30:00Z"
}

ℹ️

Pode reutilizar o mesmo token até expires. Não é preciso autenticar a cada chamada.

Criar cobrança Pix

Gere um Pix para o seu cliente pagar.

POST/orderRequer Bearer token

Corpo da requisição

Os dados ficam dentro do objeto order.

Campo	Tipo	Descrição
`order.externalId`obrigatório	texto	Seu código único do pedido. Use para consultar depois e evitar duplicidade.
`order.amount`obrigatório	número	Valor em reais. Ex.: `2.00` = R$ 2,00.
`order.typeOrder`obrigatório	texto	Use `"pix"`.
`order.expiration`opcional	número	Validade do Pix em segundos. Ex.: `30000`.
`order.webhook.url`opcional	texto	Endereço que receberá os avisos de pagamento. Veja webhooks.
`order.webhook.typeWebhook`opcional	número	Use `2` para cobranças Pix.
`order.webhook.headers`opcional	lista	Headers extras que enviaremos no seu webhook, no formato `[{"key":"...","value":"..."}]`.

cURL

curl -X POST https://payfy.club/order \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-ClientId: SEU_CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d '{
    "order": {
      "externalId": "pedido-1001",
      "amount": 2.00,
      "typeOrder": "pix",
      "expiration": 30000,
      "webhook": {
        "url": "https://seu-site.com/webhooks/payfy",
        "typeWebhook": 2
      }
    }
  }'

Resposta de sucesso 200

Campos principais da resposta (outros campos informativos podem aparecer):

Campo	O que é
`orderId`	ID da cobrança na PayFy. Guarde para consultar depois.
`externalId`	O código que você enviou.
`amount`	Valor da cobrança.
`status`	Situação da cobrança (veja a tabela).
`qrCodeLink`	Link da imagem do QR Code para exibir ao cliente.
`transaction.transactionPix.cobResponse`	Dados do Pix, incluindo o Pix copia e cola e o `txid`.
`dtCreated`	Data de criação.

Exemplo (resumido)

{
  "orderId": "683efe9c386974e24fbdcf90",
  "externalId": "pedido-1001",
  "amount": 2.0,
  "typeOrder": "pix",
  "status": "created",
  "qrCodeLink": "https://...",
  "expiration": 30000,
  "dtCreated": "2026-10-26T14:00:00Z",
  "transaction": {
    "transactionPix": {
      "cobResponse": { /* txid, pixCopiaECola, ... */ }
    }
  }
}

💡

Mostre ao cliente o Pix copia e cola ou o QR Code. Quando ele pagar, enviaremos um webhook com o status payed.

Enviar Pix (transferência)

Pague um Pix a partir do seu saldo PayFy.

POST/transferRequer Bearer token

⚠️

Idempotência: envie o header X-Idempotency-Key com um valor único por transferência. Se você repetir a mesma chave (por exemplo, por falha de rede), responderemos 409 em vez de pagar duas vezes.

Corpo da requisição

Campo	Tipo	Descrição
`amount`obrigatório	número	Valor em reais, maior que zero. Ex.: `0.10`.
`type`obrigatório	texto	Use `"pix"`.
`externalId`obrigatório	texto	Seu código único da transferência (usado para consultar depois).
`bankAccount.pixCPF`	texto	Chave Pix do tipo CPF (somente números). Informe uma chave por transferência.
`bankAccount.pixCNPJ`	texto	Chave Pix do tipo CNPJ.
`bankAccount.pixEmail`	texto	Chave Pix do tipo e-mail.
`bankAccount.pixCelular`	texto	Chave Pix do tipo celular.
`bankAccount.pixAleatorio`	texto	Chave Pix aleatória.
`message`opcional	texto	Mensagem que acompanha o Pix.
`webhook.url`opcional	texto	Endereço que receberá o aviso quando a transferência for concluída.
`webhook.typeWebhook`opcional	número	Use `3` para transferências Pix.

cURL

curl -X POST https://payfy.club/transfer \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: transf-2001" \
  -H "X-ClientId: SEU_CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d '{
    "bankAccount": { "pixCPF": "00000000000" },
    "amount": 0.10,
    "type": "pix",
    "message": "Pagamento fornecedor",
    "externalId": "transf-2001",
    "webhook": {
      "url": "https://seu-site.com/webhooks/payfy-transfer",
      "typeWebhook": 3
    }
  }'

Resposta de sucesso 200

A transferência é aceita e entra em processamento. O resultado final chega pelo webhook ou por consulta.

Exemplo (resumido)

{
  "id": "661172bd5d7e6d2095c467e1",
  "externalId": "transf-2001",
  "amount": 0.1,
  "type": "pix",
  "status": "Created",
  "createdAt": "2026-10-26T14:05:00Z"
}

Consultar saldo

Veja quanto você tem disponível agora.

GET/balanceRequer Bearer token

cURL

curl https://payfy.club/balance \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-ClientId: SEU_CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Resposta 200

Exemplo

{
  "amountTodayPayIn": 1250.00,
  "amountTodayPayOut": 300.50,
  "amountWithdraw": 0,
  "previousBalance": 5000.00,
  "blockedBalance": 0,
  "availableBalance": 5949.50,
  "totalBalance": 5949.50
}

Campo	Significado
`availableBalance`	Quanto você pode usar agora.
`totalBalance`	Saldo total da conta.
`blockedBalance`	Valor retido (ex.: contestações).
`previousBalance`	Saldo do dia anterior.
`amountTodayPayIn`	Entradas de hoje (líquidas).
`amountTodayPayOut`	Saídas de hoje (inclui tarifas).

Consultar cobrança

Veja o status de uma cobrança Pix, de duas formas.

GET/order/byId/{id}Requer Bearer token

Use o orderId que a PayFy devolveu ao criar a cobrança.

GET/order/externalid/{externalid}Requer Bearer token

Use o externalId que você mesmo enviou ao criar a cobrança.

cURL

curl https://payfy.club/order/byId/683efe9c386974e24fbdcf90 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-ClientId: SEU_CLIENT_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

curl https://payfy.club/order/externalid/pedido-1001 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-ClientId: SEU_CLIENT_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

A resposta tem o mesmo formato da criação da cobrança, com o status atualizado (e dtPayed quando pago). Se a cobrança não existir, retornamos 404.

Consultar transferência

Acompanhe o resultado de um Pix enviado.

GET/transfer/{id}Requer Bearer token

GET/transfer/externalid/{externalid}Requer Bearer token

cURL

curl https://payfy.club/transfer/661172bd5d7e6d2095c467e1 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-ClientId: SEU_CLIENT_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

curl https://payfy.club/transfer/externalid/transf-2001 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-ClientId: SEU_CLIENT_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Resposta 200

Exemplo

{
  "id": "661172bd5d7e6d2095c467e1",
  "externalId": "transf-2001",
  "amount": 0.1,
  "status": "Transferred",
  "type": "pix",
  "endToEndId": "E00000000202610261405abcdef123456",
  "createdAt": "2026-10-26T14:05:00Z",
  "transferDate": "2026-10-26T14:05:03Z",
  "receiptURL": "https://...",
  "account": {
    "owner": { "name": "Nome do favorecido", "taxId": "***.000.000-**" }
  }
}

Campo	O que é
`status`	Situação da transferência (veja a tabela).
`endToEndId`	Identificador do Pix no Banco Central, útil para conciliação e suporte.
`receiptURL`	Link do comprovante, quando disponível.
`errorMessage`	Motivo da falha, quando o status for `Error`.

Webhooks (avisos automáticos)

Em vez de ficar perguntando se o Pix foi pago, deixe que a PayFy avise você.

Informe a URLEnvie webhook.url ao criar a cobrança ou a transferência.
Recebemos a mudança de statusQuando algo muda (pago, cancelado, transferido, erro...), fazemos um POST com JSON na sua URL.
Você responde 200Responda com status HTTP 2xx para confirmar o recebimento.

Tipo	`typeWebhook`	Quando disparamos	Tentativas se falhar
Cobrança Pix	`2`	Quando o status da cobrança muda (ex.: paga).	Até 5 tentativas, a cada 5 minutos.
Transferência Pix	`3`	Quando a transferência é concluída ou falha.	Até 10 tentativas.

Aviso de cobrança paga

POST para a sua URL

{
  "Id": "683efe9c386974e24fbdcf90",
  "orderId": "683efe9c386974e24fbdcf90",
  "externalId": "pedido-1001",
  "amount": 2.0,
  "amountPayed": 2.0,
  "typeOrder": 0,
  "status": 1,
  "dtCreated": "2026-10-26T14:00:00Z",
  "dtPayed": "2026-10-26T14:01:12Z",
  "endToEndId": "E00000000202610261401abcdef123456",
  "companyId": "..."
}

ℹ️

Nos webhooks, status e typeOrder chegam como número. Veja os códigos em Status. Campos sem valor não são enviados.

Aviso de transferência

POST para a sua URL

{
  "id": "661172bd5d7e6d2095c467e1",
  "externalId": "transf-2001",
  "amount": 0.1,
  "status": 1,
  "type": "pix",
  "endToEndId": "E00000000202610261405abcdef123456",
  "createdAt": "2026-10-26T14:05:00Z",
  "transferDate": "2026-10-26T14:05:03Z",
  "receiptURL": "https://..."
}

✅

Boas práticas: responda rápido (200), processe depois; trate avisos repetidos como idempotentes (use externalId); e, se quiser ter certeza do estado, confirme com um GET.

🔐

Precisa que seu servidor valide a origem dos avisos? Use webhook.headers para que enviemos um header secreto seu em cada chamada.

Status

O que cada status significa.

Cobranças (`order`)

Código (webhook)	Status (API)	Significado
`0`	`created`	Cobrança criada, aguardando pagamento.
`1`	`payed`	Paga. Pode liberar o produto/serviço.
`2`	`waiting`	Aguardando confirmação.
`3`	`canceled`	Cancelada ou expirada.
`4`	`error`	Erro no processamento.
`5`	`refunded`	Devolvida ao pagador.
`6`	`chargeback`	Contestada/estornada.
`7`	`refunding`	Devolução em andamento.

Transferências (`transfer`)

Código (webhook)	Status (API)	Significado
`0`	`Created`	Recebida e em processamento.
`1`	`Transferred`	Concluída, dinheiro enviado.
`2`	`Error`	Falhou. Veja `errorMessage`.
`3`	`Scheduled`	Agendada.
`4`	`Refunded`	Estornada.
`5`	`WaitingToken`	Aguardando token de aprovação.
`6`	`Partial_Refunded`	Estornada parcialmente.
`7`	`Approving`	Em aprovação.
`8`	`Approved`	Aprovada.

Erros

Quando algo dá errado, a resposta explica o motivo.

Formato do erro

{
  "errorMessage": "The amount cannot be negative.",
  "propertyName": "Amount"
}

HTTP	Quando acontece	O que fazer
200	Deu certo.	Siga o fluxo.
400	Dados inválidos ou erro ao processar (ex.: valor negativo).	Leia `errorMessage` e corrija o envio.
401	Token ausente, inválido ou expirado.	Gere um novo token em `/auth`.
403	Acesso negado (assinatura/IP não autorizado ou conta sem permissão).	Confira os headers de segurança e o IP de origem; se persistir, fale com a PayFy.
404	Registro não encontrado.	Confira o `id` / `externalid`.
409	Requisição duplicada (mesmo `X-Idempotency-Key`).	A transferência já foi recebida. Consulte-a por `externalid`.
5xx	Instabilidade temporária.	Tente novamente após alguns segundos (com a mesma chave de idempotência).

Dúvidas comuns

Qual a diferença entre `id` e `externalId`?

id/orderId é gerado pela PayFy. externalId é o seu código, escolhido por você. Ambos servem para consultar.

Como obtenho meu `clientId` e `clientSecret`?

Eles são fornecidos pela PayFy no cadastro da sua empresa. Fale com o nosso time comercial ou de suporte.

Meu webhook não está chegando. E agora?

Confirme que a URL é pública (HTTPS) e responde 2xx. Você também pode consultar o status direto pelos endpoints GET.

Qual o formato dos valores?

Números com ponto decimal, em reais. Ex.: 10.50 é R$ 10,50. Datas seguem o padrão ISO 8601 (UTC).

🤝

Ficou com alguma dúvida? Fale com o time PayFy, vamos adorar ajudar você a ir ao ar.

Field	Type	Description
`clientId`required	text	Your company identifier, provided by PayFy.
`clientSecret`required	text	Your company secret, provided by PayFy. Keep it safe.

Field	Type	Description
`order.externalId`required	text	Your unique order code. Use it to query later and to avoid duplicates.
`order.amount`required	number	Amount in reais (BRL). E.g. `2.00` = R$ 2.00.
`order.typeOrder`required	text	Use `"pix"`.
`order.expiration`optional	number	Pix validity in seconds. E.g. `30000`.
`order.webhook.url`optional	text	Address that will receive payment notifications. See webhooks.
`order.webhook.typeWebhook`optional	number	Use `2` for Pix charges.
`order.webhook.headers`optional	list	Extra headers we will send to your webhook, in the format `[{"key":"...","value":"..."}]`.

Field	What it is
`orderId`	Charge ID at PayFy. Store it to query later.
`externalId`	The code you sent.
`amount`	Charge amount.
`status`	Charge state (see the table).
`qrCodeLink`	QR Code image link to show to the customer.
`transaction.transactionPix.cobResponse`	Pix data, including the Pix copy-and-paste code and the `txid`.
`dtCreated`	Creation date.

Field	Type	Description
`amount`required	number	Amount in reais (BRL), greater than zero. E.g. `0.10`.
`type`required	text	Use `"pix"`.
`externalId`required	text	Your unique transfer code (used to query later).
`bankAccount.pixCPF`	text	CPF-type Pix key (digits only). Provide one key per transfer.
`bankAccount.pixCNPJ`	text	CNPJ-type Pix key.
`bankAccount.pixEmail`	text	Email-type Pix key.
`bankAccount.pixCelular`	text	Mobile phone-type Pix key.
`bankAccount.pixAleatorio`	text	Random Pix key.
`message`optional	text	Message that goes with the Pix.
`webhook.url`optional	text	Address that will receive the notification when the transfer completes.
`webhook.typeWebhook`optional	number	Use `3` for Pix transfers.

Field	Meaning
`availableBalance`	How much you can use now.
`totalBalance`	Total account balance.
`blockedBalance`	Held amount (e.g. disputes).
`previousBalance`	Previous day's balance.
`amountTodayPayIn`	Today's incoming (net).
`amountTodayPayOut`	Today's outgoing (includes fees).

Header	What to send
`X-ClientId`	The same `clientId` used in `/auth`.
`X-Timestamp`	Current time in milliseconds (Unix, e.g. `1761600000000`). We accept a difference of up to 5 minutes.
`X-Signature`	`Base64( HMAC-SHA256( X-Timestamp + X-ClientId , hmacKey ) )` The `hmacKey` is a dedicated signing key, provided by PayFy together with your `clientId`.

Method	Route	What for
POST	`/auth`	Get the access token
POST	`/order`	Create a Pix charge
POST	`/transfer`	Send a Pix (transfer)
GET	`/balance`	Check your balance
GET	`/order/byId/{id}`	Get a charge by PayFy ID
GET	`/order/externalid/{externalid}`	Get a charge by your own code
GET	`/transfer/{id}`	Get a transfer by PayFy ID
GET	`/transfer/externalid/{id}`	Get a transfer by your own code

Field	What it is
`status`	Transfer state (see the table).
`endToEndId`	Pix identifier at the Central Bank, useful for reconciliation and support.
`receiptURL`	Receipt link, when available.
`errorMessage`	Failure reason, when the status is `Error`.

Type	`typeWebhook`	When we fire it	Retries on failure
Pix charge	`2`	When the charge status changes (e.g. paid).	Up to 5 attempts, every 5 minutes.
Pix transfer	`3`	When the transfer completes or fails.	Up to 10 attempts.

Code (webhook)	Status (API)	Meaning
`0`	`created`	Charge created, awaiting payment.
`1`	`payed`	Paid. You can release the product/service.
`2`	`waiting`	Awaiting confirmation.
`3`	`canceled`	Canceled or expired.
`4`	`error`	Processing error.
`5`	`refunded`	Returned to the payer.
`6`	`chargeback`	Disputed/reversed.
`7`	`refunding`	Refund in progress.

Code (webhook)	Status (API)	Meaning
`0`	`Created`	Received and being processed.
`1`	`Transferred`	Completed, money sent.
`2`	`Error`	Failed. See `errorMessage`.
`3`	`Scheduled`	Scheduled.
`4`	`Refunded`	Refunded.
`5`	`WaitingToken`	Waiting for approval token.
`6`	`Partial_Refunded`	Partially refunded.
`7`	`Approving`	Under approval.
`8`	`Approved`	Approved.

HTTP	When it happens	What to do
200	It worked.	Continue the flow.
400	Invalid data or processing error (e.g. negative amount).	Read `errorMessage` and fix the request.
401	Missing, invalid or expired token.	Generate a new token with `/auth`.
403	Access denied (unauthorized signature/IP or account without permission).	Check the security headers and the source IP; if it persists, contact PayFy.
404	Record not found.	Check the `id` / `externalid`.
409	Duplicate request (same `X-Idempotency-Key`).	The transfer was already received. Query it by `externalid`.
5xx	Temporary instability.	Try again after a few seconds (with the same idempotency key).

Pagamentos que movem o seu futuro.

Visão geral

Autenticar

Receber por Pix

Enviar dinheiro

Consultar

Ser avisado

Comece em 3 passos

Autenticação e segurança

1. Token de acesso (Bearer)

2. Assinatura das chamadas (headers de segurança)

Endpoints

Autenticar

Corpo da requisição

Criar cobrança Pix

Corpo da requisição

Resposta de sucesso 200

Enviar Pix (transferência)

Corpo da requisição

Resposta de sucesso 200

Consultar saldo

Resposta 200

Consultar cobrança

Consultar transferência

Resposta 200

Webhooks (avisos automáticos)

Aviso de cobrança paga

Aviso de transferência

Status

Cobranças (order)

Transferências (transfer)

Erros

Dúvidas comuns

Qual a diferença entre id e externalId?

Como obtenho meu clientId e clientSecret?

Meu webhook não está chegando. E agora?

Qual o formato dos valores?

Payments that move your future.

Getting started

Endpoints

Automatic notifications

Reference

Overview

Authenticate

Receive via Pix

Send money

Query

Get notified

Get started in 3 steps

Authentication & security

1. Access token (Bearer)

2. Request signature (security headers)

Endpoints

Authenticate

Request body

Create a Pix charge

Request body

Success response 200

Send Pix (transfer)

Request body

Success response 200

Check balance

Response 200

Get a charge

Get a transfer

Response 200

Webhooks (automatic notifications)

Paid charge notification

Transfer notification

Statuses

Charges (order)

Transfers (transfer)

Errors

Common questions

What is the difference between id and externalId?

How do I get my clientId and clientSecret?

My webhook is not arriving. What now?

What is the format of values?

Cobranças (`order`)

Transferências (`transfer`)

Qual a diferença entre `id` e `externalId`?

Como obtenho meu `clientId` e `clientSecret`?

Charges (`order`)

Transfers (`transfer`)

What is the difference between `id` and `externalId`?

How do I get my `clientId` and `clientSecret`?