> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar cobranca PIX
> Cria uma cobranca PIX para o seller autenticado e retorna QR Code com copia e cola.
## 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`
*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 CREATED
400 VALIDATION\_ERROR
502 PROVIDER\_ERROR
| HTTP | code | Quando ocorre |
| ----- | ---------------------- | -------------------------------------------- |
| `400` | `VALIDATION_ERROR` | Body invalido ou campos fora do contrato. |
| `400` | `MERCHANT_ID_REQUIRED` | Merchant nao resolvido na credencial. |
| `401` | `CREDENTIALS_REQUIRED` | Credenciais ausentes. |
| `401` | `INVALID_CREDENTIALS` | Credenciais invalidas. |
| `502` | `PIX_NOT_ISSUED` | Cobranca criada sem payload PIX do provedor. |
| `502` | `PROVIDER_ERROR` | Falha no provedor durante emissao. |
| `500` | `INTERNAL_ERROR` | Falha interna nao classificada. |
## 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
```bash theme={null}
curl --request POST \
--url https://api.turbofypay.com/sellers/pix \
--header "x-client-id: " \
--header "x-client-secret: " \
--header "x-idempotency-key: pedido-123" \
--header "Content-Type: application/json" \
--data '{
"amountCents": 2990,
"description": "Pedido #123",
"externalRef": "pedido-123"
}'
```
## Proximos passos
1. Consulte o status em [Consultar cobranca PIX](/reference/cobranca-pix/consultar-cobranca-pix).
2. Configure eventos em [Webhooks](/integracao/webhooks).
3. Revise seguranca em [Autenticacao](/integracao/autenticacao).
## OpenAPI
````yaml POST /sellers/pix
openapi: 3.0.3
info:
title: Turbofy Public API
version: 2.0.0
description: >-
Especificacao publica da API TurbofyPay para Cobranca PIX, Saques, Webhooks
e Payouts.
contact:
name: Turbofy Team
email: suporte@turbofy.com
url: https://turbofy.com
license:
name: Proprietary
url: https://turbofy.com/terms
servers:
- url: http://localhost:3030
description: Development Server
- url: https://api.turbofypay.com
description: Production Server
security: []
tags:
- name: Cobranca PIX
description: Operacoes de cobranca PIX para integradores.
- name: Saques
description: Operacoes de saque para sellers.
- name: Webhooks
description: Cadastro e consulta de webhooks.
- name: Payouts
description: Gestao de lotes de payout.
externalDocs:
description: Documentação completa
url: https://docs.turbofy.com
paths:
/sellers/pix:
post:
tags:
- Cobranca PIX
summary: Criar cobranca PIX
description: >-
Cria uma cobranca PIX para o seller autenticado e retorna QR Code e
codigo copia e cola.
operationId: createPixCharge
parameters:
- $ref: '#/components/parameters/XClientId'
- $ref: '#/components/parameters/XClientSecret'
- $ref: '#/components/parameters/XIdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PixChargeCreateRequest'
examples:
padrao:
summary: Cobranca PIX com expiracao e metadata
value:
amountCents: 1500
description: 'Pagamento do pedido #123'
externalRef: order-123
expiresAt: '2026-12-31T23:59:59.000Z'
metadata:
orderId: '123'
channel: api
responses:
'201':
description: Cobranca PIX criada com sucesso.
content:
application/json:
schema:
$ref: '#/components/schemas/PixChargeCreateResponse'
'400':
description: Payload invalido ou headers obrigatorios ausentes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Credenciais ausentes ou invalidas.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Falha no provedor de pagamento durante emissao do PIX.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- clientCredentials: []
clientSecret: []
components:
parameters:
XClientId:
name: x-client-id
in: header
required: true
schema:
type: string
description: Identificador do integrador.
XClientSecret:
name: x-client-secret
in: header
required: true
schema:
type: string
description: Segredo de autenticacao do integrador.
XIdempotencyKey:
name: x-idempotency-key
in: header
required: false
schema:
type: string
description: Chave de idempotencia para operacoes de escrita.
schemas:
PixChargeCreateRequest:
type: object
required:
- amountCents
properties:
amountCents:
type: integer
minimum: 1
description:
type: string
expiresAt:
type: string
format: date-time
externalRef:
type: string
webhook_url:
type: string
format: uri
webhook_secret:
type: string
metadata:
type: object
additionalProperties: true
splits:
type: array
items:
type: object
required:
- merchantId
properties:
merchantId:
type: string
amountCents:
type: integer
minimum: 1
percentage:
type: number
minimum: 0
PixChargeCreateResponse:
allOf:
- $ref: '#/components/schemas/PixChargeObject'
ErrorResponse:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
traceId:
type: string
PixChargeObject:
type: object
required:
- id
- status
- amountCents
- pix
- createdAt
properties:
id:
type: string
status:
type: string
amountCents:
type: integer
description:
type: string
nullable: true
pix:
type: object
required:
- qrCode
- copyPaste
- expiresAt
properties:
qrCode:
type: string
copyPaste:
type: string
expiresAt:
type: string
format: date-time
splits:
type: array
items:
type: object
properties:
id:
type: string
merchantId:
type: string
amountCents:
type: integer
percentage:
type: number
nullable: true
webhook:
type: object
nullable: true
properties:
url:
type: string
format: uri
secret:
type: string
events:
type: array
items:
type: string
payer:
type: object
nullable: true
properties:
name:
type: string
nullable: true
email:
type: string
nullable: true
phone:
type: string
nullable: true
document:
type: string
nullable: true
documentType:
type: string
enum:
- CPF
- CNPJ
nullable: true
institution:
type: string
nullable: true
agency:
type: string
nullable: true
account:
type: string
nullable: true
beneficiary:
type: object
nullable: true
properties:
id:
type: string
name:
type: string
email:
type: string
document:
type: string
nullable: true
documentType:
type: string
enum:
- CPF
- CNPJ
nullable: true
institution:
type: string
account:
type: object
properties:
institution:
type: string
type:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
securitySchemes:
clientCredentials:
type: apiKey
in: header
name: x-client-id
description: Client ID fornecido pela TurbofyPay.
clientSecret:
type: apiKey
in: header
name: x-client-secret
description: Client Secret fornecido pela TurbofyPay.
````