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>'import requests
url = "http://localhost:3030/sellers/pix/{id}"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-client-id': '<api-key>', 'x-client-secret': '<api-key>'}
};
fetch('http://localhost:3030/sellers/pix/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3030",
CURLOPT_URL => "http://localhost:3030/sellers/pix/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-client-id: <api-key>",
"x-client-secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:3030/sellers/pix/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:3030/sellers/pix/{id}")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/sellers/pix/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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>",
"documentType": "CPF",
"institution": "<string>",
"agency": "<string>",
"account": "<string>"
},
"beneficiary": {
"id": "<string>",
"name": "<string>",
"email": "<string>",
"document": "<string>",
"documentType": "CPF",
"institution": "<string>",
"account": {
"institution": "<string>",
"type": "<string>"
}
},
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}Cobranca PIX
Consultar cobranca PIX
Consulta uma cobranca PIX por ID para sincronizar status e dados de pagamento.
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>'import requests
url = "http://localhost:3030/sellers/pix/{id}"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-client-id': '<api-key>', 'x-client-secret': '<api-key>'}
};
fetch('http://localhost:3030/sellers/pix/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3030",
CURLOPT_URL => "http://localhost:3030/sellers/pix/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-client-id: <api-key>",
"x-client-secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:3030/sellers/pix/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:3030/sellers/pix/{id}")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/sellers/pix/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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>",
"documentType": "CPF",
"institution": "<string>",
"agency": "<string>",
"account": "<string>"
},
"beneficiary": {
"id": "<string>",
"name": "<string>",
"email": "<string>",
"document": "<string>",
"documentType": "CPF",
"institution": "<string>",
"account": {
"institution": "<string>",
"type": "<string>"
}
},
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}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-idx-client-secret
Pre-condicoes e requisitos
- O
iddeve ser um identificador da cobranca/transacao retornado pela Turbofy:id,externalRef,providerChargeId,pixTxidouendToEndId. - A cobranca precisa pertencer ao merchant autenticado.
Request
Parametro principal:id(path): identificador da cobranca PIX ou da transacao Pix vinculada.
Response de sucesso
Em200, a API retorna:
id,status,amountCents,descriptionpix.qrCode,pix.copyPaste,pix.expiresAtpayer: pagador real da transacao comname,email,phone,document,documentType,institution,agencyeaccountquando disponiveisbeneficiary: merchant recebedor da cobranca; a conta aparece como conta TurbofyPay, como uma instituicao de pagamentosplits(quando houver)createdAteupdatedAt
{
"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
| HTTP | code | Quando ocorre |
|---|---|---|
400 | MERCHANT_ID_REQUIRED | Merchant nao resolvido na credencial. |
401 | CREDENTIALS_REQUIRED | Credenciais ausentes. |
401 | INVALID_CREDENTIALS | Credenciais invalidas. |
404 | NOT_FOUND | Cobranca 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
endToEndIddisponivel; 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,externalRefe timestamps. - Alias legado
/rifeiro/pix/:idexiste 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
- Se ainda nao criou a cobranca, use Criar cobranca PIX.
- Para eventos assincronos, configure Webhooks.
Authorizations
Client ID fornecido pela TurbofyPay.
Client Secret fornecido pela TurbofyPay.
Headers
Identificador do integrador.
Segredo de autenticacao do integrador.
Path Parameters
Identificador da cobranca/transacao: id, externalRef, providerChargeId, pixTxid ou endToEndId.
Response
Cobranca PIX encontrada.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Last modified on June 8, 2026