Skip to main content
POST
Criar cobranca PIX

Caso de uso

Use este endpoint para criar uma cobranca PIX no checkout e receber imediatamente os dados de pagamento (qrCode e copyPaste) para exibir ao pagador.

Autenticacao

Obrigatorio em todas as chamadas:
  • x-client-id
  • x-client-secret
Recomendado para escrita:
  • x-idempotency-key

Pre-condicoes e requisitos

  • amountCents deve ser inteiro positivo.
  • Se usar webhook_url, a URL precisa ser valida e acessivel.
  • Se usar splits, cada item deve conter merchantId.
  • Use idempotencia para evitar duplicidade de cobranca.

Request

Campos mais importantes do body:
  • amountCents: valor em centavos.
  • description: texto de referencia da cobranca.
  • externalRef: identificador do seu sistema.
  • expiresAt: expiracao em ISO-8601.
  • metadata: dados de conciliacao.
  • splits: divisao de repasse entre merchants.

Response de sucesso

Em 201, a API retorna:
  • id e status
  • amountCents e description
  • pix.qrCode e pix.copyPaste
  • pix.expiresAt
  • createdAt e updatedAt
Fluxo visual de uma cobranca PIX criada com resposta 201, status pendente, QR Code sanitizado e conciliacao por webhook. Exemplo sanitizado do que precisa ser exibido ao pagador e do que deve ser persistido para reconciliar status, webhook e consulta posterior.

Erros comuns reais

201 CREATED400 VALIDATION_ERROR502 PROVIDER_ERROR

Regras de negocio e observacoes operacionais

  • Nao reutilize x-idempotency-key com payload diferente.
  • Se enviar webhook_url, a cobranca cria webhook escopado para eventos de ciclo de vida.
  • O alias legado /rifeiro/pix existe por compatibilidade; rota canonica publica: /sellers/pix.

Exemplo de codigo

Proximos passos

  1. Consulte o status em Consultar cobranca PIX.
  2. Configure eventos em Webhooks.
  3. Revise seguranca em Autenticacao.

Authorizations

x-client-id
string
header
required

Client ID fornecido pela TurbofyPay.

x-client-secret
string
header
required

Client Secret fornecido pela TurbofyPay.

Headers

x-client-id
string
required

Identificador do integrador.

x-client-secret
string
required

Segredo de autenticacao do integrador.

x-idempotency-key
string

Chave de idempotencia para operacoes de escrita.

Body

application/json
amountCents
integer
required
Required range: x >= 1
description
string
expiresAt
string<date-time>
externalRef
string
webhook_url
string<uri>
webhook_secret
string
metadata
object
splits
object[]

Response

Cobranca PIX criada com sucesso.

id
string
required
status
string
required
amountCents
integer
required
pix
object
required
createdAt
string<date-time>
required
description
string | null
splits
object[]
webhook
object | null
payer
object | null
beneficiary
object | null
updatedAt
string<date-time>
Last modified on June 1, 2026