Começar

Autenticação

Todas as requisições autenticadas devem incluir sua API Key no header Authorization.

HEADER DE AUTENTICAÇÃO
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)
Nunca exponha sua Secret Key no frontend. Use apenas no servidor.

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.

Começar

Base URL

Use a URL abaixo como prefixo para todas as chamadas da API.

BASE URL
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)
PIX

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.

POST/api/pix

Campos obrigatórios

CampoTipoReqDescriçã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

CampoTipoDescriçã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'];
RESPOSTA 201
{
  "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());
RESPOSTA 201
{
  "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"
}
PIX

Consultar Cobrança

Retorna detalhes completos de uma cobrança. O status é sincronizado em tempo real com o gateway.

GET/api/pix/{transaction_id}
pending paid expired cancelled failed
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}");
RESPOSTA 200
{
  "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"
}
PIX

Verificar Status

Endpoint leve que retorna apenas o status. Ideal para polling a cada 2–3 segundos enquanto aguarda o pagamento.

GET/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}");
RESPOSTA 200
{
  "success": true,
  "transaction_id": "txn_abc123",
  "status": "paid",
  "paid_at": "2025-01-01T00:15:30Z",
  "expires_at": "2025-01-01T01:00:00Z"
}
PIX

Listar Cobranças

Lista cobranças PIX com paginação e filtros.

GET/api/pix

Query 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");
RESPOSTA 200
{"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}}}}
Financeiro

Saque PIX

Envia um PIX para uma chave externa (PIX Out). Requer Secret Key.

POST/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" });
RESPOSTA 201
{"success":true,"withdrawal_id":"wth_xyz789","amount":100.00,"status":"processing","pix_key":"joao@email.com","created_at":"2025-01-01T00:00:00Z"}
Financeiro

Saldo

Retorna o saldo disponível da conta.

GET/api/v1/balance
curl 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");
RESPOSTA 200
{
  "success": true,
  "balance": 1250.0,
  "currency": "BRL"
}
Notificações

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"
  }
}
Responda com HTTP 200 para confirmar. Reenvios automáticos: 1min → 5min → 30min → 2h → 24h.

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
Referência

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."]}}
UTMIFY

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.

ENDPOINT UTMIFY
POST https://api.utmify.com.br/api-credentials/orders

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
  }'