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>"
    ]
  },
  "payer": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "document": "<string>",
    "institution": "<string>",
    "agency": "<string>",
    "account": "<string>"
  },
  "beneficiary": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "document": "<string>",
    "institution": "<string>",
    "account": {
      "institution": "<string>",
      "type": "<string>"
    }
  },
  "updatedAt": "2023-11-07T05:31:56Z"
}

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>"
    ]
  },
  "payer": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "document": "<string>",
    "institution": "<string>",
    "agency": "<string>",
    "account": "<string>"
  },
  "beneficiary": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "document": "<string>",
    "institution": "<string>",
    "account": {
      "institution": "<string>",
      "type": "<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

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

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

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

Consulte o status em Consultar cobranca PIX.
Configure eventos em Webhooks.
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[]

Show child attributes

Response

Cobranca PIX criada com sucesso.

string

required

status

string

required

amountCents

integer

required

pix

object

required

Show child attributes

createdAt

string<date-time>

required

description

string | null

splits

object[]

Show child attributes

webhook

object

Show child attributes

payer

object

Show child attributes

beneficiary

object

Show child attributes

updatedAt

string<date-time>

Last modified on June 1, 2026

Consultar cobranca PIX

​Caso de uso

​Autenticacao

​Pre-condicoes e requisitos

​Request

​Response de sucesso

​Erros comuns reais

​Regras de negocio e observacoes operacionais

​Exemplo de codigo

​Proximos passos

Authorizations

Headers

Body

Response

Caso de uso

Autenticacao

Pre-condicoes e requisitos

Request

Response de sucesso

Erros comuns reais

Regras de negocio e observacoes operacionais

Exemplo de codigo

Proximos passos