Documentação API PIX

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