PIX Charge API - Testing and Validation

Overview

This document provides testing guidelines and validation procedures for the PIX Charge API. It includes endpoint testing, authentication setup, and validation scenarios to ensure proper integration.

🔧 Getting Started

Prerequisites

Valid Astrapay account
API credentials (client ID and secret)

Authentication

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

Base URLs

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

Common Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by the client)

📡 API Endpoints

1. Create Dynamic QRCode PIX Charge

POST /v1/dynamic

Creates a new dynamic QRCode PIX charge with customizable expiration times.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Request Body

{
  "amount": 100.00,
  "expiration": 3600,
  "description": "Payment for order #12345",
  "userReference": "order-12345",
  "debtor": {
    "name": "João Silva",
    "naturalPersonIdentification": "12345678901"
  },
  "validateDebtor": false
}

Important Notes:

userReference: Optional field that allows clients to send their own identifier or any other information they want. This field is included in webhook notifications, making it useful for correlating webhook events with your internal systems.
debtor: Optional debtor information. If provided, you can specify either naturalPersonIdentification (CPF) or legalPersonIdentification (CNPJ), but not both.
validateDebtor: When set to true, only the specified debtor can make the payment. Payments from other people will be automatically refunded.

⚠️ Sandbox Environment Note:
In the sandbox environment, charges created with amounts ending in 1 cent (e.g., 0.01, 1.01, 2.01, etc.) will be automatically paid within 1 minute. After this automatic payment, the webhook will be triggered to your registered URL. This feature is designed for testing webhook integration without manual payment simulation.

Response

{
  "txid": "astra202412dfsdrtsdgdgdst00005Z",
  "amount": 100.00,
  "status": {
        "code": "2",
        "description": "ACTIVE"
  },
  "pixCopyAndPaste": "00020126580014br.gov.bcb.pix...",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "description": "Payment for order #12345",
  "userReference": "order-12345",
  "debtor": {
    "name": "João Silva",
    "naturalPersonIdentification": "12345678901"
  },
  "calendar": {
    "creationDate": "2024-01-15T10:30:00.000Z",
    "expirationDate": "2024-01-15T11:30:00.000Z"
  }
}

Important: The txid is the unique identifier for the charge, generated by our system and returned in the creation response. This identifier is used for all subsequent operations (consultation, refunds) and is included in webhook notifications.

2. List Dynamic QRCode PIX Charges

GET /v1/dynamic

Retrieves a paginated list of dynamic PIX charges with filtering options.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Query Parameters

initialDate (required): Start date for the search
endDate (required): End date for the search
status (optional): Filter by charge status
naturalPersonIdentification (optional): Filter by CPF
legalPersonIdentification (optional): Filter by CNPJ
userReference (optional): Filter by user reference
page (optional): Page number (default: 0)
size (optional): Page size (default: 20)

Available Status Values

Status	Description
`ACTIVE`	Charge was created but not yet paid or expired
`PAID`	Charge has been paid and cannot accept another payment
`EXPIRED`	Charge has expired and is no longer valid
`PARTIALLY REFUNDED`	Charge was refunded for less than the full amount
`REFUNDED`	Charge was refunded in full

Example Request

GET /v1/charges/instant?initialDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z&status=ACTIVE&page=0&size=20

3. Consult Dynamic PIX Charge

GET /v1/dynamic/{txid}

Retrieves detailed information about a specific PIX charge.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Path Parameters

txid: The transaction ID of the charge to consult (this is the unique identifier returned when creating the charge)

4. Create Refund

POST /v1/refunds

Creates a refund request for a paid PIX charge.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Request Body

{
  "txid": "astra202412dfsdrtsdgdgdst00005Z",
  "amount": 50.00,
  "description": "Partial refund for order #12345"
}

Note: The txid must be the unique identifier of a paid charge. You can only refund charges that have been paid.

5. List Refunds

GET /v1/refunds

Retrieves a paginated list of refunds with filtering options.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Query Parameters

initialDate (required): Start date for the search
endDate (required): End date for the search
status (optional): Filter by refund status
statusReason (optional): Filter by refund status reason
page (optional): Page number (default: 0)
size (optional): Page size (default: 20)

Available Refund Status Values

Status	Description
`PROCESSING`	Refund is being processed
`COMPLETED`	Refund has been completed successfully
`FAILED`	Refund processing failed
`CANCELLED`	Refund was cancelled

6. Consult Refund

GET /v1/refunds/{refundId}

Retrieves detailed information about a specific refund.

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Path Parameters

refundId: The refund ID to consult (this is the unique identifier returned when creating the refund)

7. Generate Static QR Code

POST /v1/cob-static/encode

Generates a static QR code for PIX payments.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Request Body

{
  "keyPix": "[email protected]",
  "merchantName": "Your Store Name",
  "merchantCity": "São Paulo",
  "amount": 100.00,
  "txid": "static-qr-001"
}

8. Decode Static QR Code

POST /v1/cob-static/decode

Decodes and reads information from a static QR code.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (new UUID generated by you)

Request Body

{
  "copyPast": "00020126580014br.gov.bcb.pix..."
}