PIX Checkout API Documentation

Overview

The PIX Checkout API provides a powerful and efficient solution for processing multiple PIX payments in a single operation. Designed for businesses that need to send bulk payments to suppliers, service providers, employees, or any other beneficiaries, this API streamlines the payment process while maintaining security and reliability.

Key Features:

Bulk PIX Payments: Process hundreds or thousands of PIX payments in a single checkout operation
Automated Processing: Schedule and execute payments automatically with minimal manual intervention
Real-time Monitoring: Track checkout status and individual payment progress in real-time
Flexible PIX Keys: Support for all PIX key types (CPF, CNPJ, email, phone, random key, and bank account)
Comprehensive Reporting: Detailed reports on checkout processing results and individual payment status
Secure Operations: Bank-grade security with OAuth 2.0 authentication and transaction tracking

Getting Started

Prerequisites

Before integrating with the PIX Checkout API, ensure you have:

Astrapay Account: Active merchant account with PIX Checkout service enabled
API Credentials: Client ID and Client Secret for OAuth 2.0 authentication
Bank Account: Valid bank account for checkout debit operations
PIX Keys: Valid PIX keys for all payment beneficiaries

Authentication

All API requests require OAuth 2.0 authentication using a Bearer token obtained here.

Base URLs

Sandbox: https://api-sandbox.astrapay.com.br/v1
Production: https://api.astrapay.com.br/v1

Common Headers

All API requests must include:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
x-transaction-id: 550e8400-e29b-41d4-a716-446655440000

How It Works

1. Checkout Creation

Create a new PIX checkout with multiple payments:

{
  "checkoutId": "PAYROLL_JAN_2025",
  "debitAccount": {
    "agency": "1234",
    "account": "987654321",
    "accountType": "CHECKING",
    "accountDigit": "5"
  },
  "payments": [
    {
      "paymentId": "EMP_001",
      "pixKey": {
        "type": "CPF",
        "value": "12345678901"
      },
      "amount": 5000.00,
      "beneficiaryName": "João Silva",
      "description": "Salary - January 2025"
    },
    {
      "paymentId": "EMP_002",
      "pixKey": {
        "type": "EMAIL",
        "value": "[email protected]"
      },
      "amount": 4500.00,
      "beneficiaryName": "Maria Santos",
      "description": "Salary - January 2025"
    }
  ],
  "userReference": "PAYROLL_JANUARY_2025"
}

2. Checkout Release

Authorize the checkout for processing:

PUT /pix-checkout/PAYROLL_JAN_2025/release

3. Status Monitoring

Monitor checkout and payment status:

GET /pix-checkout/PAYROLL_JAN_2025
GET /pix-checkout/PAYROLL_JAN_2025/payments

Use Cases

🏢 Payroll Processing

Scenario: Monthly salary payments to employees
Benefits: Automated payroll processing, reduced manual work, faster payments
Example: 500 employees receiving salaries via PIX

🏪 Supplier Payments

Scenario: Regular payments to suppliers and vendors
Benefits: Streamlined accounts payable, better cash flow management
Example: Weekly payments to 50 suppliers

💰 Commission Payments

Scenario: Sales commission and bonus distributions
Benefits: Timely commission payments, improved sales team satisfaction
Example: Monthly commission payments to 200 sales representatives

🎯 Marketing Campaigns

Scenario: Promotional payments and cashback programs
Benefits: Automated campaign execution, real-time payment tracking
Example: Cashback payments to 1000 customers

📊 Financial Services

Scenario: Investment returns and dividend distributions
Benefits: Automated distribution processing, accurate record keeping
Example: Quarterly dividend payments to 500 investors