Autenticação
Todas as requisições autenticadas devem incluir sua API Key no header Authorization.
Authorization: Bearer sk_prod_SUA_SECRET_KEY
| Tipo | Prefixo | Permissões |
|---|---|---|
| Secret Key | sk_prod_... | Tudo — GET, POST, PUT, DELETE |
| Public Key | pk_prod_... | Somente leitura (GET) |
Crie suas chaves em Dashboard → Chaves de API. Cada chave é vinculada a um produto específico usando o hash do produto (ex: #B2XVAM1H) visível na listagem de produtos. A chave herda automaticamente o produto — todas as transações geradas com a chave são atribuídas ao produto vinculado.
Base URL
Use a URL abaixo como prefixo para todas as chamadas da API.
https://app.playpayments.com.br/api
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /pix | Criar cobrança PIX |
| GET | /pix/{id} | Consultar cobrança completa |
| GET | /pix/status/{id} | Verificar status (leve) |
| GET | /pix | Listar cobranças |
| POST | /v1/withdrawals | Saque PIX |
| GET | /v1/balance | Consultar saldo |
| GET | /health | Health check (sem autenticação) |
Criar Cobrança PIX
Gera uma cobrança PIX com QR Code e código copia-e-cola. O gateway é selecionado automaticamente em round-robin entre suas adquirentes ativas.
/api/pixCampos obrigatórios
| Campo | Tipo | Req | Descrição |
|---|---|---|---|
| payment_method | string | obrigatório | Método de pagamento — use pix |
| amount | number | obrigatório | Valor total em R$ — mínimo 0.01 |
| customer.name | string | obrigatório | Nome completo do pagador |
| customer.email | string | obrigatório | Email do pagador |
| customer.document | string | obrigatório | CPF (11 dígitos) ou CNPJ (14 dígitos), somente números |
Campos opcionais
| Campo | Tipo | Descrição |
|---|---|---|
| customer.phone | string | Telefone com DDD, somente números |
| title | string | Título da cobrança exibido no recibo (máx. 100 chars) |
| description | string | Descrição detalhada da cobrança (máx. 500 chars) |
| external_id | string | ID do seu sistema — usado para idempotência e rastreio |
| expires_in | integer | Expiração do PIX em segundos — padrão 3600 (1h), máx 86400 (24h) |
| cart | array | Itens do carrinho. Cada item: product_hash, title, price, quantity |
| cart[].product_hash | string | Hash do produto (ex: B2XVAM1H), visível em /produtos |
| cart[].title | string | Nome/título do item no carrinho |
| cart[].price | number | Preço unitário em R$ |
| cart[].quantity | integer | Quantidade do item — padrão 1 |
| tracking | object | Parâmetros de rastreio de tráfego (UTMs). Campos: utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck |
curl -X POST https://app.playpayments.com.br/api/pix \
-H "Authorization: Bearer sk_prod_SUA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "pix",
"amount": 150.00,
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900",
"phone": "11999999999"
},
"title": "Pedido #1234",
"description": "Curso de Marketing Digital",
"external_id": "pedido-1234",
"expires_in": 3600,
"cart": [
{
"product_hash": "B2XVAM1H",
"title": "Curso de Marketing Digital",
"price": 150.00,
"quantity": 1
}
],
"tracking": {
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "black-friday-2025",
"utm_content": "banner-topo",
"utm_term": "marketing digital",
"src": "fb-ads",
"sck": "subid-abc123"
}
}'
const axios = require('axios');
const { data } = await axios.post('https://app.playpayments.com.br/api/pix', {
payment_method: 'pix',
amount: 150.00,
customer: {
name: 'João Silva', email: 'joao@email.com',
document: '12345678900', phone: '11999999999'
},
title: 'Pedido #1234',
description: 'Curso de Marketing Digital',
external_id: 'pedido-1234',
expires_in: 3600,
cart: [{
product_hash: 'B2XVAM1H',
title: 'Curso de Marketing Digital',
price: 150.00,
quantity: 1
}],
tracking: {
utm_source: 'facebook', utm_medium: 'cpc',
utm_campaign: 'black-friday-2025', utm_content: 'banner-topo',
utm_term: 'marketing digital', src: 'fb-ads', sck: 'subid-abc123'
}
}, {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
console.log(data.pix_code);
const res = await fetch('https://app.playpayments.com.br/api/pix', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_prod_SUA_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_method: 'pix',
amount: 150.00,
customer: {
name: 'João Silva', email: 'joao@email.com',
document: '12345678900', phone: '11999999999'
},
title: 'Pedido #1234',
description: 'Curso de Marketing Digital',
external_id: 'pedido-1234',
expires_in: 3600,
cart: [{
product_hash: 'B2XVAM1H',
title: 'Curso de Marketing Digital',
price: 150.00,
quantity: 1
}],
tracking: {
utm_source: 'facebook', utm_medium: 'cpc',
utm_campaign: 'black-friday-2025', utm_content: 'banner-topo',
utm_term: 'marketing digital', src: 'fb-ads', sck: 'subid-abc123'
}
})
});
const data = await res.json();
console.log(data.pix_code);
import requests
res = requests.post('https://app.playpayments.com.br/api/pix',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'},
json={
'payment_method': 'pix',
'amount': 150.00,
'customer': {
'name': 'João Silva', 'email': 'joao@email.com',
'document': '12345678900', 'phone': '11999999999'
},
'title': 'Pedido #1234',
'description': 'Curso de Marketing Digital',
'external_id': 'pedido-1234',
'expires_in': 3600,
'cart': [{
'product_hash': 'B2XVAM1H',
'title': 'Curso de Marketing Digital',
'price': 150.00,
'quantity': 1
}],
'tracking': {
'utm_source': 'facebook', 'utm_medium': 'cpc',
'utm_campaign': 'black-friday-2025', 'utm_content': 'banner-topo',
'utm_term': 'marketing digital', 'src': 'fb-ads', 'sck': 'subid-abc123'
}
}
)
print(res.json()['pix_code'])
$ch = curl_init('https://app.playpayments.com.br/api/pix');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'payment_method' => 'pix',
'amount' => 150.00,
'customer' => [
'name' => 'João Silva',
'email' => 'joao@email.com',
'document' => '12345678900',
'phone' => '11999999999',
],
'title' => 'Pedido #1234',
'description' => 'Curso de Marketing Digital',
'external_id' => 'pedido-1234',
'expires_in' => 3600,
'cart' => [[
'product_hash' => 'B2XVAM1H',
'title' => 'Curso de Marketing Digital',
'price' => 150.00,
'quantity' => 1,
]],
'tracking' => [
'utm_source' => 'facebook',
'utm_medium' => 'cpc',
'utm_campaign' => 'black-friday-2025',
'utm_content' => 'banner-topo',
'utm_term' => 'marketing digital',
'src' => 'fb-ads',
'sck' => 'subid-abc123',
],
]),
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY', 'Content-Type: application/json']
]);
$data = json_decode(curl_exec($ch), true);
echo $data['pix_code'];
{
"success": true,
"transaction_id": "txn_abc123",
"pix_code": "00020126...",
"qr_code": "00020126...",
"amount": 150.0,
"fee_amount": 2.25,
"net_amount": 147.75,
"status": "pending",
"expires_at": "2025-01-01T01:00:00Z",
"created_at": "2025-01-01T00:00:00Z"
}
| Campo | Tipo | Req | Descrição |
|---|---|---|---|
| amount | number | obrigatório | Valor em R$ — mínimo 0.01 |
| customer.name | string | obrigatório | Nome completo do pagador |
| customer.email | string | obrigatório | Email do pagador |
| customer.document | string | obrigatório | CPF (11 dígitos) ou CNPJ (14 dígitos) |
| customer.phone | string | opcional | Telefone com DDD (somente números) |
| description | string | opcional | Descrição da cobrança |
| external_id | string | opcional | ID do seu sistema — usado para idempotência |
| expires_in | integer | opcional | Expiração em segundos — padrão 3600, máx 86400 |
curl -X POST https://app.playpayments.com.br/api/pix \
-H "Authorization: Bearer sk_prod_SUA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "pix",
"amount": 150.00,
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900",
"phone": "11999999999"
},
"title": "Pedido #1234",
"description": "Curso de Marketing Digital",
"external_id": "pedido-1234",
"expires_in": 3600,
"cart": [
{
"product_hash": "B2XVAM1H",
"title": "Curso de Marketing Digital",
"price": 150.00,
"quantity": 1
}
],
"tracking": {
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "black-friday-2025",
"utm_content": "banner-topo",
"utm_term": "marketing digital",
"src": "fb-ads",
"sck": "subid-abc123"
}
}'
const axios = require('axios');
const { data } = await axios.post('https://app.playpayments.com.br/api/pix', {
payment_method: 'pix',
amount: 150.00,
customer: {
name: 'João Silva', email: 'joao@email.com',
document: '12345678900', phone: '11999999999'
},
title: 'Pedido #1234',
description: 'Curso de Marketing Digital',
external_id: 'pedido-1234',
expires_in: 3600,
cart: [{
product_hash: 'B2XVAM1H',
title: 'Curso de Marketing Digital',
price: 150.00,
quantity: 1
}],
tracking: {
utm_source: 'facebook', utm_medium: 'cpc',
utm_campaign: 'black-friday-2025', utm_content: 'banner-topo',
utm_term: 'marketing digital', src: 'fb-ads', sck: 'subid-abc123'
}
}, {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
console.log(data.pix_code);
const res = await fetch('https://app.playpayments.com.br/api/pix', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_prod_SUA_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_method: 'pix',
amount: 150.00,
customer: {
name: 'João Silva', email: 'joao@email.com',
document: '12345678900', phone: '11999999999'
},
title: 'Pedido #1234',
description: 'Curso de Marketing Digital',
external_id: 'pedido-1234',
expires_in: 3600,
cart: [{
product_hash: 'B2XVAM1H',
title: 'Curso de Marketing Digital',
price: 150.00,
quantity: 1
}],
tracking: {
utm_source: 'facebook', utm_medium: 'cpc',
utm_campaign: 'black-friday-2025', utm_content: 'banner-topo',
utm_term: 'marketing digital', src: 'fb-ads', sck: 'subid-abc123'
}
})
});
const data = await res.json();
console.log(data.pix_code);
import requests
res = requests.post('https://app.playpayments.com.br/api/pix',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'},
json={
'payment_method': 'pix',
'amount': 150.00,
'customer': {
'name': 'João Silva', 'email': 'joao@email.com',
'document': '12345678900', 'phone': '11999999999'
},
'title': 'Pedido #1234',
'description': 'Curso de Marketing Digital',
'external_id': 'pedido-1234',
'expires_in': 3600,
'cart': [{
'product_hash': 'B2XVAM1H',
'title': 'Curso de Marketing Digital',
'price': 150.00,
'quantity': 1
}],
'tracking': {
'utm_source': 'facebook', 'utm_medium': 'cpc',
'utm_campaign': 'black-friday-2025', 'utm_content': 'banner-topo',
'utm_term': 'marketing digital', 'src': 'fb-ads', 'sck': 'subid-abc123'
}
}
)
print(res.json()['pix_code'])
import httpx, asyncio
async def main():
async with httpx.AsyncClient() as c:
r = await c.post('https://app.playpayments.com.br/api/pix',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'},
json={
'payment_method': 'pix',
'amount': 150.00,
'customer': {
'name': 'João Silva', 'email': 'joao@email.com',
'document': '12345678900', 'phone': '11999999999'
},
'title': 'Pedido #1234',
'description': 'Curso de Marketing Digital',
'external_id': 'pedido-1234',
'expires_in': 3600,
'cart': [{'product_hash': 'B2XVAM1H', 'title': 'Curso de Marketing Digital', 'price': 150.00, 'quantity': 1}],
'tracking': {'utm_source': 'facebook', 'utm_medium': 'cpc', 'utm_campaign': 'black-friday-2025', 'utm_content': 'banner-topo', 'utm_term': 'marketing digital', 'src': 'fb-ads', 'sck': 'subid-abc123'}
}
)
print(r.json()['pix_code'])
asyncio.run(main())
$client = new \GuzzleHttp\Client();
$res = $client->post('https://app.playpayments.com.br/api/pix', [
'headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY'],
'json' => [
'payment_method' => 'pix',
'amount' => 150.00,
'customer' => [
'name' => 'João Silva', 'email' => 'joao@email.com',
'document' => '12345678900', 'phone' => '11999999999'
],
'title' => 'Pedido #1234',
'description' => 'Curso de Marketing Digital',
'external_id' => 'pedido-1234',
'expires_in' => 3600,
'cart' => [[
'product_hash' => 'B2XVAM1H', 'title' => 'Curso de Marketing Digital',
'price' => 150.00, 'quantity' => 1
]],
'tracking' => [
'utm_source' => 'facebook', 'utm_medium' => 'cpc',
'utm_campaign' => 'black-friday-2025', 'utm_content' => 'banner-topo',
'utm_term' => 'marketing digital', 'src' => 'fb-ads', 'sck' => 'subid-abc123'
]
]
]);
$data = json_decode($res->getBody(), true);
echo $data['pix_code'];
$ch = curl_init('https://app.playpayments.com.br/api/pix');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'payment_method' => 'pix',
'amount' => 150.00,
'customer' => [
'name' => 'João Silva', 'email' => 'joao@email.com',
'document' => '12345678900', 'phone' => '11999999999'
],
'title' => 'Pedido #1234',
'description' => 'Curso de Marketing Digital',
'external_id' => 'pedido-1234',
'expires_in' => 3600,
'cart' => [['product_hash' => 'B2XVAM1H', 'title' => 'Curso de Marketing Digital', 'price' => 150.00, 'quantity' => 1]],
'tracking' => ['utm_source' => 'facebook', 'utm_medium' => 'cpc', 'utm_campaign' => 'black-friday-2025', 'utm_content' => 'banner-topo', 'utm_term' => 'marketing digital', 'src' => 'fb-ads', 'sck' => 'subid-abc123']
]),
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY', 'Content-Type: application/json']
]);
$data = json_decode(curl_exec($ch), true);
echo $data['pix_code'];
package main
import ("bytes"; "encoding/json"; "fmt"; "net/http")
func main() {
body, _ := json.Marshal(map[string]any{
"payment_method": "pix",
"amount": 150.00,
"customer": map[string]string{
"name": "João Silva", "email": "joao@email.com",
"document": "12345678900", "phone": "11999999999",
},
"title": "Pedido #1234",
"description": "Curso de Marketing Digital",
"external_id": "pedido-1234",
"expires_in": 3600,
"cart": []map[string]any{{
"product_hash": "B2XVAM1H",
"title": "Curso de Marketing Digital",
"price": 150.00,
"quantity": 1,
}},
"tracking": map[string]string{
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "black-friday-2025",
"utm_content": "banner-topo",
"utm_term": "marketing digital",
"src": "fb-ads",
"sck": "subid-abc123",
},
})
req, _ := http.NewRequest("POST", "https://app.playpayments.com.br/api/pix", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
fmt.Println(data["pix_code"])
}
require 'net/http'
require 'json'
uri = URI('https://app.playpayments.com.br/api/pix')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'
req['Content-Type'] = 'application/json'
req.body = {
payment_method: 'pix',
amount: 150.00,
customer: {
name: 'João Silva', email: 'joao@email.com',
document: '12345678900', phone: '11999999999'
},
title: 'Pedido #1234',
description: 'Curso de Marketing Digital',
external_id: 'pedido-1234',
expires_in: 3600,
cart: [{
product_hash: 'B2XVAM1H',
title: 'Curso de Marketing Digital',
price: 150.00,
quantity: 1
}],
tracking: {
utm_source: 'facebook',
utm_medium: 'cpc',
utm_campaign: 'black-friday-2025',
utm_content: 'banner-topo',
utm_term: 'marketing digital',
src: 'fb-ads',
sck: 'subid-abc123'
}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)['pix_code']
OkHttpClient client = new OkHttpClient();
JSONObject customer = new JSONObject()
.put("name", "João Silva")
.put("email", "joao@email.com")
.put("document", "12345678900")
.put("phone", "11999999999");
JSONObject cartItem = new JSONObject()
.put("product_hash", "B2XVAM1H")
.put("title", "Curso de Marketing Digital")
.put("price", 150.00)
.put("quantity", 1);
JSONObject tracking = new JSONObject()
.put("utm_source", "facebook")
.put("utm_medium", "cpc")
.put("utm_campaign", "black-friday-2025")
.put("utm_content", "banner-topo")
.put("utm_term", "marketing digital")
.put("src", "fb-ads")
.put("sck", "subid-abc123");
String body = new JSONObject()
.put("payment_method", "pix")
.put("amount", 150.00)
.put("customer", customer)
.put("title", "Pedido #1234")
.put("description", "Curso de Marketing Digital")
.put("external_id", "pedido-1234")
.put("expires_in", 3600)
.put("cart", new JSONArray().put(cartItem))
.put("tracking", tracking)
.toString();
Request req = new Request.Builder()
.url("https://app.playpayments.com.br/api/pix")
.post(RequestBody.create(body, MediaType.get("application/json")))
.addHeader("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
.build();
try (Response r = client.newCall(req).execute()) {
JSONObject data = new JSONObject(r.body().string());
System.out.println(data.getString("pix_code"));
}
using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_prod_SUA_SECRET_KEY");
var res = await client.PostAsJsonAsync("https://app.playpayments.com.br/api/pix", new {
payment_method = "pix",
amount = 150.00,
customer = new {
name = "João Silva", email = "joao@email.com",
document = "12345678900", phone = "11999999999"
},
title = "Pedido #1234",
description = "Curso de Marketing Digital",
external_id = "pedido-1234",
expires_in = 3600,
cart = new[] { new {
product_hash = "B2XVAM1H",
title = "Curso de Marketing Digital",
price = 150.00,
quantity = 1
}},
tracking = new {
utm_source = "facebook", utm_medium = "cpc",
utm_campaign = "black-friday-2025", utm_content = "banner-topo",
utm_term = "marketing digital", src = "fb-ads", sck = "subid-abc123"
}
});
var data = await res.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(data.GetProperty("pix_code").GetString());
{
"success": true,
"transaction_id": "txn_abc123",
"pix_code": "00020126...",
"qr_code": "00020126...",
"amount": 150.0,
"fee_amount": 2.25,
"net_amount": 147.75,
"status": "pending",
"expires_at": "2025-01-01T01:00:00Z",
"created_at": "2025-01-01T00:00:00Z"
}
Consultar Cobrança
Retorna detalhes completos de uma cobrança. O status é sincronizado em tempo real com o gateway.
/api/pix/{transaction_id}
curl https://app.playpayments.com.br/api/pix/{transaction_id} \
-H "Authorization: Bearer sk_prod_SUA_SECRET_KEY"
const { data } = await axios.get('https://app.playpayments.com.br/api/pix/{transaction_id}', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
// data.status: pending | paid | expired | cancelled
const res = await fetch('https://app.playpayments.com.br/api/pix/{transaction_id}', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
const data = await res.json();
// data.status: pending | paid | expired | cancelled
import requests
res = requests.get('https://app.playpayments.com.br/api/pix/{transaction_id}',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(res.json())
// data.status: pending | paid | expired | cancelled
async with httpx.AsyncClient() as c:
r = await c.get('https://app.playpayments.com.br/api/pix/{transaction_id}',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(r.json())
// data.status: pending | paid | expired | cancelled
$res = $client->get('https://app.playpayments.com.br/api/pix/{transaction_id}', ['headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode($res->getBody(), true);
$ch = curl_init('https://app.playpayments.com.br/api/pix/{transaction_id}');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode(curl_exec($ch), true);
req, _ := http.NewRequest("GET", "https://app.playpayments.com.br/api/pix/{transaction_id}", nil)
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
resp, _ := http.DefaultClient.Do(req)
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
uri = URI('https://app.playpayments.com.br/api/pix/{transaction_id}')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)
Request req = new Request.Builder()
.url("https://app.playpayments.com.br/api/pix/{transaction_id}")
.addHeader("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
.build();
try (Response r = client.newCall(req).execute()) {
System.out.println(r.body().string());
}
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_prod_SUA_SECRET_KEY");
var data = await client.GetFromJsonAsync<JsonElement>("https://app.playpayments.com.br/api/pix/{transaction_id}");
{
"success": true,
"transaction_id": "txn_abc123",
"status": "paid",
"amount": 150.0,
"fee_amount": 2.25,
"net_amount": 147.75,
"pix_code": "00020126...",
"paid_at": "2025-01-01T00:15:30Z",
"expires_at": "2025-01-01T01:00:00Z"
}
Verificar Status
Endpoint leve que retorna apenas o status. Ideal para polling a cada 2–3 segundos enquanto aguarda o pagamento.
/api/pix/status/{transaction_id}curl https://app.playpayments.com.br/api/pix/status/{transaction_id} \
-H "Authorization: Bearer sk_prod_SUA_SECRET_KEY"
const { data } = await axios.get('https://app.playpayments.com.br/api/pix/status/{transaction_id}', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
// Leve — ideal para polling
const res = await fetch('https://app.playpayments.com.br/api/pix/status/{transaction_id}', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
const data = await res.json();
// Leve — ideal para polling
import requests
res = requests.get('https://app.playpayments.com.br/api/pix/status/{transaction_id}',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(res.json())
// Leve — ideal para polling
async with httpx.AsyncClient() as c:
r = await c.get('https://app.playpayments.com.br/api/pix/status/{transaction_id}',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(r.json())
// Leve — ideal para polling
$res = $client->get('https://app.playpayments.com.br/api/pix/status/{transaction_id}', ['headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode($res->getBody(), true);
$ch = curl_init('https://app.playpayments.com.br/api/pix/status/{transaction_id}');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode(curl_exec($ch), true);
req, _ := http.NewRequest("GET", "https://app.playpayments.com.br/api/pix/status/{transaction_id}", nil)
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
resp, _ := http.DefaultClient.Do(req)
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
uri = URI('https://app.playpayments.com.br/api/pix/status/{transaction_id}')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)
Request req = new Request.Builder()
.url("https://app.playpayments.com.br/api/pix/status/{transaction_id}")
.addHeader("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
.build();
try (Response r = client.newCall(req).execute()) {
System.out.println(r.body().string());
}
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_prod_SUA_SECRET_KEY");
var data = await client.GetFromJsonAsync<JsonElement>("https://app.playpayments.com.br/api/pix/status/{transaction_id}");
{
"success": true,
"transaction_id": "txn_abc123",
"status": "paid",
"paid_at": "2025-01-01T00:15:30Z",
"expires_at": "2025-01-01T01:00:00Z"
}
Listar Cobranças
Lista cobranças PIX com paginação e filtros.
/api/pixQuery Parameters
| Campo | Tipo | Req | Descrição |
|---|---|---|---|
| page | integer | opcional | Página — padrão 1 |
| per_page | integer | opcional | Itens por página — máximo 100 |
| status | string | opcional | Filtrar: pending, paid, expired, cancelled |
| start_date | date | opcional | Data inicial — formato YYYY-MM-DD |
| end_date | date | opcional | Data final — formato YYYY-MM-DD |
curl https://app.playpayments.com.br/api/pix?status=paid&per_page=20 \ -H "Authorization: Bearer sk_prod_SUA_SECRET_KEY"
const { data } = await axios.get('https://app.playpayments.com.br/api/pix?status=paid&per_page=20', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
// data.data[] + data.pagination
const res = await fetch('https://app.playpayments.com.br/api/pix?status=paid&per_page=20', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
const data = await res.json();
// data.data[] + data.pagination
import requests
res = requests.get('https://app.playpayments.com.br/api/pix?status=paid&per_page=20',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(res.json())
// data.data[] + data.pagination
async with httpx.AsyncClient() as c:
r = await c.get('https://app.playpayments.com.br/api/pix?status=paid&per_page=20',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(r.json())
// data.data[] + data.pagination
$res = $client->get('https://app.playpayments.com.br/api/pix?status=paid&per_page=20', ['headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode($res->getBody(), true);
$ch = curl_init('https://app.playpayments.com.br/api/pix?status=paid&per_page=20');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode(curl_exec($ch), true);
req, _ := http.NewRequest("GET", "https://app.playpayments.com.br/api/pix?status=paid&per_page=20", nil)
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
resp, _ := http.DefaultClient.Do(req)
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
uri = URI('https://app.playpayments.com.br/api/pix?status=paid&per_page=20')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)
Request req = new Request.Builder()
.url("https://app.playpayments.com.br/api/pix?status=paid&per_page=20")
.addHeader("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
.build();
try (Response r = client.newCall(req).execute()) {
System.out.println(r.body().string());
}
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_prod_SUA_SECRET_KEY");
var data = await client.GetFromJsonAsync<JsonElement>("https://app.playpayments.com.br/api/pix?status=paid&per_page=20");
{"success":true,"data":[{{"transaction_id":"txn_abc123","amount":150.00,"status":"paid","created_at":"..."}}],"pagination":{{"total":150,"per_page":20,"current_page":1,"last_page":8}}}}
Saque PIX
Envia um PIX para uma chave externa (PIX Out). Requer Secret Key.
/api/v1/withdrawals
Parâmetros
| Campo | Tipo | Req | Descrição |
|---|---|---|---|
| amount | number | obrigatório | Valor em R$ a sacar |
| pix_key | string | obrigatório | Chave PIX do destinatário |
| pix_type | string | obrigatório | cpf · cnpj · email · phone · random |
| description | string | opcional | Descrição do saque |
curl -X POST https://app.playpayments.com.br/api/v1/withdrawals \
-H "Authorization: Bearer sk_prod_SUA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{{"amount":100.00,"pix_key":"joao@email.com","pix_type":"email"}}'
await axios.post('https://app.playpayments.com.br/api/v1/withdrawals', {
amount: 100.00, pix_key: 'joao@email.com', pix_type: 'email'
}, { headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' } });
await fetch('https://app.playpayments.com.br/api/v1/withdrawals', {
method: 'POST',
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: 100.00, pix_key: 'joao@email.com', pix_type: 'email' })
});
requests.post('https://app.playpayments.com.br/api/v1/withdrawals',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'},
json={'amount': 100.00, 'pix_key': 'joao@email.com', 'pix_type': 'email'}
)
await c.post('https://app.playpayments.com.br/api/v1/withdrawals',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'},
json={'amount': 100.00, 'pix_key': 'joao@email.com', 'pix_type': 'email'}
)
$client->post('https://app.playpayments.com.br/api/v1/withdrawals', [
'headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY'],
'json' => ['amount' => 100.00, 'pix_key' => 'joao@email.com', 'pix_type' => 'email']
]);
$ch = curl_init('https://app.playpayments.com.br/api/v1/withdrawals');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['amount'=>100.00,'pix_key'=>'joao@email.com','pix_type'=>'email']), CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY','Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true]);
curl_exec($ch);
body, _ := json.Marshal(map[string]any{"amount": 100.00, "pix_key": "joao@email.com", "pix_type": "email"})
req, _ := http.NewRequest("POST", "https://app.playpayments.com.br/api/v1/withdrawals", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)
req = Net::HTTP::Post.new(URI('https://app.playpayments.com.br/api/v1/withdrawals'))
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'; req['Content-Type'] = 'application/json'
req.body = {amount: 100.00, pix_key: 'joao@email.com', pix_type: 'email'}.to_json
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
String body = new JSONObject().put("amount",100.00).put("pix_key","joao@email.com").put("pix_type","email").toString();
Request req = new Request.Builder().url("https://app.playpayments.com.br/api/v1/withdrawals").post(RequestBody.create(body,MediaType.get("application/json"))).addHeader("Authorization","Bearer sk_prod_SUA_SECRET_KEY").build();
client.newCall(req).execute();
await client.PostAsJsonAsync("https://app.playpayments.com.br/api/v1/withdrawals", new { amount = 100.00, pix_key = "joao@email.com", pix_type = "email" });
{"success":true,"withdrawal_id":"wth_xyz789","amount":100.00,"status":"processing","pix_key":"joao@email.com","created_at":"2025-01-01T00:00:00Z"}
Saldo
Retorna o saldo disponível da conta.
/api/v1/balancecurl https://app.playpayments.com.br/api/v1/balance \ -H "Authorization: Bearer sk_prod_SUA_SECRET_KEY"
const { data } = await axios.get('https://app.playpayments.com.br/api/v1/balance', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
// data.balance: float em BRL
const res = await fetch('https://app.playpayments.com.br/api/v1/balance', {
headers: { Authorization: 'Bearer sk_prod_SUA_SECRET_KEY' }
});
const data = await res.json();
// data.balance: float em BRL
import requests
res = requests.get('https://app.playpayments.com.br/api/v1/balance',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(res.json())
// data.balance: float em BRL
async with httpx.AsyncClient() as c:
r = await c.get('https://app.playpayments.com.br/api/v1/balance',
headers={'Authorization': 'Bearer sk_prod_SUA_SECRET_KEY'}
)
print(r.json())
// data.balance: float em BRL
$res = $client->get('https://app.playpayments.com.br/api/v1/balance', ['headers' => ['Authorization' => 'Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode($res->getBody(), true);
$ch = curl_init('https://app.playpayments.com.br/api/v1/balance');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_prod_SUA_SECRET_KEY']]);
$data = json_decode(curl_exec($ch), true);
req, _ := http.NewRequest("GET", "https://app.playpayments.com.br/api/v1/balance", nil)
req.Header.Set("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
resp, _ := http.DefaultClient.Do(req)
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)
uri = URI('https://app.playpayments.com.br/api/v1/balance')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_prod_SUA_SECRET_KEY'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)
Request req = new Request.Builder()
.url("https://app.playpayments.com.br/api/v1/balance")
.addHeader("Authorization", "Bearer sk_prod_SUA_SECRET_KEY")
.build();
try (Response r = client.newCall(req).execute()) {
System.out.println(r.body().string());
}
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_prod_SUA_SECRET_KEY");
var data = await client.GetFromJsonAsync<JsonElement>("https://app.playpayments.com.br/api/v1/balance");
{
"success": true,
"balance": 1250.0,
"currency": "BRL"
}
Webhooks
Receba notificações automáticas quando uma transação for paga, expirar ou for cancelada. Configure sua URL em Configurações → Webhooks.
Payload de exemplo
{
"event": "transaction.paid",
"transaction_id": "txn_abc123",
"external_id": "pedido-1234",
"amount": 150.00,
"status": "paid",
"paid_at": "2025-01-01T00:15:30Z",
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900"
}
}
Eventos disponíveis
| Evento | Descrição |
|---|---|
| transaction.paid | Pagamento PIX confirmado |
| transaction.expired | Cobrança expirou sem pagamento |
| transaction.cancelled | Cobrança cancelada |
| withdrawal.completed | Saque PIX processado com sucesso |
| withdrawal.failed | Falha no processamento do saque |
Erros
A API usa códigos HTTP padrão. Erros retornam JSON com success: false e uma mensagem.
| Código | Significado |
|---|---|
| 401 | Token ausente ou inválido |
| 403 | Public Key usada em endpoint de escrita |
| 404 | Transação não encontrada |
| 422 | Validação falhou — ver campo errors |
| 400 | Parâmetro inválido ou gateway indisponível |
| 500 | Erro interno do servidor |
{"success":false,"error":"Dados inválidos","errors":{"amount":["O campo amount é obrigatório."]}}
Integração UTMify
Envie dados de conversão para a UTMify automaticamente a cada pagamento PIX confirmado.
Use o webhook transaction.paid para disparar a notificação.
Fluxo
| Etapa | Ação |
|---|---|
| 1 | Cliente acessa com UTMs — salve no backend/cookie |
| 2 | Crie a cobrança PIX na PlayPayments POST /api/pix
|
| 3 | Webhook transaction.paid chega no seu servidor |
| 4 | POST para UTMify com dados da venda + UTMs capturados |
Mapeamento PlayPayments → UTMify
| PlayPayments (webhook) | UTMify | Transformação |
|---|---|---|
| transaction_id | orderId | Direto |
| amount | totalPriceInCents | × 100 |
| fee_amount | gatewayFeeInCents | × 100 |
| net_amount | userCommissionInCents | × 100 |
| paid_at | approvedDate | YYYY-MM-DD HH:MM:SS |
| status: paid | status: paid | — |
| status: pending | status: waiting_payment | Mapeado |
| utm_* (cookies) | trackingParameters | Capturar no frontend |
Payload para UTMify (cURL)
curl -X POST https://api.utmify.com.br/api-credentials/orders \
-H "x-api-token: SEU_TOKEN_UTMIFY" \
-H "Content-Type: application/json" \
-d '{
"orderId": "txn_abc123",
"platform": "PlayPayments",
"paymentMethod": "pix",
"status": "paid",
"createdAt": "2025-01-01 00:00:00",
"approvedDate": "2025-01-01 00:15:30",
"refundedAt": null,
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"phone": "11999999999",
"document": "12345678900",
"country": "BR",
"ip": "177.0.0.1"
},
"products": [{
"id": "produto-001",
"name": "Produto PlayPayments",
"planId": null,
"planName": null,
"quantity": 1,
"priceInCents": 15000
}],
"trackingParameters": {
"src": null,
"sck": null,
"utm_source": "FB",
"utm_campaign": "CAMPANHA|ID",
"utm_medium": "CONJUNTO|ID",
"utm_content": "ANUNCIO|ID",
"utm_term": null
},
"commission": {
"totalPriceInCents": 15000,
"gatewayFeeInCents": 225,
"userCommissionInCents": 14775,
"currency": "BRL"
},
"isTest": false
}'