Skip to main content
GET
/
sellers
/
pix
/
{id}
Consultar cobranca PIX
curl --request GET \
  --url http://localhost:3030/sellers/pix/{id} \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>'
{
  "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 esta rota para consultar o estado de uma cobranca ja criada e sincronizar seu ERP, checkout ou painel financeiro.

​
Autenticacao

  • x-client-id
  • x-client-secret

​
Pre-condicoes e requisitos

  • O id deve ser um identificador da cobranca/transacao retornado pela Turbofy: id, externalRef, providerChargeId, pixTxid ou endToEndId.
  • A cobranca precisa pertencer ao merchant autenticado.

​
Request

Parametro principal:
  • id (path): identificador da cobranca PIX ou da transacao Pix vinculada.

​
Response de sucesso

Em 200, a API retorna:
  • id, status, amountCents, description
  • pix.qrCode, pix.copyPaste, pix.expiresAt
  • payer: pagador real da transacao com name, email, phone, document, documentType, institution, agency e account quando disponiveis
  • beneficiary: merchant recebedor da cobranca; a conta aparece como conta TurbofyPay, como uma instituicao de pagamento
  • splits (quando houver)
  • createdAt e updatedAt
Exemplo parcial: 
{
  "id": "3f8d6f3a-87f9-4ed4-a820-95f76f050fca",
  "status": "PAID",
  "amountCents": 2990,
  "payer": {
    "name": "Maria Pagadora",
    "email": "maria@example.com",
    "phone": "11999998888",
    "document": "39053344705",
    "documentType": "CPF",
    "institution": "Banco Origem",
    "agency": "0001",
    "account": "123456-7"
  },
  "beneficiary": {
    "id": "merchant-123",
    "name": "Loja Recebedora",
    "email": "loja@example.com",
    "document": "12345678000195",
    "documentType": "CNPJ",
    "institution": "TurbofyPay",
    "account": {
      "institution": "TurbofyPay",
      "type": "Conta de pagamento"
    }
  }
}

​
Erros comuns reais

HTTPcodeQuando ocorre
400MERCHANT_ID_REQUIREDMerchant nao resolvido na credencial.
401CREDENTIALS_REQUIREDCredenciais ausentes.
401INVALID_CREDENTIALSCredenciais invalidas.
404NOT_FOUNDCobranca inexistente para o merchant autenticado.

​
Regras de negocio e observacoes operacionais

  • A consulta retorna somente cobrancas do merchant autenticado.
  • O pagador vem dos dados reais da transacao Pix quando o pagamento ja foi confirmado e ha endToEndId disponivel; se a rede Pix estiver indisponivel, a API usa snapshot persistido ou metadata local.
  • O beneficiario e sempre o merchant dono da cobranca. A TurbofyPay aparece como instituicao/conta de pagamento, nao como beneficiario final.
  • Para conciliacao, persista id, status, externalRef e timestamps.
  • Alias legado /rifeiro/pix/:id existe por compatibilidade; use /sellers/pix/{id} como caminho principal.

​
Exemplo de codigo

curl --request GET \
  --url https://api.turbofypay.com/sellers/pix/3f8d6f3a-87f9-4ed4-a820-95f76f050fca \
  --header "x-client-id: <client-id>" \
  --header "x-client-secret: <client-secret>"

​
Proximos passos

  1. Se ainda nao criou a cobranca, use Criar cobranca PIX.
  2. Para eventos assincronos, configure Webhooks.

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.

Path Parameters

​
id
string
required

Identificador da cobranca/transacao: id, externalRef, providerChargeId, pixTxid ou endToEndId.

Response

Cobranca PIX encontrada.

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