API PIX
Crie cobranças via PIX de forma programática para lojas nacionais.
🔑 Autenticação Necessária: Para usar esta API, você precisa incluir sua API Key no header de todas as requisições. Saiba mais sobre autenticação →
Endpoint
POST
Criar Cobrança PIX
Cria uma nova cobrança via PIX e retorna o código PIX Copia e Cola para pagamento.
https://app.aproveicheckout.com.br/api/checkout
Headers
| Campo | Tipo | Descrição |
|---|---|---|
api-key Obrigatório |
string | Sua API Key de autenticação |
Content-Type |
string | Deve ser application/json |
Parâmetros da Requisição
Customer (cliente) Obrigatório
| Campo | Tipo | Descrição |
|---|---|---|
customer.name Obrigatório |
string | Nome completo do cliente |
customer.document Obrigatório |
string | CPF do cliente (apenas números) |
customer.email Obrigatório |
string | E-mail do cliente |
customer.phone Obrigatório |
string | Telefone do cliente com código do país (ex: +5511999999999) |
Customer Address (endereço) Obrigatório
| Campo | Tipo | Descrição |
|---|---|---|
customer.address.street Obrigatório |
string | Logradouro do endereço |
customer.address.number Obrigatório |
string | Número do endereço |
customer.address.district Obrigatório |
string | Bairro do endereço |
customer.address.zipcode Obrigatório |
string | CEP do endereço (apenas números) |
customer.address.city Obrigatório |
string | Cidade do endereço |
customer.address.state Obrigatório |
string | Estado do endereço (UF - 2 caracteres) |
customer.address.complement Opcional |
string | Complemento do endereço |
Products (produtos) Obrigatório
Array de produtos da venda
| Campo | Tipo | Descrição |
|---|---|---|
products[x].code Obrigatório |
string | Código único do produto no seu sistema |
products[x].name Obrigatório |
string | Nome do produto |
products[x].price Obrigatório |
integer | Valor unitário em centavos (ex: R$10,00 = 1000) |
products[x].is_digital Obrigatório |
boolean | Se o produto é digital (true/false) |
products[x].quantity Obrigatório |
integer | Quantidade do produto |
products[x].description Opcional |
string | Descrição do produto |
products[x].image_url Opcional |
string | URL da imagem do produto |
products[x].file_url Opcional |
string | URL do arquivo (para produtos digitais) |
Payment (pagamento) Obrigatório
| Campo | Tipo | Descrição |
|---|---|---|
payment.method Obrigatório |
string | Método de pagamento. Use 'pix' para PIX |
payment.payment_value Obrigatório |
integer | Valor total da venda em centavos (Produtos + Frete - Desconto) |
payment.freight_value Obrigatório |
integer | Valor do frete em centavos |
payment.discount_value Obrigatório |
integer | Valor de desconto em centavos |
payment.external_code Opcional |
string | Código externo do pedido no seu sistema |
payment.currency Obrigatório |
string | Moeda do pagamento. Use 'BRL' para Real brasileiro |
Tracking (rastreamento) Opcional
| Campo | Tipo | Descrição |
|---|---|---|
notification_url |
string | URL para receber webhooks de atualização |
src |
string | Origem da venda (ex: "checkout_web") |
utm_medium |
string | UTM Medium para rastreamento |
utm_source |
string | UTM Source para rastreamento |
utm_campaign |
string | UTM Campaign para rastreamento |
utm_content |
string | UTM Content para rastreamento |
utm_term |
string | UTM Term para rastreamento |
Exemplo de Requisição
cURL
curl --location 'https://app.aproveicheckout.com.br/api/checkout' \
--header 'api-key: SUA_API_KEY_AQUI' \
--header 'Content-Type: application/json' \
--data '{
"customer": {
"name": "Teste da Silva",
"email": "teste.silva@example.com",
"document": "74600027043",
"phone": "+5511999999999",
"address": {
"street": "Av. Paulista",
"number": "1000",
"complement": "Apto 101",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zipcode": "01310000"
}
},
"payment": {
"method": "pix",
"payment_value": 11000,
"freight_value": 2000,
"discount_value": 1000,
"external_code": "EX001",
"currency": "BRL"
},
"products": [
{
"name": "Camiseta Azul",
"price": 5000,
"quantity": 2,
"code": "SKU123",
"is_digital": false,
"description": "Camiseta de algodão azul tamanho M",
"image_url": "https://example.com/images/camiseta-azul.jpg"
},
{
"name": "Seguro",
"price": 1000,
"quantity": 1,
"code": "SKU456",
"is_digital": true,
"description": "Seguro para a Camisa",
"image_url": "https://example.com/images/tenis.jpg",
"file_url": "https://example.com/images/tenis.jpg"
}
],
"notification_url": "https://example.com/notification",
"src": "checkout_web",
"utm_medium": "cpc",
"utm_source": "google",
"utm_campaign": "verao2025",
"utm_content": "banner_home",
"utm_term": "camiseta azul"
}'
Node.js (Axios)
const axios = require('axios');
const data = {
customer: {
name: "Teste da Silva",
email: "teste.silva@example.com",
document: "74600027043",
phone: "+5511999999999",
address: {
street: "Av. Paulista",
number: "1000",
complement: "Apto 101",
district: "Bela Vista",
city: "São Paulo",
state: "SP",
zipcode: "01310000"
}
},
payment: {
method: "pix",
payment_value: 11000,
freight_value: 2000,
discount_value: 1000,
external_code: "EX001",
currency: "BRL"
},
products: [
{
name: "Camiseta Azul",
price: 5000,
quantity: 2,
code: "SKU123",
is_digital: false,
description: "Camiseta de algodão azul tamanho M",
image_url: "https://example.com/images/camiseta-azul.jpg"
}
],
notification_url: "https://example.com/notification",
src: "checkout_web"
};
axios.post('https://app.aproveicheckout.com.br/api/checkout', data, {
headers: {
'api-key': 'SUA_API_KEY_AQUI',
'Content-Type': 'application/json'
}
})
.then(response => {
console.log('Sucesso:', response.data);
const pixCode = response.data.pix_copy_paste;
const qrCode = response.data.pix_qrcode;
})
.catch(error => {
console.error('Erro:', error.response?.data || error.message);
});
PHP (cURL)
<?php
$apiKey = 'SUA_API_KEY_AQUI';
$url = 'https://app.aproveicheckout.com.br/api/checkout';
$data = [
'customer' => [
'name' => 'Teste da Silva',
'email' => 'teste.silva@example.com',
'document' => '74600027043',
'phone' => '+5511999999999',
'address' => [
'street' => 'Av. Paulista',
'number' => '1000',
'complement' => 'Apto 101',
'district' => 'Bela Vista',
'city' => 'São Paulo',
'state' => 'SP',
'zipcode' => '01310000'
]
],
'payment' => [
'method' => 'pix',
'payment_value' => 11000,
'freight_value' => 2000,
'discount_value' => 1000,
'external_code' => 'EX001',
'currency' => 'BRL'
],
'products' => [
[
'name' => 'Camiseta Azul',
'price' => 5000,
'quantity' => 2,
'code' => 'SKU123',
'is_digital' => false,
'description' => 'Camiseta de algodão azul tamanho M',
'image_url' => 'https://example.com/images/camiseta-azul.jpg'
],
[
'name' => 'Seguro',
'price' => 1000,
'quantity' => 1,
'code' => 'SKU456',
'is_digital' => true,
'description' => 'Seguro para a Camisa',
'image_url' => 'https://example.com/images/tenis.jpg',
'file_url' => 'https://example.com/images/tenis.jpg'
]
],
'notification_url' => 'https://example.com/notification',
'src' => 'checkout_web',
'utm_medium' => 'cpc',
'utm_source' => 'google',
'utm_campaign' => 'verao2025',
'utm_content' => 'banner_home',
'utm_term' => 'camiseta azul'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'api-key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($statusCode === 200) {
$result = json_decode($response, true);
echo "Transação criada: " . $result['data']['transaction_token'] . "\n";
echo "PIX Copia e Cola: " . $result['data']['pix_copy_paste'] . "\n";
} else {
echo "Erro: " . $response . "\n";
}
JavaScript (Node.js com Axios)
const axios = require('axios');
const apiKey = 'SUA_API_KEY_AQUI';
const url = 'https://app.aproveicheckout.com.br/api/checkout';
const data = {
customer: {
name: 'Teste da Silva',
email: 'teste.silva@example.com',
document: '74600027043',
phone: '+5511999999999',
address: {
street: 'Av. Paulista',
number: '1000',
complement: 'Apto 101',
district: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
zipcode: '01310000'
}
},
payment: {
method: 'pix',
payment_value: 11000,
freight_value: 2000,
discount_value: 1000,
external_code: 'EX001',
currency: 'BRL'
},
products: [
{
name: 'Camiseta Azul',
price: 5000,
quantity: 2,
code: 'SKU123',
is_digital: false,
description: 'Camiseta de algodão azul tamanho M',
image_url: 'https://example.com/images/camiseta-azul.jpg'
},
{
name: 'Seguro',
price: 1000,
quantity: 1,
code: 'SKU456',
is_digital: true,
description: 'Seguro para a Camisa',
image_url: 'https://example.com/images/tenis.jpg',
file_url: 'https://example.com/images/tenis.jpg'
}
],
notification_url: 'https://example.com/notification',
src: 'checkout_web',
utm_medium: 'cpc',
utm_source: 'google',
utm_campaign: 'verao2025',
utm_content: 'banner_home',
utm_term: 'camiseta azul'
};
axios.post(url, data, {
headers: {
'api-key': apiKey,
'Content-Type': 'application/json'
}
})
.then(response => {
console.log('Sucesso:', response.data);
console.log('Token:', response.data.data.transaction_token);
console.log('PIX:', response.data.data.pix_copy_paste);
})
.catch(error => {
console.error('Erro:', error.response?.data || error.message);
});
Python (Requests)
import requests
import json
api_key = 'SUA_API_KEY_AQUI'
url = 'https://app.aproveicheckout.com.br/api/checkout'
headers = {
'api-key': api_key,
'Content-Type': 'application/json'
}
data = {
'customer': {
'name': 'Teste da Silva',
'email': 'teste.silva@example.com',
'document': '74600027043',
'phone': '+5511999999999',
'address': {
'street': 'Av. Paulista',
'number': '1000',
'complement': 'Apto 101',
'district': 'Bela Vista',
'city': 'São Paulo',
'state': 'SP',
'zipcode': '01310000'
}
},
'payment': {
'method': 'pix',
'payment_value': 11000,
'freight_value': 2000,
'discount_value': 1000,
'external_code': 'EX001',
'currency': 'BRL'
},
'products': [
{
'name': 'Camiseta Azul',
'price': 5000,
'quantity': 2,
'code': 'SKU123',
'is_digital': False,
'description': 'Camiseta de algodão azul tamanho M',
'image_url': 'https://example.com/images/camiseta-azul.jpg'
},
{
'name': 'Seguro',
'price': 1000,
'quantity': 1,
'code': 'SKU456',
'is_digital': True,
'description': 'Seguro para a Camisa',
'image_url': 'https://example.com/images/tenis.jpg',
'file_url': 'https://example.com/images/tenis.jpg'
}
],
'notification_url': 'https://example.com/notification',
'src': 'checkout_web',
'utm_medium': 'cpc',
'utm_source': 'google',
'utm_campaign': 'verao2025',
'utm_content': 'banner_home',
'utm_term': 'camiseta azul'
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
result = response.json()
print('Sucesso:', result)
print('Token:', result['data']['transaction_token'])
print('PIX:', result['data']['pix_copy_paste'])
else:
print('Erro:', response.status_code, response.text)
C# (HttpClient)
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
public class PixApiClient
{
private readonly HttpClient _httpClient;
private const string ApiKey = "SUA_API_KEY_AQUI";
private const string ApiUrl = "https://app.aproveicheckout.com.br/api/checkout";
public PixApiClient()
{
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Add("api-key", ApiKey);
}
public async Task CreatePixCharge()
{
var data = new
{
customer = new
{
name = "Teste da Silva",
email = "teste.silva@example.com",
document = "74600027043",
phone = "+5511999999999",
address = new
{
street = "Av. Paulista",
number = "1000",
complement = "Apto 101",
district = "Bela Vista",
city = "São Paulo",
state = "SP",
zipcode = "01310000"
}
},
payment = new
{
method = "pix",
payment_value = 11000,
freight_value = 2000,
discount_value = 1000,
external_code = "EX001",
currency = "BRL"
},
products = new[]
{
new
{
name = "Camiseta Azul",
price = 5000,
quantity = 2,
code = "SKU123",
is_digital = false,
description = "Camiseta de algodão azul tamanho M",
image_url = "https://example.com/images/camiseta-azul.jpg"
}
},
notification_url = "https://example.com/notification",
src = "checkout_web",
utm_source = "google",
utm_campaign = "verao2025"
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await _httpClient.PostAsync(ApiUrl, content);
var result = await response.Content.ReadAsStringAsync();
if (response.IsSuccessStatusCode)
{
Console.WriteLine("Sucesso: " + result);
return result;
}
else
{
Console.WriteLine("Erro: " + result);
throw new Exception("Falha na requisição");
}
}
}
Resposta de Sucesso
200 OK
| Campo | Tipo | Descrição |
|---|---|---|
data.transaction_token |
string | Código interno da transação (enviado no webhook) |
data.external_code |
string | Código externo informado na requisição |
data.amount |
integer | Valor da cobrança em centavos |
data.payment_type |
string | Tipo de pagamento ('pix') |
data.payment_status |
string | Status do pagamento. Valores: 'pending', 'approved', 'refused', 'in_process' |
data.pix_copy_paste |
string | Código PIX Copia e Cola para efetuar o pagamento |
message |
string | Mensagem da requisição |
status |
string | Status da requisição ('success' ou 'error') |
JSON Response
{
"data": {
"transaction_token": "VCP1O8SB9GJ",
"external_code": "EX001",
"amount": 12000,
"payment_type": "pix",
"payment_status": "pending",
"pix_copy_paste": "00020101021226820014br.gov.bcb.pix2560pix.stone.com.br/pix/v2/a9121de8-9590-4f94-a2b3-775063ec40d35204000053039865406120.005802BR5923Mangofy Tecnologia Ltda6014RIO DE JANEIRO62290525fcefc158e567a571fa3670dec63044F21"
},
"message": "Transação criada com sucesso",
"status": "success"
}
✅ Próximos Passos: Após criar a cobrança, você deve exibir o código pix_copy_paste para o cliente ou gerar um QR Code.
Quando o pagamento for confirmado, você receberá uma notificação através do webhook configurado.
Ver documentação de webhooks →
Erros Comuns
Dados Inválidos
422 Unprocessable Entity
{
"status": "error",
"message": "Erro de validação",
"errors": {
"customer.email": ["O campo email é obrigatório"],
"payment.payment_value": ["O valor do pagamento deve ser maior que zero"]
}
}
API Key Inválida
401 Unauthorized
{
"status": "error",
"message": "API Key inválida",
"code": "AUTH_INVALID_KEY"
}
Valores em Centavos
Todos os valores monetários devem ser enviados em centavos. Exemplos:
R$ 10,00
1000
R$ 150,50
15050
R$ 1.250,99
125099