Skip to main content
POST
/
sellers
/
pix
Criar cobranca PIX
curl --request POST \
  --url http://localhost:3030/sellers/pix \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "amountCents": 1500,
  "description": "Pagamento do pedido #123",
  "externalRef": "order-123",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "metadata": {
    "orderId": "123",
    "channel": "api"
  }
}
'
{
  "id": "<string>",
  "status": "<string>",
  "amountCents": 123,
  "pix": {
    "qrCode": "<string>",
    "copyPaste": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "splits": [
    {
      "id": "<string>",
      "merchantId": "<string>",
      "amountCents": 123,
      "percentage": 123
    }
  ],
  "webhook": {
    "url": "<string>",
    "secret": "<string>",
    "events": [
      "<string>"
    ]
  },
  "updatedAt": "2023-11-07T05:31:56Z"
}

​
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

​
Erros comuns reais

201 CREATED400 VALIDATION_ERROR502 PROVIDER_ERROR
HTTPcodeQuando ocorre
400VALIDATION_ERRORBody invalido ou campos fora do contrato.
400MERCHANT_ID_REQUIREDMerchant nao resolvido na credencial.
401CREDENTIALS_REQUIREDCredenciais ausentes.
401INVALID_CREDENTIALSCredenciais invalidas.
502PIX_NOT_ISSUEDCobranca criada sem payload PIX do provedor.
502PROVIDER_ERRORFalha no provedor durante emissao.
500INTERNAL_ERRORFalha 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

curl --request POST \
  --url https://api.turbofypay.com/sellers/pix \
  --header "x-client-id: <client-id>" \
  --header "x-client-secret: <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.
  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
​
updatedAt
string<date-time>
Last modified on April 13, 2026