WS ZAPPYPAG - API Documentation

PIX_STATUS.md

PIX Transaction status mapping

1. PIX (pix in)

Internal Status	FitBank Variants Accepted	Description
Created	Created	Receipt credited to receiving account
Registered	Registered	Transaction registered (intermediate state)
Settled	Paid, Settled, Success	Transaction completed successfully
Failed	Failed, Error	Transaction failed
Canceled	Canceled, Cancel	Transaction canceled

2. PIX (withdraw | pix out)

Internal Status	FitBank Variants Accepted	Description
Created	Created	Transaction created
Registered	Registered	Transaction registered (intermediate state)
Settled	Paid, Settled, Success	Transaction completed successfully
Failed	Failed, Error	Transaction failed
Canceled	Canceled, Cancel	Transaction canceled

3. PIX Refund (refund pix in | refund pix out)

Internal Status	FitBank Variants Accepted	Description
Created	Created	Refund created
Registering	Registering	Refund registration in progress
Registered	Registered	Refund registered
Canceled	Cancel, Canceled	Refund canceled
Settled	Paid, Settled	Refund completed

4. QR Code Status

Internal Status	FitBank Value	Description
Created	Created	QR code created
Registering	Registering	Registration in progress
Processed	Processed	QR code processed
Settled	Settled	Payment completed
Error	Error	Error occurred
Canceled	Canceled	QR code canceled
Expired	Expired	QR code expired

Webhook event format

The system normalizes statuses to lowercase for webhook events:

Flow	Event Pattern	Example Events
PIX In	pix.in.{status}	pix.in.paid, pix.in.registered, pix.in.failed
PIX Out	pix.out.{status}	pix.out.paid, pix.out.canceled
Refund In	pix.refund.in.{status}	pix.refund.in.paid, pix.refund.in.registered
Refund Out	pix.refund.out.{status}	pix.refund.out.paid, pix.refund.out.canceled

Note: For BFF compatibility, settled is mapped to paid in webhook events.

ZAPPY_API_DOCS.md

WS ZAPPYPAG - API Documentation

ZAPPY is a Banking as a Service (BaaS) platform. It provides a secure, compliant infrastructure for banking operations with a modern REST API interface.

The platform enables:

• Digital Banking Operations: Account management, transactions, and comprehensive banking services
• PIX Integration: Brazilian instant payment system with QR code generation, payments, and key management
• Identity & Access Management: JWT-based authentication and session management
• Webhook Processing: Event-driven architecture for real-time banking event distribution to customers

Architecture:

1. IAM Service (Identity and Access Management): User authentication, JWT tokens, session management
2. BaaS Service (Banking as a Service): Banking API integration, PIX operations, webhook reception and message transformation
3. Relay Service (Webhook Relay): Distributes webhooks to customers via Pub/Sub (Internal Service - Not documented here)

Platform features:

• Multi-tenant: Supports multiple customers on shared infrastructure
• Event-driven: Uses Pub/Sub for asynchronous webhook processing
• Secure: Defense-in-depth with load balancer, WAF, internal-only serverless services
• Banking Compliant: Audit logging, data retention, and compliance-ready architecture
• High Availability: Redundant infrastructure with in-memory caching and relational data storage

The platform provides a modern API interface for banking operations with robust security, scalability, and compliance features.

---

IAM: Identity and Access Management

The IAM (Identity and Access Management) Service provides authentication and session management for the ZAPPY platform. This service allows you to securely authenticate users, manage access tokens, and maintain user sessions throughout your application. All authentication requests are made through the /iam/v1 endpoint base path.

The service supports standard authentication workflows including user login, logout, and token refresh capabilities. When you successfully authenticate a user, you'll receive both an access token for making authenticated API requests and a refresh token for obtaining new access tokens when they expire. Access tokens are short-lived (15 minutes expiration) for security purposes and should be included in the Authorization header of subsequent API requests to protected endpoints. Refresh tokens are valid for 15 days and can be used to obtain new access tokens without requiring the user to log in again.

For applications using an external session management system, the IAM service provides a BFF (Backend For Frontend) integration endpoint that allows you to exchange your existing session identifiers for ZAPPY access tokens, enabling seamless integration with the platform's banking services.

Authentication

POST /iam/v1/auth/login

Authenticates a user and returns a JWT token and refresh token for subsequent requests. The access_token (JWT has 15 minutes expiration) is used for API requests, while the refresh_token (Hash has 15 days expiration) is used to obtain a new access_token when it expires.

Request:

{
    "username": "string",  // required, email format, min: 3, max: 128
    "password": "string"   // required, min: 8, max: 128
}

Response 200 OK:

{
    "access_token": "string",
    "refresh_token": "string",
    "type": "Bearer",
    "expires_at": 1234567890,
    "user": {
        "id": "string",
        "name": "string",
        "email": "string",
        "roles": ["string"]
    }
}

Response 401 Unauthorized:

{
    "code": 401,
    "message": "user credentials don't match with our records"
}

---

Refresh Token

POST /iam/v1/auth/refresh

Refreshes the access token using a valid refresh token. When your access token expires, use this endpoint to obtain a new access token without requiring the user to log in again. The refresh token itself will also be rotated for security purposes.

Request:

{
    "refresh_token": "string"  // required
}

Response 200 OK:

{
    "access_token": "string",
    "refresh_token": "string",
    "type": "Bearer",
    "expires_at": "2024-01-01T00:00:00Z",
    "user": {
        "id": "string",
        "name": "string",
        "email": "string",
        "roles": ["string"]
    }
}

Response 401 Unauthorized:

{
    "code": 401,
    "message": "the refresh token is invalid"
}

---

Logout

POST /iam/v1/auth/logout

Logs out the user by invalidating the refresh token. After calling this endpoint, both the access token and refresh token will no longer be valid, and the user will need to log in again to obtain new tokens.

Request:

{
    "refresh_token": "string"  // required
}

Response 200 OK:

{
    "code": 200,
    "message": "the user session has been successfully logged out"
}

Response 401 Unauthorized:

{
    "code": 401,
    "message": "the refresh token is invalid"
}

---

BFF Session Integration

POST /iam/v1/bff/session

Creates JWT tokens from an external BFF (Backend For Frontend) session ID. This endpoint enables integration with external session management systems by allowing you to exchange a valid BFF session identifier for ZAPPY access and refresh tokens. The session ID is validated against the external BFF service before tokens are issued.

Request:

{
    "session_id": "string"  // required, max: 255
}

Response 200 OK:

{
    "access_token": "string",
    "refresh_token": "string",
    "type": "Bearer",
    "expires_at": "2024-01-01T00:00:00Z",
    "user": {
        "id": "string",
        "name": "string",
        "email": "string",
        "roles": ["string"]
    }
}

Response 401 Unauthorized:

{
    "error": "invalid_session",
    "message": "Session validation failed",
    "details": {
        "reason": "session invalid or expired"
    }
}

Response 503 Service Unavailable:

{
    "error": "bff_unavailable",
    "message": "BFF service unavailable or endpoint not implemented",
    "details": {
        "error": "string"
    }
}

---

Create User

POST /iam/v1/users

Creates a new user account in the ZAPPY platform. This endpoint requires JWT authentication and allows you to provision new user accounts with their credentials. The password must meet strong password requirements including a mix of letters, numbers, and special characters.

Authentication Required: Authorization: Bearer <access_token>

Request:

{
    "first_name": "string",  // required, min: 2, max: 128
    "last_name": "string",   // required, min: 2, max: 128
    "email": "string",       // required, email format, max: 240
    "password": "string"     // required, strong password: 8-64 chars, must contain letter, number, and special character
}

Response 201 Created:

{
    "id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string"
}

Response 422 Unprocessable Entity:

{
    "code": 422,
    "message": "user already exists"
}

---

Health Check

GET /iam/health

Returns the health status of the IAM service. This endpoint can be used for monitoring and health checks by load balancers or monitoring systems.

Request: None

Response 200 OK:

{
    "status": "OK",
    "message": "string"
}

---

Service Information

GET /iam/v1/

Returns basic information about the IAM service including its name, description, and version number.

Request: None

Response 200 OK:

{
    "name": "iam",
    "description": "Identity and Access Management service.",
    "version": "1.0.0"
}

---

BaaS: Banking as a Service

The BaaS (Banking as a Service) Service provides comprehensive banking operations and instant payment capabilities through the /baas/v1 endpoint base path. This service enables you to perform account management operations such as retrieving account balances, transaction history, and detailed financial reports. All account-specific requests to this service require a valid access token obtained from the IAM service, and the account-specific operations must include the account ID in the request path.

The service offers complete PIX integration, Brazil's instant payment system, allowing you to generate dynamic QR codes for receiving payments, execute withdrawals (outgoing transfers to other banks via PIX or traditional bank transfers), manage PIX keys, and process refunds. PIX operations include real-time transaction tracking, the ability to cancel pending transactions, and comprehensive transaction history queries with flexible filtering options. Each account can have multiple registered PIX keys that enable simplified payment identification and collection.

The BaaS service supports PIX Automatic (Pix Automático), enabling receivers to create recurring payment consents directly or via QR codes, and payers to manage consent approvals and scheduled payments.

The BaaS service also provides webhook endpoints for receiving real-time notifications about transaction events. These webhooks notify your application immediately when PIX payments are received, withdrawals are completed, refunds are processed, PIX key status changes occur, or PIX Automatic consent and schedule events happen. This event-driven architecture ensures your application stays synchronized with all banking activities without the need for constant polling.

---

Reference Data

The Reference Data endpoints provide access to enumerated types and lookup values used throughout the BaaS API. These public endpoints do not require authentication and return standardized lists of valid values for operation types and transaction subtypes.

Get Operation Types

GET /baas/v1/operation/types

Returns a list of all valid operation types supported by the platform. Operation types categorize the nature of banking operations (e.g., PIX transfers, boleto payments, account operations). Use these values to filter transactions via the operation_type parameter in the Get Account Transactions endpoint.

Authentication Required: None (Public endpoint)

Request: None

Response 200 OK:

[
    {
        "id": 0,
        "name": "Purchase boleto"
    },
    {
        "id": 1,
        "name": "Purchase card"
    },
    {
        "id": 40,
        "name": "Pix out"
    },
    {
        "id": 41,
        "name": "Pix in"
    }
]

Common Operation Types:

• 0 - Purchase boleto
• 40 - Pix out (withdrawals)
• 41 - Pix in (incoming payments)
• 42 - Refund Pix in
• 43 - Refund Pix out
• 44 - QR Code

Note: The complete list includes 44 operation types. Use this endpoint to retrieve all current values.

---

Get Transaction Subtypes

GET /baas/v1/operation/subtypes

Returns a list of all valid transaction subtypes supported by the platform. Subtypes provide detailed categorization of transactions within each operation type (e.g., "Credit Pix in", "Pre-debit Pix out", "Manual credit"). Each transaction in your account history includes a subtype that describes the specific nature of the banking operation.

Authentication Required: None (Public endpoint)

Request: None

Response 200 OK:

[
    {
        "id": 0,
        "name": "Pre-credit payment of boleto"
    },
    {
        "id": 9,
        "name": "Manual credit"
    },
    {
        "id": 21,
        "name": "Initial balance"
    },
    {
        "id": 22,
        "name": "Final balance"
    },
    {
        "id": 222,
        "name": "Credit Pix in"
    },
    {
        "id": 242,
        "name": "Pre-debit Pix out"
    }
]

Common Subtypes:

• 9 - Manual credit
• 20 - Manual debit
• 21 - Initial balance (filtered by default in transactions)
• 22 - Final balance (filtered by default in transactions)
• 222 - Credit Pix in
• 242 - Pre-debit Pix out
• 244 - Debit Pix out

Note: The complete list includes 380+ subtypes (IDs 0-379). Use this endpoint to retrieve all current values and their descriptions.

---

Account Management

Get Account Transactions

POST /baas/v1/account/:id/transactions

Retrieves the transaction history for a specific account within a date range. This endpoint returns paginated transaction data along with current account balance and account details. By default, balance entries (Initial/Final Balance) are filtered out unless the raw parameter is set to true.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "init_date": "2024-01-01",      // required, format: YYYY-MM-DD
    "ends_date": "2024-01-31",      // required, format: YYYY-MM-DD
    "page": 1,                      // required, min: 1
    "limit": 50,                    // required, min: 1, max: 100
    "raw": false,                   // optional, default: false. If true, includes balance entries (subtypes 21, 22)
    "operation_type": 41            // optional, filter by operation type (0-109). Example: 41 = Pix in, 40 = Pix out
}

Response 200 OK:

{
    "data": [
        {
            "id": "1976159309",
            "type": "CreditPixIn",
            "subtype": "Credit Pix in",
            "operation": "Pix in",
            "details": "Crédito Recebimento via Pix John Doe - 12345678901",
            "description": "CreditPixIn",
            "document_number": 245188468,
            "date": "2024-09-18T17:12:34.287",
            "value": 5.00,
            "tags": ["245188468", "6a10967d-b764-46d7-9609-f27279619d10"]
        }
    ],
    "meta": {
        "page": 1,
        "limit": 50,
        "total": 250
    },
    "balance": {
        "total": 1500.00,
        "blocked": 0.00,
        "updated_at": "2024-01-01T12:00:00Z"
    },
    "account": {
        "bank_number": "450",
        "bank_branch": "0001",
        "bank_account": "201953902",
        "bank_account_digit": "2"
    }
}

Important Notes:

• The data array is always present, even when empty ([])
• The operation field returns a human-readable string (e.g., "Pix in") instead of an integer
• The tags array includes the document number as the first element
• Balance entries (Initial Balance, Final Balance) are excluded by default. Set raw=true to include them
• Use the /baas/v1/operation/types endpoint to get all valid operation type IDs and names
• Use the /baas/v1/operation/subtypes endpoint to get all valid subtype IDs and names

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

Get Account Balance

GET /baas/v1/account/:id/balance

Retrieves the current balance for a specific account, including total available balance, blocked amounts, and the last update timestamp.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request: None

Response 200 OK:

{
    "balance": 1500.00,
    "blocked": 0.00,
    "updated_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

Generate Account Report

POST /baas/v1/account/:id/report

Generates a detailed account balance report for a specific date range. The report is generated asynchronously and will be sent to the provided email address once processing is complete. This is useful for generating monthly statements or financial reports.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "init_date": "2024-01-01",  // required, format: YYYY-MM-DD
    "ends_date": "2024-01-31",  // required, format: YYYY-MM-DD
    "email": "string"           // required, email format
}

Response 202 Accepted:

{
    "message": "Your account report request has been received and is being processed. You will receive the report file at the provided email address shortly.",
    "status": "processing",
    "updated_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

PIX QR Code Operations

Generate PIX QR Code

POST /baas/v1/account/:id/pix/qrcode

Generates a dynamic PIX QR code for receiving payments. The QR code can be configured with a specific value, expiration date, and payer information. Once generated, the QR code can be presented to customers who can scan it with their banking app to complete the payment. The account must have at least one registered PIX key to generate QR codes.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "reference": "string",      // required, unique identifier for this QR code
    "payer": {
        "tax_number": "string", // required, CPF (11 digits) or CNPJ (14 digits) format
        "name": "string",       // required, payer name
        "message": "string"     // optional, message to payer
    },
    "value": 100.50,            // required, min: 1, max: 999999
    "expires_at": "2024-01-01 15:30", // optional, format: YYYY-MM-DD HH:MM (America/Sao_Paulo timezone), default: now + 15 minutes
    "data": {}                  // optional, additional metadata as key-value pairs
}

Response 200 OK:

{
    "reference": "string",
    "payer": {
        "tax_number": "string",
        "name": "string",
        "message": "string"
    },
    "value": 100.50,
    "expires_at": "2024-01-01 15:30",
    "qr_code": "string",
    "base64": "string",
    "document_number": 123456,
    "conciliation_id": "string"
}

Response 422 Unprocessable Entity:

{
    "code": 422,
    "message": "No PIX key registered for this account"
}

---

Get PIX QR Code

GET /baas/v1/account/:id/pix/qrcode/:reference

Retrieves detailed information about a previously generated PIX QR code using its reference identifier. This includes the QR code hash, payer and receiver information, location details, status, and expiration date.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - QR code reference identifier (required)

Request: None

Response 200 OK:

{
    "reference": "string",
    "type": "dynamic",
    "key": "string",
    "payer": {
        "name": "string",
        "tax_number": "string",
        "message": "string"
    },
    "receiver": {
        "name": "string",
        "tax_number": "string"
    },
    "location": {
        "city": "string",
        "zip_code": "string"
    },
    "qrcode": {
        "hash": "string"
    },
    "reusable": false,
    "expires_at": "2024-01-01T15:30:00Z",
    "value": 100.50,
    "status": "string",
    "created_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "The qrcode reference 'string' not found or expired."
}

---

Cancel PIX QR Code

DELETE /baas/v1/account/:id/pix/qrcode/:reference

Cancels a previously generated PIX QR code by its reference identifier. Once canceled, the QR code can no longer be used to receive payments. This is useful when you need to invalidate a QR code before its expiration date.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - QR code reference identifier (required)

Request: None

Response 200 OK:

{
    "reference": "string",
    "document_number": 123456,
    "conciliation_id": "string",
    "status": "canceled",
    "canceled_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "The qrcode reference 'string' not found or expired."
}

---

PIX Transactions

Get PIX Transactions

POST /baas/v1/account/:id/pix/transactions

Retrieves the history of incoming PIX payments (PIX In) for a specific account within a date range. This endpoint returns paginated transaction data including payer information, QR code details, end-to-end IDs, and payment status.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "init_date": "2024-01-01",  // required, format: YYYY-MM-DD, length: 10
    "ends_date": "2024-01-31",  // required, format: YYYY-MM-DD, length: 10
    "page": 0,                  // required, min: 0
    "limit": 50                 // required, min: 1, max: 100
}

Response 200 OK:

{
    "data": [
        {
            "document_number": "string",
            "e2e_id": "string",
            "origin": {
                "name": "string",
                "tax_number": "string",
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "destination": {
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "payer": {
                "name": "string",
                "tax_number": "string",
                "message": "string"
            },
            "qrcode": {
                "type": "string",
                "document_number": "string",
                "conciliation_id": "string"
            },
            "paid_at": "2024-01-01T12:00:00Z",
            "status": "string",
            "value": 100.50
        }
    ],
    "meta": {
        "page": 0,
        "limit": 50,
        "total": 100
    }
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

Important Notes:

• This endpoint returns only completed transactions (payments that have been received and processed)
• Pending QR codes are NOT included in this list - use the single transaction endpoint (GET /baas/v1/account/:id/pix/transactions/:reference) to check if a specific QR code has been paid
• Transactions are filtered by the paid_at date within the specified date range
• The payer object contains the actual payment initiator's information, which may differ from the QR code's expected payer (for anonymous QR codes)

---

Get PIX Transaction

GET /baas/v1/account/:id/pix/transactions/:reference

Retrieves detailed information about a specific PIX In transaction using its QR code reference identifier. The transaction reference must have been created within the last 24 hours (cache TTL).

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - QR code reference identifier (required)

Request: None

Response 200 OK (Settled - payment completed):

{
    "reference": "my-order-123",
    "document_number": 1004328524,
    "e2e_id": "E90400888202501011200abcdef123456",
    "origin": {
        "bank_account": "1098529",
        "bank_account_digit": "9",
        "bank_branch": "3972",
        "bank_number": "033",
        "ispb": "",
        "spb": ""
    },
    "destination": {
        "bank_account": "8666108890",
        "bank_account_digit": "5",
        "bank_branch": "0001",
        "bank_number": "450",
        "ispb": "",
        "spb": ""
    },
    "payer": {
        "name": "John Doe",
        "tax_number": "12345678901",
        "message": "Payment for order #123"
    },
    "qrcode": {
        "type": "dynamic",
        "document_number": 1183497952,
        "conciliation_id": "163421F8D573ECE6F47B65BE8A422FF86B6"
    },
    "paid_at": "2024-01-01T12:00:00Z",
    "status": "settled",
    "value": 1.00
}

Response 200 OK (Pending - payment not yet received):

{
    "reference": "my-order-123",
    "document_number": 0,
    "e2e_id": "",
    "qrcode": {
        "type": "dynamic",
        "document_number": 1183497952,
        "conciliation_id": "163421F8D573ECE6F47B65BE8A422FF86B6"
    },
    "paid_at": "",
    "status": "pending",
    "value": 1.00
}

Response 200 OK (Expired - QR code expired before payment):

{
    "reference": "my-order-123",
    "document_number": 0,
    "e2e_id": "",
    "qrcode": {
        "type": "dynamic",
        "document_number": 1183497952,
        "conciliation_id": "163421F8D573ECE6F47B65BE8A422FF86B6"
    },
    "paid_at": "",
    "status": "expired",
    "value": 1.00
}

Response 404 Not Found:

{
    "code": "ZPY.PIX.017",
    "message": "The transaction reference 'my-order-123' was not found."
}

Important Notes:

• The reference must be the same value used when generating the QR code
• Transaction references are cached for 24 hours after QR code generation
• After cache expiration, the transaction cannot be retrieved via this endpoint (use the date-range search instead)

Transaction Status Values:

Status	Description
pending	QR code exists but payment has not been received yet
expired	QR code expired before payment was received
created	Payment received and credited to account
registered	Payment registered in the banking system (intermediate state)
settled	Payment successfully settled (final state)
canceled	Transaction was canceled

Status Determination Logic:

This endpoint uses a multi-tier cache strategy to determine transaction status:

1. QR Code Lookup: First, the system checks if the QR code reference exists

   • If not found → Returns 404 error
   • If found → Proceeds to payment check

2. Payment Check: System checks if a payment webhook has been received

   • If NO payment received:
     • QR code expired → Returns expired status
     • QR code still valid → Returns pending status
   • If payment received → Queries provider for actual transaction status

3. Provider Status: For paid transactions, the status is retrieved from the banking provider and normalized to lowercase (settled, canceled, etc.)

Payer Data Availability:

The payer field behavior depends on the transaction status and QR code type:

Transaction State	payer Field
Pending	null (omitted from response)
Expired	null (omitted from response)
Paid	Contains actual payer information

Anonymous QR Codes:

When a QR code is generated without payer information (anonymous):

• The payer object is present in paid transactions
• payer.name and payer.tax_number contain the actual payment initiator's data (the person who paid)
• These values come from the payment transaction, not from the QR code generation

Response Field Availability by Status:

Field	pending	expired	settled/paid
reference	✓	✓	✓
document_number	0	0	Payment doc number
e2e_id	"" (empty)	"" (empty)	Transaction E2E ID
origin	null (omitted)	null (omitted)	Origin bank data
destination	null (omitted)	null (omitted)	Destination bank data
payer	null (omitted)	null (omitted)	Payer information
payer.message	-	-	Omitted if empty
qrcode	✓	✓	✓
paid_at	"" (empty)	"" (empty)	ISO 8601 datetime
status	"pending"	"expired"	Provider status
value	✓	✓	✓

---

Refund PIX In

POST /baas/v1/account/:id/pix/refund

Processes a refund for a previously received PIX payment. You can refund the full or partial amount of the original transaction. The refund is processed immediately and the funds are returned to the payer's account.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "reference": "string",      // required, unique refund reference
    "document_number": 123456,  // required, original transaction document number
    "value": 100.50,            // required, min: 1, refund amount
    "message": "string"         // optional, refund reason/message
}

Response 200 OK:

{
    "reference": "string",
    "document_number": 123456,
    "value": 100.50,
    "status": "approved",
    "refunded_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

Get PIX Refunds

POST /baas/v1/account/:id/pix/refunds

Retrieves the history of PIX refund transactions for a specific account within a date range. This includes both refunds you've processed (outgoing) and refunds you've received (incoming).

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "init_date": "2024-01-01",  // required, format: YYYY-MM-DD, length: 10
    "ends_date": "2024-01-31",  // required, format: YYYY-MM-DD, length: 10
    "page": 1,                  // required, min: 1
    "limit": 50                 // required, min: 1, max: 100
}

Response 200 OK:

{
    "data": [
        {
            "reference": "string",
            "document_number": "string",
            "e2e_id": "string",
            "origin": {
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "destination": {
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "reason": "string",
            "refund_date": "2024-01-01T12:00:00Z",
            "message": "string",
            "status": "string",
            "value": 100.50
        }
    ],
    "meta": {
        "page": 1,
        "limit": 50,
        "total": 10
    }
}

Response 400 Bad Request:

{
    "code": 400,
    "message": "The ends_date must be greater than or equal to init_date"
}

---

Get PIX Refund

GET /baas/v1/account/:id/pix/refund/:reference

Retrieves detailed information about a specific PIX refund transaction using its reference identifier.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - Refund reference identifier (required)

Request: None

Response 200 OK:

{
    "reference": "string",
    "document_number": "string",
    "e2e_id": "string",
    "origin": {
        "bank_account": "string",
        "bank_account_digit": "string",
        "bank_branch": "string",
        "bank_number": "string",
        "ispb": "string",
        "spb": "string"
    },
    "destination": {
        "bank_account": "string",
        "bank_account_digit": "string",
        "bank_branch": "string",
        "bank_number": "string",
        "ispb": "string",
        "spb": "string"
    },
    "reason": "string",
    "refund_date": "2024-01-01T12:00:00Z",
    "message": "string",
    "status": "string",
    "value": 100.50
}

Response 404 Not Found:

{
    "code": 404,
    "message": "The refund reference 'string' not found."
}

---

Webhook Configuration for PIX In Transactions:

To receive real-time notifications for PIX In payments and refunds, configure your account to listen to these webhook event types:

• pix.in.paid - Incoming PIX payment settled
• pix.refund.in.paid - Incoming refund completed
• pix.refund.in.canceled - Incoming refund canceled

See the Webhooks section for complete documentation on webhook configuration, authentication, and payload examples.

---

PIX Key Management

Supported PIX Key Types

The ZAPPY platform supports the following PIX key types as defined by the Brazilian Central Bank. Each account can register multiple PIX keys to facilitate payment reception.

Accepted Key Types:

Type	Description	Format Example
SocialSecurity	Brazilian CPF (Individual Taxpayer ID)	12345678901 (11 digits)
TaxNumber	Brazilian CNPJ (Corporate Taxpayer ID)	12345678000199 (14 digits)
Email	Email address	user@example.com
PhoneNumber	Phone number with country code	+5511999999999
RandomKeyCode	Random UUID key generated by the system	123e4567-e89b-12d3-a456-426614174000

Important Notes:

• These key type values are case-sensitive and must be used exactly as shown above
• SocialSecurity corresponds to CPF (Cadastro de Pessoas Físicas)
• TaxNumber corresponds to CNPJ (Cadastro Nacional da Pessoa Jurídica)
• Each PIX key must be unique across the entire PIX ecosystem
• Keys must be validated and registered with the Brazilian Central Bank before they can be used

---

Get PIX Keys

GET /baas/v1/account/:id/pix/keys

Retrieves all PIX keys registered for a specific account. PIX keys are identifiers that can be used to receive payments without sharing bank account details. Supported key types include CPF/CNPJ (SocialSecurity/TaxNumber), email, phone number, and random keys.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request: None

Response 200 OK:

{
    "data": [
        {
            "id": "019a3252-3bd5-73c0-b1d9-c490939e0709",
            "type": "string",
            "key": "string",
            "status": "string",
            "updated_at": "2024-01-01T12:00:00Z"
        }
    ],
    "meta": {
        "total": 2
    }
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

Get PIX Key Status

GET /baas/v1/account/:id/pix/key/:keyId

Retrieves the current status of a specific PIX key. PIX keys can have various statuses during their lifecycle including "registering", "registered", "canceling", and "canceled".

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• keyId - PIX key identifier (required)

Request: None

Response 200 OK:

{
    "id": "019a3252-3bd5-73c0-b1d9-c490939e0709",
    "type": "string",
    "key": "string",
    "status": "string",
    "updated_at": "2024-01-01T12:00:00Z"
}

Response 400 Bad Request:

{
    "code": 400,
    "message": "Missing PIX key ID"
}

---

Get PIX Key Info

GET /baas/v1/account/:id/pix/key/:keyId/info

Retrieves detailed information about a PIX key including the receiver's bank details, name, and tax identification number. This information is retrieved from the Brazilian Central Bank's PIX key directory.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• keyId - PIX key identifier (required)

Request: None

Response 200 OK:

{
    "search_protocol": 123456,
    "type": "string",
    "key": "string",
    "receiver": {
        "bank_name": "string",
        "name": "string",
        "ispb": "string",
        "bank": "string",
        "bank_branch": "string",
        "bank_account": "string",
        "bank_account_digit": "string",
        "tax_number": "string"
    },
    "updated_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "PIX key not found"
}

---

Cancel PIX Key

DELETE /baas/v1/account/:id/pix/key/:keyId

Cancels a PIX key registration. Once canceled, the key can no longer be used to receive payments. The cancellation process may take some time to be confirmed by the Brazilian Central Bank's PIX infrastructure.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• keyId - PIX key identifier (required)

Request: None

Response 200 OK:

{
    "type": "string",
    "key": "string",
    "status": "canceled",
    "canceled_at": "2024-01-01T12:00:00Z"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "PIX key not found"
}

---

Withdrawals (PIX Out & Bank Transfers)

Status Information

Withdrawal transactions progress through different statuses during their lifecycle. Understanding these statuses is essential for tracking transaction processing and handling webhook notifications.

Possible Statuses:

• Created: Transaction has been initiated and will be processed
• Registered: Intermediate state - Transaction was registered in the SPI (Brazilian Instant Payment System) but not yet settled. This is not a final state.
• Paid / Settled: Final state - Transaction settled successfully
• Canceled: Final state - Transaction canceled

Important Notes:

• Intermediate vs Final States: Registered is an intermediate processing state, not a completion status. Transactions in Registered state are still being processed. Only Paid/Settled and Canceled are final states indicating transaction completion.

• Webhook Behavior: Only final states (Paid and Canceled) are sent via webhooks. You will not receive webhook notifications for intermediate states like Registered or Created.

• Status Normalization: All status values in webhooks are normalized to lowercase (e.g., paid, canceled). The system automatically handles variations in status naming from the payment processor.

Webhook vs API Naming Differences:

While both webhooks and APIs report transaction statuses, there are key naming differences to be aware of:

• Paid status in webhooks corresponds to Settled status in API responses (both indicate successful PIX payment settlement)
• Canceled status in webhooks may appear as Cancel in some raw responses but is always normalized to canceled

Scheduled PixOut Behavior:

When a PixOut operation is scheduled for a future date, the transaction follows a specific workflow:

1. Transaction is stored with Created status immediately upon creation
2. No webhook notification is received at creation time
3. You must use the Get Withdrawal endpoint to query the transaction status during the waiting period
4. When the scheduled payment date arrives, the transaction is processed and a webhook with Paid status is sent

Note: To monitor scheduled withdrawals, implement regular polling using the Get Withdrawal endpoint or wait for the webhook notification when the scheduled date is reached.

---

Withdraw

POST /baas/v1/account/:id/withdraw

Initiates a withdrawal from the account to an external destination. Withdrawals can be made via PIX (instant transfer) or traditional bank transfer. For PIX withdrawals, you can specify a PIX key as the destination. For bank transfers, you must provide complete bank account details. The withdrawal will be processed according to the specified date.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request (Bank Account Method):

{
    "method": "bank_account",           // required, values: "bank_account" or "pix"
    "reference": "string",              // required, unique reference identifier
    "destination": {
        "name": "string",               // required, receiver name
        "tax_number": "string"          // required, CPF (11 digits) or CNPJ (14 digits)
    },
    "bank_account": {
        "type": "Current",              // required, values: Current, Salary, Saving, or Payment
        "bank_number": "string",        // required, 3-digit bank code
        "bank_branch": "string",        // required, branch number
        "bank_account": "string",       // required, account number
        "bank_account_digit": "string"  // required, account check digit
    },
    "description": "string",            // optional, max: 1024 characters
    "message": "string",                // optional, max: 1024 characters
    "date": "2024-01-01",              // required, format: YYYY-MM-DD, length: 10
    "value": 100.50                     // required, must be greater than 0
}

Request (PIX Method):

{
    "method": "pix",
    "reference": "string",
    "destination": {
        "name": "string",
        "tax_number": "string"
    },
    "pix": {
        "type": "Email",                // required, values: SocialSecurity, TaxNumber, Email, PhoneNumber, RandomKeyCode
        "key": "string",                // required, PIX key value
        "account_type": "current"       // optional, values: current, salary, saving, payment
    },
    "description": "string",
    "message": "string",
    "date": "2024-01-01",
    "value": 100.50
}

PIX Account Type Values

The account_type field specifies the destination bank account type. If not provided, the system will attempt to use the account type from the PIX key lookup, or default to current.

Value	Description
current	Current account (Conta Corrente)
salary	Salary account (Conta Salário)
saving	Savings account (Conta Poupança)
payment	Payment account (Conta de Pagamento)

Important: Destination Tax Number for PIX Transfers

The destination.tax_number field is critical for PIX withdrawals using Email, PhoneNumber, or RandomKeyCode key types. Since these PIX key types don't directly contain the receiver's CPF/CNPJ, the system uses the destination.tax_number you provide as the receiver's tax identification.

• For SocialSecurity or TaxNumber PIX keys: The PIX key itself is the tax number
• For Email, PhoneNumber, or RandomKeyCode PIX keys: The destination.tax_number is used

Always ensure destination.tax_number contains the unmasked, valid CPF or CNPJ of the payment receiver.

Response 200 OK:

{
    "reference": "string",
    "method": "string",
    "value": 100.50,
    "document_number": 123456,
    "status": "string",
    "updated_at": "2024-01-01T12:00:00Z"
}

Response 400 Bad Request:

{
    "code": 400,
    "message": "Validation failed",
    "details": {
        "errors": "Bank account details are required when method is 'bank_account'; Bank number is required for bank account transfers"
    }
}

---

Get Withdrawal

GET /baas/v1/account/:id/withdraw/:reference

Retrieves detailed information about a specific withdrawal transaction using its reference identifier. This includes the origin and destination bank details, end-to-end ID (for PIX), payment date, and current status.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - Withdrawal reference identifier (required)

Request: None

Response 200 OK:

{
    "reference": "string",
    "document_number": 123456,
    "e2e_id": "string",
    "origin": {
        "bank_account": "string",
        "bank_account_digit": "string",
        "bank_branch": "string",
        "bank_number": "string",
        "ispb": "string",
        "spb": "string"
    },
    "destination": {
        "bank_account": "string",
        "bank_account_digit": "string",
        "bank_branch": "string",
        "bank_number": "string",
        "ispb": "string",
        "spb": "string"
    },
    "payment_date": "2024-01-01T12:00:00Z",
    "status": "string"
}

Response 404 Not Found:

{
    "code": 404,
    "message": "The withdrawal reference 'string' not found."
}

---

Get Withdrawals

POST /baas/v1/account/:id/withdraws

Retrieves a paginated list of withdrawal transactions for a specific account within a date range. This includes both PIX transfers and traditional bank transfers.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "init_date": "2024-01-01",  // required, format: YYYY-MM-DD, length: 10
    "ends_date": "2024-01-31",  // required, format: YYYY-MM-DD, length: 10
    "page": 1,                  // required, min: 1
    "limit": 50                 // required, min: 1, max: 100
}

Response 200 OK:

{
    "data": [
        {
            "reference": "string",
            "document_number": 123456,
            "e2e_id": "string",
            "origin": {
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "destination": {
                "bank_account": "string",
                "bank_account_digit": "string",
                "bank_branch": "string",
                "bank_number": "string",
                "ispb": "string",
                "spb": "string"
            },
            "payment_date": "2024-01-01T12:00:00Z",
            "status": "string",
            "value": 100.50
        }
    ],
    "meta": {
        "page": 1,
        "limit": 50,
        "total": 5
    }
}

Response 404 Not Found:

{
    "code": 404,
    "message": "Account not found"
}

---

Cancel Withdrawal

DELETE /baas/v1/account/:id/withdraw/:reference

Cancels a pending withdrawal transaction by its reference identifier. Only withdrawals that have not yet been processed can be canceled. Once a withdrawal is confirmed or completed, it cannot be canceled.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - Withdrawal reference identifier (required)

Request: None

Response 200 OK:

{
    "reference": "string",
    "document_number": 123456,
    "status": "canceled",
    "canceled_at": "2024-01-01T12:00:00Z"
}

Response 422 Unprocessable Entity:

{
    "code": 422,
    "message": "Failed to cancel withdrawal"
}

---

Webhook Configuration for Withdrawals

To receive real-time notifications about withdrawal transaction events, your account must be configured to listen to the following webhook event types:

PIX Out Withdrawal Events:

• pix.out.paid - Sent when withdrawal is paid/settled
• pix.out.canceled - Sent when withdrawal is canceled

Configuration:

Use your BFF (Backend For Frontend) webhook settings to subscribe to these event types. You can subscribe to individual events or use wildcard patterns for broader coverage:

• pix.out.* - Receive all PIX Out events
• pix.out.paid - Receive only paid/settled notifications
• pix.out.canceled - Receive only cancellation notifications

Important: Webhook notifications only include Paid and Canceled statuses. Other statuses (Created, Registered) are only available through API queries. Remember that Paid in webhooks corresponds to Settled in API responses.

Related Documentation:

• See the Webhooks section for complete webhook documentation, payload examples, authentication methods, and retry policies
• See the PIX Out Webhook Events section for detailed payload structure

---

PIX Automatic (Recurring Payments)

PIX Automatic (Pix Automático) is a Central Bank of Brazil innovation that enables automated recurring payments through the PIX instant payment system. This feature allows payers to pre-authorize recurring debits from their accounts, enabling businesses to automate collection of subscriptions, memberships, utility bills, and other recurring fees.

Primary Use Cases:

• Subscription services (streaming, software, memberships)
• Gym and fitness club memberships
• Recurring utility bill payments
• Insurance premium payments
• Loan installment collections

Core Concepts:

Concept	Description
Consent (Recurrence)	A payer's authorization for recurring debits. Contains frequency, value constraints, and validity period.
Schedule	An individual scheduled payment created from an approved consent. Represents a single payment execution.
Payer (Debtor)	The account holder who authorizes and pays the recurring charges.
Receiver (Creditor)	The business or individual who receives the recurring payments.

Key Features:

• Payer Control: Payers can approve, modify, or cancel consents at any time
• Flexible Value Types: Support for both fixed and variable payment amounts
• Central Bank Compliance: Full compliance with Brazilian Central Bank regulations
• Real-time Notifications: Webhook events for all consent and payment status changes

---

User Journeys

PIX Automatic supports two payer authorization journeys for consent confirmation:

Journey 1: Webhook-Based Consent Confirmation

This flow is triggered when a receiver initiates a consent request through their banking system.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    JOURNEY 1: WEBHOOK CONSENT CONFIRMATION                  │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver initiates consent request (external system)
        ↓
Step 2: Banking provider sends consent request to ZAPPY BaaS
        ↓
Step 3: ZAPPY BaaS sends webhook notification to your application
        Event: pix.auto.consent.pending
        ↓
Step 4: Your app displays consent details to payer for review
        - Receiver information
        - Payment frequency and value
        - Validity period
        ↓
Step 5: Payer approves or rejects in your app
        ↓
Step 6: Your app calls POST /auto-pix/consents/{cid}/confirm
        {
            "status": "approved",
            "search_protocol": "...",
            "notification": true
        }
        ↓
Step 7: ZAPPY BaaS processes confirmation with banking provider
        ↓
Step 8: Result webhook sent to your application
        Event: pix.auto.consent.approved OR pix.auto.consent.rejected

Important Notes:

• The payer must review consent details before confirmation
• The search_protocol from the webhook must be included in the confirmation request
• Payers can set notification: true to receive alerts before each payment

---

Journey 2: QR Code Scanning

This flow is initiated when a payer scans a PIX Automatic QR code.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    JOURNEY 2: QR CODE CONSENT CONFIRMATION                  │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver generates PIX Automatic QR code (external system)
        ↓
Step 2: Payer scans QR code using your app
        ↓
Step 3: Your app calls GET /auto-pix/qrcode/{hash}
        ↓
Step 4: ZAPPY BaaS returns consent information:
        {
            "recurrence_id": "REC123",
            "search_protocol": "PROTO456",
            "receiver": { "name": "...", "tax_number": "..." },
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 9990
        }
        ↓
Step 5: Your app displays consent details to payer for review
        ↓
Step 6: Payer approves or rejects in your app
        ↓
Step 7: Your app calls POST /auto-pix/consents/{cid}/confirm
        (Same as Journey 1, Steps 6-8)

Important Notes:

• QR codes contain encoded consent parameters
• The search_protocol from QR code info must be used in confirmation
• For variable value consents, payer can set maximum_value during confirmation

---

Receiver Journey 1: Create Recurrence (Direct)

This flow is initiated by the receiver (creditor) who wants to set up a recurring payment from a known debtor.

┌─────────────────────────────────────────────────────────────────────────────┐
│              RECEIVER JOURNEY 1: CREATE RECURRENCE (DIRECT)                 │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver calls POST /auto-pix/consents
        {
            "tax_number": "98765432100",
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 29.90,
            "initial_date": "2025-02-15"
        }
        ↓
Step 2: ZAPPY BaaS creates recurrence with the banking provider
        ↓
Step 3: Response: { "recurrence_id": "REC123", "status": "pending" }
        ↓
Step 4: Banking provider sends consent request to debtor's bank
        ↓
Step 5: ZAPPY BaaS receives confirmation webhook
        Event: pix.auto.consent.confirm
        → Relayed to receiver's webhook endpoint
        ↓
Step 6: Debtor approves consent via their own banking app
        ↓
Step 7: ZAPPY BaaS receives notification webhook
        Event: pix.auto.consent.approved
        → Relayed to receiver's webhook endpoint
        ↓
Step 8: Payments are automatically scheduled per frequency
        Event: pix.auto.schedule.settled (for each payment)
        → Relayed to receiver's webhook endpoint

Important Notes:

• The tax_number is required to identify the payer
• The receiver must have a registered PIX key (or provide one in pix_key)
• Once created, the consent awaits debtor approval via their own banking institution
• Webhook events track the full lifecycle from confirmation to payment

---

Receiver Journey 2: Generate QR Code with Recurrence

This flow is initiated by the receiver who generates a QR code that encodes recurrence parameters. Any payer can scan this QR code to initiate the consent.

┌─────────────────────────────────────────────────────────────────────────────┐
│            RECEIVER JOURNEY 2: GENERATE QR CODE WITH RECURRENCE             │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver calls POST /auto-pix/qrcode
        {
            "pix_key": "receiver@email.com",
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 29.90,
            "initial_date": "2025-02-15"
        }
        ↓
Step 2: ZAPPY BaaS generates QR code with the banking provider
        ↓
Step 3: Response:
        {
            "hash_code": "HASH123...",
            "qrcode_base64": "iVBORw0KGgo...",
            "document_number": 12345,
            "reference": "unique-reference-uuid"
        }
        ↓
Step 4: Receiver displays QR code to potential payer
        ↓
Step 5: Payer scans QR code with their banking app
        ↓
Step 6: Payer's banking app creates recurrence from QR code data
        ↓
Step 7: Same lifecycle as Receiver Journey 1 (Steps 5-8):
        - pix.auto.consent.confirm → pix.auto.consent.approved
        - pix.auto.schedule.settled (for each payment)

Important Notes:

• A registered PIX key (pix_key) is required for QR code generation
• The QR code can be scanned by any payer; tax_number is optional
• The reference in the response can be used to look up QR code info later via GET /auto-pix/qrcode/:reference
• The qrcode_base64 contains a Base64-encoded PNG image ready for display

---

Business Rules (Central Bank Compliance)

PIX Automatic operates under strict Central Bank of Brazil regulations. These rules are enforced by the platform and cannot be bypassed.

Scheduling Window

All scheduled payments must fall within the allowed scheduling window:

Constraint	Value	Description
Minimum	D+2	Payment must be scheduled at least 2 business days in advance
Maximum	D+10	Payment must be scheduled no more than 10 business days in advance

Example: If today is January 15th, valid payment dates are January 17th through January 25th.

Requests with payment dates outside this window will be rejected with error code ZPY.PXA.007.

---

Cancellation Cutoff Times

Different actors have different deadlines for canceling scheduled payments. All times are in America/Sao_Paulo timezone.

Actor	Cutoff Time	Description
Payer	11:59 PM on D-1	Payer can cancel until 1 minute before midnight on the day before payment
Receiver	9:59 PM on D-1	Receiver can cancel until 2 hours before payer cutoff

Example: For a payment scheduled on January 20th:

• Payer can cancel until January 19th at 11:59 PM
• Receiver can cancel until January 19th at 9:59 PM

Consent Cancellation Impact on Schedules

When a consent is canceled, the impact on existing schedules depends on timing:

Actor	Cancellation Time	D+1 Schedules	D+2+ Schedules
Payer	Any time	Canceled	Canceled
Receiver	Before 10:00 PM	Canceled	Canceled
Receiver	After 10:00 PM	Preserved	Canceled

Important: When a receiver cancels a consent after 10 PM, the next-day (D+1) payment will still be executed. This protects payers from unexpected last-minute cancellations.

---

Value Type Rules

PIX Automatic supports two value types with different modification rules:

Fixed Value Consent:

• Payment amount is set at consent creation and cannot be modified
• The value field contains the immutable payment amount
• To change the amount, the consent must be canceled and a new one created

Variable Value Consent:

• Receiver sets minimum_value at creation (immutable)
• Payer sets maximum_value during confirmation (can be modified later)
• Actual payment amounts can vary between minimum and maximum
• Important: Receiver cannot see the payer's maximum_value

Field	Set By	Modifiable	Visible To
minimum_value	Receiver	No	Both
maximum_value	Payer	Yes (by payer only)	Payer only

---

Retry Logic

Failed payments are automatically retried according to Central Bank rules:

Parameter	Value
Maximum retry attempts	3
Retry period	Up to 7 days
Retry windows per day	Up to 2
Payer notification	Required 24+ hours before retry

Note: Retry logic is handled automatically by the banking provider. Your application will receive webhook notifications for each attempt result.

---

Consent Management Endpoints

All PIX Automatic endpoints are account-scoped and require JWT authentication.

Base Path: /baas/v1/account/:id/auto-pix

---

List Consents

GET /baas/v1/account/:id/auto-pix/consents

Retrieves all PIX Automatic consents associated with the account. Returns both consents where the account is the payer and where it is the receiver.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request: None

Response 200 OK:

{
    "consents": [
        {
            "recurrence_id": "REC123456",
            "receiver_name": "Streaming Service Inc",
            "receiver_tax_number": "12345678000199",
            "status": "approved"
        },
        {
            "recurrence_id": "REC789012",
            "receiver_name": "Gym Fitness Club",
            "receiver_tax_number": "98765432000188",
            "status": "pending"
        }
    ],
    "meta": {
        "page": 1,
        "page_size": 20,
        "total_items": 2,
        "total_pages": 1
    }
}

Response 404 Not Found:

{
    "code": "ZPY.ACC.001",
    "message": "Account not found"
}

---

Get Consent Details

GET /baas/v1/account/:id/auto-pix/consents/:cid

Retrieves detailed information about a specific consent including all parties, value constraints, and schedule configuration.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• cid - Consent/Recurrence ID (required)

Request: None

Response 200 OK:

{
    "recurrence_id": "REC123456",
    "authorization_id": "AUTH789",
    "status": "approved",
    "contract_id": "CONTRACT001",
    "description": "Monthly subscription - Premium Plan",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "debtor": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "initial_date": "2025-01-15",
    "final_date": "2026-01-15",
    "frequency": "monthly",
    "value_type": "fixed",
    "value": 2990,
    "notification": true,
    "credit_line": false
}

Response for Variable Value Consent (Payer View):

{
    "recurrence_id": "REC789012",
    "status": "approved",
    "value_type": "variable",
    "minimum_value": 1000,
    "maximum_value": 50000,
    "original_value": 2500
}

Response for Variable Value Consent (Receiver View):

{
    "recurrence_id": "REC789012",
    "status": "approved",
    "value_type": "variable",
    "minimum_value": 1000,
    "original_value": 2500
}

Note: The maximum_value field is only visible to the payer (debtor). Receivers will not see this field.

Response 404 Not Found:

{
    "code": "ZPY.PXA.001",
    "message": "Automatic Pix consent not found"
}

---

Confirm Consent

POST /baas/v1/account/:id/auto-pix/consents/:cid/confirm

Confirms or rejects a pending consent. This endpoint is only available to the payer (debtor) and can only be called when the consent is in pending status.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• cid - Consent/Recurrence ID (required)

Request (Approval):

{
    "search_protocol": "PROTO123456",
    "status": "approved",
    "description": "Monthly gym membership",
    "notification": true,
    "credit_line": false,
    "maximum_value": 15000
}

Request (Rejection):

{
    "search_protocol": "PROTO123456",
    "status": "rejected",
    "reason_code": "CUSTOMER_REQUEST"
}

Request Fields:

Field	Type	Required	Description
search_protocol	string	Yes	Protocol from webhook or QR code info
status	string	Yes	approved or rejected
description	string	No	Custom description for the consent
notification	boolean	No	Receive alerts before payments (default: true)
credit_line	boolean	No	Allow credit line usage (default: false)
maximum_value	integer	No	Maximum value in cents (variable value only)
reason_code	string	Conditional	Required when status is rejected

Response 200 OK (Approved):

{
    "recurrence_id": "REC123456",
    "status": "approved",
    "message": "Consent confirmed successfully"
}

Response 200 OK (Rejected):

{
    "recurrence_id": "REC123456",
    "status": "rejected",
    "message": "Consent rejected successfully"
}

Response 400 Bad Request:

{
    "code": "ZPY.VAL.001",
    "message": "Invalid request payload",
    "details": {
        "search_protocol": "search_protocol is required"
    }
}

Response 403 Forbidden:

{
    "code": "ZPY.PXA.008",
    "message": "Only the payer can confirm or reject a consent"
}

Response 502 Bad Gateway:

{
    "code": "ZPY.PXA.003",
    "message": "Failed to confirm Automatic Pix consent"
}

---

Modify Consent

PATCH /baas/v1/account/:id/auto-pix/consents/:cid

Modifies an existing consent. The fields that can be modified depend on whether the caller is the payer or receiver.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• cid - Consent/Recurrence ID (required)

Request (Payer - can modify):

{
    "notification": false,
    "credit_line": true,
    "maximum_value": 20000
}

Request (Receiver - can modify):

{
    "payer_name": "John Smith Doe",
    "first_payment": "2025-02-20"
}

Modification Permissions:

Field	Payer	Receiver	Notes
notification	Yes	No	Toggle payment notifications
credit_line	Yes	No	Allow/disallow credit line
maximum_value	Yes	No	Variable value consents only
payer_name	No	Yes	Update payer display name
first_payment	No	Yes	Only when consent is pending

Response 200 OK:

{
    "recurrence_id": "REC123456",
    "status": "approved",
    "message": "Consent modified successfully"
}

Response 400 Bad Request (Fixed Value):

{
    "code": "ZPY.PXA.009",
    "message": "Cannot modify maximum_value for fixed value consent"
}

Response 502 Bad Gateway:

{
    "code": "ZPY.PXA.004",
    "message": "Failed to modify Automatic Pix consent"
}

---

Cancel Consent

DELETE /baas/v1/account/:id/auto-pix/consents/:cid

Cancels an active consent. Both payers and receivers can cancel consents, but the impact on scheduled payments differs based on timing (see Business Rules).

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• cid - Consent/Recurrence ID (required)

Request: None

Response 200 OK:

{
    "recurrence_id": "REC123456",
    "status": "canceled",
    "message": "Consent canceled successfully"
}

Response 502 Bad Gateway:

{
    "code": "ZPY.PXA.005",
    "message": "Failed to cancel Automatic Pix consent"
}

---

Receiver Endpoints

These endpoints are used by the receiver (creditor) to initiate recurring payment consents.

---

Create Consent (Receiver Journey 1)

POST /baas/v1/account/:id/auto-pix/consents

Creates a new PIX Automatic recurrence directly by specifying the debtor (payer) information. The banking provider will send a consent request to the debtor's bank for approval.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "tax_number": "98765432100",
    "name": "John Doe",
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15",
    "value_type": "fixed",
    "value": 29.90,
    "description": "Monthly subscription - Premium Plan",
    "contract_id": "CONTRACT001",
    "pix_key": "receiver@email.com"
}

Request Fields:

Field	Type	Required	Description
tax_number	string	Yes	CPF (11 digits) or CNPJ (14 digits) of the payer
name	string	No	Display name of the payer
frequency	string	Yes	Payment frequency: weekly, monthly, quarterly, annual
initial_date	string	Yes	Start date (YYYY-MM-DD)
final_date	string	No	End date (YYYY-MM-DD). If omitted, consent has no end date
value_type	string	Yes	fixed or variable
value	number	Conditional	Payment amount. Required for fixed value type
minimum_value	number	Conditional	Minimum payment amount. Used for variable value type
maximum_value	number	No	Maximum payment amount. Used for variable value type
description	string	No	Description of the recurrence purpose
contract_id	string	No	External contract identifier for reconciliation
pix_key	string	No	Receiver's PIX key. If omitted, account's default PIX key is used

Response 201 Created:

{
    "recurrence_id": "REC123456",
    "status": "pending",
    "message": "Recurrence created successfully"
}

Response 400 Bad Request:

{
    "code": "ZPY.VAL.001",
    "message": "Invalid request payload",
    "details": {
        "tax_number": "tax_number is required"
    }
}

Response 404 Not Found:

{
    "code": "ZPY.ACC.001",
    "message": "Account not found"
}

Response 502 Bad Gateway:

{
    "code": "ZPY.PXA.008",
    "message": "Failed to create Automatic Pix consent"
}

---

Generate PIX Auto QR Code (Receiver Journey 2)

POST /baas/v1/account/:id/auto-pix/qrcode

Generates a PIX Automatic QR code that encodes recurrence parameters. When a payer scans this QR code with their banking app, the recurrence is created automatically. The receiver's PIX key is required for QR code generation.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Request:

{
    "pix_key": "receiver@email.com",
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15",
    "value_type": "fixed",
    "value": 29.90,
    "description": "Monthly subscription - Premium Plan",
    "contract_id": "CONTRACT001",
    "tax_number": "98765432100",
    "name": "John Doe"
}

Request Fields:

Field	Type	Required	Description
pix_key	string	Yes	Receiver's PIX key (must be registered)
frequency	string	Yes	Payment frequency: weekly, monthly, quarterly, annual
initial_date	string	Yes	Start date (YYYY-MM-DD)
final_date	string	No	End date (YYYY-MM-DD). If omitted, consent has no end date
value_type	string	Yes	fixed or variable
value	number	Conditional	Payment amount. Required for fixed value type
minimum_value	number	Conditional	Minimum payment amount. Used for variable value type
maximum_value	number	No	Maximum payment amount. Used for variable value type
description	string	No	Description of the recurrence purpose
contract_id	string	No	External contract identifier for reconciliation
tax_number	string	No	Pre-fill payer's CPF/CNPJ in QR code
name	string	No	Pre-fill payer's name in QR code

Response 201 Created:

{
    "hash_code": "bx7k9m2p4q8r1t5w3y6z0abc",
    "qrcode_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "document_number": 245188468,
    "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields:

Field	Type	Description
hash_code	string	Unique hash from the banking provider
qrcode_base64	string	Base64-encoded PNG image of the QR code
document_number	integer	Banking provider document number for reconciliation
reference	string	Unique reference UUID for looking up QR code info

Response 400 Bad Request:

{
    "code": "ZPY.VAL.001",
    "message": "Invalid request payload",
    "details": {
        "pix_key": "pix_key is required"
    }
}

Response 404 Not Found:

{
    "code": "ZPY.ACC.001",
    "message": "Account not found"
}

Response 502 Bad Gateway:

{
    "code": "ZPY.PXA.009",
    "message": "Failed to generate Automatic Pix QR code"
}

---

Schedule Management Endpoints

List Schedules

GET /baas/v1/account/:id/auto-pix/schedules

Retrieves scheduled payments for the account. Supports filtering by consent, status, and date range.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)

Query Parameters:

Parameter	Type	Required	Description
recurrence_id	string	No	Filter by consent ID
status	string	No	Filter by status: pending, settled, failed, canceled
from_date	string	No	Start date (YYYY-MM-DD)
to_date	string	No	End date (YYYY-MM-DD)
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request Example:

GET /baas/v1/account/123/auto-pix/schedules?status=pending&from_date=2025-01-01&to_date=2025-01-31

Response 200 OK:

{
    "schedules": [
        {
            "schedule_id": "SCH001",
            "recurrence_id": "REC123456",
            "receiver_name": "Streaming Service Inc",
            "receiver_tax_number": "12345678000199",
            "payment_date": "2025-01-15",
            "value": 2990,
            "status": "pending",
            "end_to_end_id": ""
        },
        {
            "schedule_id": "SCH002",
            "recurrence_id": "REC123456",
            "receiver_name": "Streaming Service Inc",
            "receiver_tax_number": "12345678000199",
            "payment_date": "2025-02-15",
            "value": 2990,
            "status": "pending",
            "end_to_end_id": ""
        }
    ],
    "meta": {
        "page": 1,
        "page_size": 20,
        "total_items": 2,
        "total_pages": 1
    }
}

---

Get Schedule Details

GET /baas/v1/account/:id/auto-pix/schedules/:sid

Retrieves detailed information about a specific scheduled payment.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• sid - Schedule ID (required)

Request: None

Response 200 OK (Pending):

{
    "schedule_id": "SCH001",
    "recurrence_id": "REC123456",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "debtor": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "payment_date": "2025-01-15",
    "value": 2990,
    "status": "pending",
    "end_to_end_id": ""
}

Response 200 OK (Settled):

{
    "schedule_id": "SCH001",
    "recurrence_id": "REC123456",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payment_date": "2025-01-15",
    "value": 2990,
    "status": "settled",
    "end_to_end_id": "E12345678202501151200abcdef123456"
}

Response 404 Not Found:

{
    "code": "ZPY.PXA.002",
    "message": "Automatic Pix schedule not found"
}

---

Cancel Schedule

DELETE /baas/v1/account/:id/auto-pix/schedules/:sid

Cancels a pending scheduled payment. Subject to cutoff time restrictions based on the caller's role.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• sid - Schedule ID (required)

Query Parameters:

Parameter	Type	Required	Description
recurrence_id	string	Yes	The consent ID associated with this schedule

Request Example:

DELETE /baas/v1/account/123/auto-pix/schedules/SCH001?recurrence_id=REC123456

Response 200 OK:

{
    "schedule_id": "SCH001",
    "recurrence_id": "REC123456",
    "status": "canceled",
    "message": "Schedule canceled successfully"
}

Response 400 Bad Request (Cutoff Exceeded):

{
    "code": "ZPY.PXA.007",
    "message": "Cancellation cutoff time has passed"
}

---

QR Code Endpoint

Get QR Code Info

GET /baas/v1/account/:id/auto-pix/qrcode/:reference

Extracts PIX Automatic consent information from a scanned QR code hash. Used in Journey 2 to retrieve consent details before confirmation.

Authentication Required: Authorization: Bearer <access_token>

Path Parameters:

• id - Account UUID (required)
• reference - QR code hash/reference (required)

Request: None

Response 200 OK (Fixed Value):

{
    "recurrence_id": "REC123456",
    "search_protocol": "PROTO789",
    "description": "Monthly subscription",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "value_type": "fixed",
    "value": 2990,
    "frequency": "monthly",
    "initial_date": "2025-01-15",
    "final_date": "2026-01-15"
}

Response 200 OK (Variable Value):

{
    "recurrence_id": "REC789012",
    "search_protocol": "PROTO456",
    "description": "Variable utility payment",
    "receiver": {
        "tax_number": "98765432000188",
        "name": "Utility Company"
    },
    "value_type": "variable",
    "minimum_value": 5000,
    "frequency": "monthly",
    "initial_date": "2025-02-01"
}

Response 404 Not Found:

{
    "code": "ZPY.PXA.006",
    "message": "Automatic Pix QR code not found"
}

---

Status Definitions

Consent Status

Status	Description
pending	Consent request received, awaiting payer confirmation
approved	Payer has approved, consent is active for scheduling
rejected	Payer has rejected the consent request
canceled	Consent was canceled by payer or receiver

Status Transitions:

pending ──► approved ──► canceled
   │
   └──────► rejected

Schedule Status

Status	Description
pending	Payment is scheduled, awaiting execution date
settled	Payment was executed successfully
failed	Payment execution failed (may be retried)
canceled	Payment was canceled before execution

Status Transitions:

pending ──► settled
   │
   ├──────► failed (may retry → pending)
   │
   └──────► canceled

---

Permission Matrix

Access to operations depends on the caller's role (determined by tax number matching):

Operation	Payer	Receiver	Notes
Create Consent	✗	✓	Receiver initiates recurrence (Journey 1)
Generate QR Code	✗	✓	Receiver generates QR code (Journey 2)
Confirm/Reject Consent	✓	✗	Payer exclusive
List Consents	✓	✓	See own consents
View Consent Details	✓	✓	MaximumValue hidden from receiver
Modify Notification	✓	✗	Payer preference
Modify Credit Line	✓	✗	Payer preference
Modify Maximum Value	✓	✗	Variable value only
Modify Payer Name	✗	✓	Receiver can update display name
Modify First Payment	✗	✓	Only when status is pending
Cancel Consent	✓	✓	Both can cancel
List Schedules	✓	✓	See own schedules
View Schedule Details	✓	✓	Full details
Cancel Schedule	✓*	✓*	Subject to cutoff times

*Payer cutoff: 11:59 PM D-1 | Receiver cutoff: 9:59 PM D-1

---

Error Codes

PIX Automatic specific error codes:

Code	HTTP Status	Message	Description
ZPY.PXA.001	404	Automatic Pix consent not found	The specified recurrence ID does not exist
ZPY.PXA.002	404	Automatic Pix schedule not found	The specified schedule ID does not exist
ZPY.PXA.003	502	Failed to confirm Automatic Pix consent	Banking provider error during confirmation
ZPY.PXA.004	502	Failed to modify Automatic Pix consent	Banking provider error during modification
ZPY.PXA.005	502	Failed to cancel Automatic Pix consent	Banking provider error during cancellation
ZPY.PXA.006	404	Automatic Pix QR code not found	Invalid or expired QR code reference
ZPY.PXA.007	400	Cancellation cutoff time has passed	Cannot cancel after cutoff deadline
ZPY.PXA.008	403	Operation not permitted	Caller does not have permission for this operation
ZPY.PXA.009	400	Cannot modify value for fixed consent	Fixed value consents cannot have value modified

---

Webhook Events

PIX Automatic generates webhook events for consent and schedule lifecycle changes. Subscribe to these events to receive real-time notifications.

Consent Events:

Event Type	Trigger	Description
pix.auto.consent.pending	Consent awaiting payer approval	New consent created, waiting for payer confirmation
pix.auto.consent.approved	Consent confirmed by payer	Payer approved the recurring payment
pix.auto.consent.rejected	Consent rejected by payer	Payer declined the recurring payment
pix.auto.consent.canceled	Consent canceled	Consent was terminated by payer or receiver

Schedule Events:

Event Type	Trigger	Description
pix.auto.schedule.pending	Schedule created	New scheduled payment waiting for execution
pix.auto.schedule.settled	Payment executed	Scheduled payment completed successfully
pix.auto.schedule.failed	Payment failed	Scheduled payment execution failed (may be retried)
pix.auto.schedule.canceled	Schedule canceled	Scheduled payment was canceled

Webhook Payload Example (Consent Pending):

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "pending",
    "description": "Monthly subscription - Premium Plan",
    "contract_id": "CONTRACT001",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value_type": "fixed",
    "value": 29.90,
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15"
}

Webhook Payload Example (Consent Approved):

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "approved",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value_type": "fixed",
    "value": 29.90,
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15",
    "message": "Consent approved by payer"
}

Webhook Payload Example (Schedule Settled):

{
    "type": "pix_auto_schedule",
    "schedule_id": "SCH001",
    "end_to_end_id": "E12345678202501151200abcdef123456",
    "status": "settled",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value": 29.90,
    "payment_date": "2025-01-15",
    "guidance": ""
}

Subscribing to Events:

Use wildcard patterns to subscribe to PIX Automatic events:

• pix.auto.* - All PIX Automatic events
• pix.auto.consent.* - All consent events
• pix.auto.schedule.* - All schedule events
• pix.auto.consent.approved - Specific event only

See the Webhooks section for complete webhook configuration, authentication, and retry policy documentation.

---

Webhooks

The ZAPPY platform sends real-time webhook notifications to your configured endpoints when banking events occur. These webhooks enable your application to react immediately to PIX payments, withdrawals, refunds, and PIX key status changes without polling our APIs.

Overview

How It Works:

1. Banking events occur (e.g., PIX payment received, withdrawal completed)
2. ZAPPY transforms the event to a clean, consistent format
3. Event is published to Google Cloud Pub/Sub for reliable delivery
4. Your configured webhook endpoint receives the notification
5. Automatic retries with exponential backoff on failures

Key Features:

• Reliable Delivery: Google Cloud Pub/Sub with automatic retries
• Event Filtering: Subscribe to specific event types using wildcards (e.g., pix.in.*)
• Transaction Type: Every payload includes a type field (credit, debit, refund) for easy classification
• Idempotency: 5-minute deduplication window prevents duplicate processing
• Correlation IDs: Track events across distributed systems
• Dead Letter Queue: Failed deliveries are logged for investigation

Transaction Type Field

All PIX transaction webhooks include a type field that indicates the nature of the transaction:

Type	Description	Event Types
credit	Money coming into the account	pix.in.*
debit	Money going out of the account	pix.out.*, pix.auto.*
refund	Reversal/refund transaction	pix.refund.in.*, pix.refund.out.*

This field simplifies transaction classification without needing to parse the event_type string.

Authentication

Webhooks are authenticated using one of two methods configured in your BFF webhook settings:

Basic Authentication:

Authorization: Basic base64(username:password)

Bearer Token:

Authorization: Bearer {your-token}

Common Headers

All webhook requests include these headers:

Content-Type: application/json
Accept: application/json
User-Agent: ZAPPY-RELAY/1.0

Event Types and Filtering

You can subscribe to specific event types using flexible pattern matching:

Pattern	Description	Example Events Matched
*	All events	All PIX In, PIX Out, Refunds, Keys, PIX Auto
pix.in.*	All PIX In events	pix.in.paid, pix.in.registered, etc.
pix.out.*	All PIX Out events	pix.out.paid, pix.out.completed, etc.
pix.*.paid	All paid events	pix.in.paid, pix.out.paid
pix.refund.in.*	All PIX In refunds	pix.refund.in.paid, pix.refund.in.canceled
pix.key.*	All PIX Key events	pix.key.created, pix.key.registered, etc.
pix.auto.*	All PIX Automatic events	pix.auto.consent.approved, pix.auto.schedule.settled, etc.
pix.auto.consent.*	All consent events	pix.auto.consent.pending, pix.auto.consent.approved, etc.
pix.auto.schedule.*	All schedule events	pix.auto.schedule.settled, pix.auto.schedule.failed, etc.
pix.in.paid	Exact match	Only pix.in.paid

PIX In Webhook Events

Sent when PIX payments are received in your accounts.

Event Types:

• pix.in.paid - Payment received and settled
• pix.in.registered - Payment registered
• pix.in.canceled - Payment canceled
• pix.in.error - Payment error

Payload Example:

{
  "type": "credit",
  "id": 123456,
  "document_number": 3573432,
  "end_to_end_id": "E12345678202401011200abcdef123456",
  "origin": {
    "name": "John Doe",
    "identifier": "12345678901",
    "bank": "001",
    "bank_branch": "0001",
    "bank_account": "12345",
    "bank_account_digit": "6",
    "ispb": "00000000",
    "spb": "001"
  },
  "destination": {
    "name": "Your Account Name",
    "identifier": "98765432100",
    "bank": "450",
    "bank_branch": "0001",
    "bank_account": "67890",
    "bank_account_digit": "1",
    "ispb": "00000000",
    "spb": "450",
    "pix_key": "customer@example.com"
  },
  "qrcode": {
    "id": "unique-qrcode-id",
    "type": "dynamic",
    "document_number": 3573432,
    "reference": "your-reference-123",
    "payer": {
      "name": "John Doe",
      "identifier": "12345678901"
    },
    "value": {
      "principal": 100.00,
      "rebate": 0.00,
      "discount": 5.00,
      "interest": 0.00,
      "fine": 0.00
    }
  },
  "receipt_url": "https://banking-provider.example.com/receipt/123456",
  "value": 100.00,
  "status": "paid",
  "tags": ["account_id=your-account-uuid"],
  "message": "Payment for order #123",
  "transfer_date": "2024-01-01",
  "initiation_type": "DICT"
}

PIX Out Webhook Events

Sent when PIX withdrawals are processed from your accounts.

Event Types:

• pix.out.paid - Withdrawal completed successfully (final state)
• pix.out.canceled - Withdrawal canceled (final state)

Note: Only final transaction states trigger webhook notifications. Intermediate processing states (such as registration or validation) do not generate webhook events.

Payload Example:

{
  "type": "debit",
  "document_number": 123456,
  "reference": "your-withdrawal-ref-456",
  "end_to_end_id": "E12345678202401011200xyz789",
  "origin": {
    "name": "Your Account Name",
    "identifier": "98765432100",
    "bank": "450",
    "bank_branch": "0001",
    "bank_account": "67890",
    "bank_account_digit": "1",
    "ispb": "00000000",
    "spb": "450"
  },
  "destination": {
    "name": "Jane Smith",
    "identifier": "11122233344",
    "bank": "001",
    "bank_branch": "0002",
    "bank_account": "54321",
    "bank_account_digit": "9",
    "ispb": "00000000",
    "spb": "001",
    "pix_key": "jane@example.com"
  },
  "receipt_url": "https://banking-provider.example.com/receipt/456",
  "value": 250.50,
  "status": "paid",
  "tags": ["account_id=your-account-uuid"],
  "payment_date": "2024-01-01T14:30:00Z"
}

PIX Refund Webhook Events

Sent when refunds are processed (both incoming and outgoing).

Event Types:

• pix.refund.in.paid - Refund of incoming PIX completed
• pix.refund.in.canceled - Refund canceled
• pix.refund.out.paid - Refund of outgoing PIX received
• pix.refund.out.canceled - Refund canceled

Refund PIX In Payload

Refunds for incoming payments include refund_code:

{
  "type": "refund",
  "id": 12345,
  "document_number": 3573431,
  "end_to_end_id": "E12345678202401021500refund",
  "origin": { "name": "...", "identifier": "...", "bank": "...", "..." : "..." },
  "destination": { "name": "...", "identifier": "...", "bank": "...", "..." : "..." },
  "value": 100.0,
  "status": "paid",
  "transfer_date": "2024-01-02T15:00:00Z",
  "refund_date": "2024-01-02T15:00:00Z",
  "refund_code": "MD06",
  "initiation_e2e_id": "E12345678202401011200original",
  "initiation_document_number": "3573430",
  "method": "RefundPixIn"
}

Refund PIX Out Payload

Refunds for outgoing payments include pix_out_identifier (the original payment reference):

{
  "type": "refund",
  "document_number": 5593541,
  "reference": "3921731e-089f-4278-9913-69801f827411",
  "end_to_end_id": "",
  "origin": { "name": "Maria da Silva", "identifier": "12345678902", "bank": "450", "..." : "..." },
  "destination": { "name": "João da Silva", "identifier": "12345678901", "bank": "450", "..." : "..." },
  "receipt_url": "http://www.pdfurl.com.br/",
  "value": 1.0,
  "status": "paid",
  "payment_date": "",
  "refund_date": "2022-10-25T16:19:42.347",
  "initiation_e2e_id": "E2101818909290219019210109302018",
  "initiation_document_number": "764",
  "method": "RefundPixOut",
  "pix_out_identifier": "payment32434"
}

Note: refund_code is only available for RefundPixIn. RefundPixOut uses pix_out_identifier instead.

PIX Key Webhook Events

Sent when PIX key registration status changes.

Event Types:

• pix.key.created - PIX key created
• pix.key.registered - PIX key successfully registered with Central Bank
• pix.key.status.updated - PIX key status changed
• pix.key.changed - PIX key ownership changed
• pix.key.canceled - PIX key canceled
• pix.key.claiming - PIX key claim initiated
• Additional claim-related events

Payload Example:

{
  "document_number": 3573432,
  "type": "Email",
  "key": "customer@example.com",
  "action": "pix.key.registered",
  "method": "CreatePixKey",
  "status": "registered",
  "business_unit_id": 1234
}

Webhook Response

Your endpoint must respond with a 2xx status code to acknowledge receipt:

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Webhook received"
}

Important:

• Respond within 30 seconds to avoid timeouts
• Return 2xx for successful processing
• Return 5xx to trigger automatic retries
• Return 4xx for permanent failures (no retries)

Retry Policy

Automatic Retries:

• Triggered on 5xx responses or network errors
• Exponential backoff strategy
• Managed by Google Cloud Pub/Sub
• Maximum retry duration configurable

Dead Letter Queue: Failed deliveries are sent to a dead letter queue with detailed information:

{
  "original_event_type": "pix.in.paid",
  "account_id": "your-account-uuid",
  "webhook_url": "https://your-app.com/webhook",
  "failure_reason": "webhook returned non-2xx status: 500",
  "attempts": 1,
  "last_error": "connection timeout",
  "failed_at": "2024-01-01T12:00:00Z",
  "correlation_id": "correlation-uuid",
  "payload": "{...webhook payload...}"
}

Best Practices

1. Idempotency: Use end_to_end_id or document_number to prevent duplicate processing
2. Async Processing: Acknowledge receipt immediately (200 OK), process asynchronously
3. Correlation IDs: Use for distributed tracing and debugging
4. Secure Endpoints: Use HTTPS with valid SSL certificates
5. Monitor Failures: Check dead letter queue for failed deliveries
6. Timeout Handling: Respond within 30 seconds maximum

---

Health Check

GET /baas/health

Returns the health status of the BaaS service. This endpoint can be used for monitoring and health checks by load balancers or monitoring systems.

Request: None

Response 200 OK:

{
    "status": "OK",
    "message": "string"
}

---

Service Information

GET /baas/v1/

Returns basic information about the BaaS service including its name, description, and version number.

Request: None

Response 200 OK:

{
    "name": "baas",
    "description": "Banking as a Service integration service.",
    "version": "1.0.0"
}

---

Common Error Responses

All endpoints may return the following error responses in addition to their specific error scenarios:

400 Bad Request

Returned when request validation fails or required parameters are missing/invalid.

{
    "code": 400,
    "message": "Validation failed",
    "details": {
        "errors": "string"
    }
}

401 Unauthorized

Returned when authentication fails or the access token is invalid/expired.

{
    "code": 401,
    "message": "string"
}

404 Not Found

Returned when the requested resource or route is not found.

{
    "code": 404,
    "message": "The resource route was not found."
}

422 Unprocessable Entity

Returned when the request is valid but cannot be processed due to business logic constraints.

{
    "code": 422,
    "message": "string"
}

500 Internal Server Error

Returned when an unexpected server error occurs.

{
    "code": 500,
    "message": "internal server error"
}

---

Authentication Guide

Getting Started

1. Login: Call POST /iam/v1/auth/login with your credentials to obtain an access token and refresh token.

2. Using Access Tokens: Include the access token in the Authorization header of all protected endpoint requests:

   Authorization: Bearer <access_token>
   

3. Token Expiration: Access tokens expire after 15 minutes. When an access token expires, use the refresh token to obtain a new one.

4. Refreshing Tokens: Call POST /iam/v1/auth/refresh with your refresh token to get a new access token. Refresh tokens are valid for 15 days.

5. Logout: Call POST /iam/v1/auth/logout with your refresh token to invalidate all tokens and end the session.

BFF Integration

If you have an external session management system, you can use the BFF integration endpoint to obtain ZAPPY tokens:

1. Call POST /iam/v1/bff/session with your BFF session ID
2. Receive ZAPPY access and refresh tokens
3. Use these tokens for subsequent BaaS API calls

---

Date and Time Formats

• Date: YYYY-MM-DD (e.g., "2024-01-01")
• DateTime: YYYY-MM-DD HH:mm (e.g., "2024-01-01 15:30") for input
• ISO 8601: YYYY-MM-DDTHH:mm:ssZ (e.g., "2024-01-01T15:30:00Z") for responses

---

Pagination

List endpoints that return paginated results include a meta object in the response:

{
    "data": [...],
    "meta": {
        "page": 1,
        "limit": 50,
        "total": 250
    }
}

• page: Current page number
• limit: Number of items per page
• total: Total number of items available

---

Support

For technical support or questions about the ZAPPY API, please contact your account manager or refer to the platform documentation.

ZAPPY_AUTO_PIX.md

PIX Automatic (Pix Automatico) - Complete Flow Guide

PIX Automatic is a Central Bank of Brazil innovation that enables automated recurring payments through the PIX instant payment system. This document describes the complete flow, from consent creation to payment execution, including all webhook events, business rules, and architecture details.

---

Table of Contents

1. Introduction
2. Core Concepts
3. Payer Journey
4. Receiver Journey
5. Complete Lifecycle
6. Webhook Events
7. Business Rules
8. Status Definitions
9. Error Codes
10. Architecture Overview

---

Introduction

PIX Automatic (Pix Automatico) allows payers to pre-authorize recurring debits from their accounts, enabling businesses to automate collection of subscriptions, memberships, utility bills, and other recurring fees through the PIX instant payment system.

Primary Use Cases:

• Subscription services (streaming, software, memberships)
• Gym and fitness club memberships
• Recurring utility bill payments
• Insurance premium payments
• Loan installment collections
• SaaS billing

What makes PIX Automatic different from regular PIX:

• Payments are pre-authorized by the payer through a consent mechanism
• Payments execute automatically on a defined schedule without manual intervention
• The payer maintains full control to approve, modify, or cancel consents at any time
• Full Central Bank compliance with strict rules on scheduling, cancellation, and retry

---

Core Concepts

Consent (Recurrence)

A consent represents a payer's authorization for recurring debits. It defines:

• Who pays and who receives
• How often payments occur (frequency)
• How much each payment costs (value type and constraints)
• When payments start and optionally end

Each consent has a unique recurrence_id that identifies it throughout its lifecycle.

Schedule

A schedule represents an individual payment created from an approved consent. Each payment occurrence generates a schedule entry with its own schedule_id. Schedules track the execution status of each individual payment.

Payer (Debtor)

The account holder who authorizes and pays the recurring charges. The payer:

• Approves or rejects consent requests
• Can modify notification preferences and maximum values
• Can cancel consents and individual schedules

Receiver (Creditor)

The business or individual who receives the recurring payments. The receiver:

• Initiates consent requests (creates recurrences)
• Can generate QR codes for easy consent setup
• Can cancel consents and individual schedules (with earlier cutoff times)

Value Types

Type	Description	Key Rules
Fixed	Same amount every payment	value is set at creation and cannot be modified
Variable	Amount varies per payment	Receiver sets minimum_value (immutable); payer sets maximum_value during confirmation (modifiable)

Frequencies

Frequency	Description
weekly	Payment every week
monthly	Payment every month
quarterly	Payment every 3 months
annual	Payment once per year

---

Payer Journey

The payer has two ways to set up a consent:

Payer Journey 1: Webhook-Based Consent Confirmation

This flow is triggered when a receiver initiates a consent request.

┌─────────────────────────────────────────────────────────────────────────────┐
│              PAYER JOURNEY 1: WEBHOOK CONSENT CONFIRMATION                   │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver initiates consent request (via API or external system)
        ↓
Step 2: BaaS provider sends consent confirmation request
        ↓
Step 3: Your application receives webhook notification
        Event: pix.auto.consent.confirm
        Payload includes: recurrence_id, search_protocol, receiver info,
                          frequency, value_type, value constraints
        ↓
Step 4: Your app displays consent details to the payer for review:
        - Receiver name and tax number
        - Payment frequency and value
        - Validity period (initial_date to final_date)
        ↓
Step 5: Payer approves or rejects in your app
        ↓
Step 6: Your app calls POST /auto-pix/consents/{cid}/confirm
        {
            "search_protocol": "PROTO123456",
            "status": "approved",       // or "rejected"
            "notification": true,       // receive alerts before payments
            "maximum_value": 15000      // for variable value consents
        }
        ↓
Step 7: BaaS provider processes the confirmation
        ↓
Step 8: Your application receives result webhook
        Event: pix.auto.consent.approved  OR  pix.auto.consent.rejected

Important Notes:

• The payer must review consent details before confirming
• The search_protocol from the webhook must be included in the confirmation request
• For variable value consents, the payer can set a maximum_value limit
• Setting notification: true enables alerts before each payment execution

Payer Journey 2: QR Code Scanning

This flow is initiated when a payer scans a PIX Automatic QR code generated by a receiver.

┌─────────────────────────────────────────────────────────────────────────────┐
│                PAYER JOURNEY 2: QR CODE CONSENT CONFIRMATION                 │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver generates PIX Automatic QR code
        ↓
Step 2: Payer scans QR code using your app
        ↓
Step 3: Your app calls GET /auto-pix/qrcode/{hash}
        ↓
Step 4: ZAPPY returns consent information:
        {
            "recurrence_id": "REC123",
            "search_protocol": "PROTO456",
            "receiver": { "name": "...", "tax_number": "..." },
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 29.90
        }
        ↓
Step 5: Your app displays consent details to the payer for review
        ↓
Step 6: Payer approves or rejects in your app
        ↓
Step 7: Your app calls POST /auto-pix/consents/{cid}/confirm
        (Same as Payer Journey 1, Steps 6-8)

Important Notes:

• QR codes contain encoded consent parameters
• The search_protocol from the QR code info must be used in confirmation
• For variable value consents, the payer can set maximum_value during confirmation

---

Receiver Journey

The receiver has two ways to initiate a consent:

Receiver Journey 1: Create Recurrence (Direct)

Use this when you know the debtor's information and want to create a recurrence directly.

┌─────────────────────────────────────────────────────────────────────────────┐
│              RECEIVER JOURNEY 1: CREATE RECURRENCE (DIRECT)                  │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver calls POST /auto-pix/consents
        {
            "tax_number": "98765432100",
            "name": "John Doe",
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 29.90,
            "initial_date": "2025-02-15",
            "pix_key": "receiver@email.com"
        }
        ↓
Step 2: ZAPPY forwards request to the BaaS provider
        ↓
Step 3: Response:
        {
            "recurrence_id": "REC123456",
            "status": "pending",
            "message": "Recurrence created successfully"
        }
        ↓
Step 4: BaaS provider sends consent request to the debtor's bank
        ↓
Step 5: Receiver's webhook receives confirmation event
        Event: pix.auto.consent.confirm
        ↓
Step 6: Debtor approves consent via their own banking app
        ↓
Step 7: Receiver's webhook receives approval event
        Event: pix.auto.consent.approved
        ↓
Step 8: Payments execute automatically per frequency
        Event: pix.auto.schedule.settled (for each successful payment)

Request Fields:

Field	Type	Required	Description
tax_number	string	Yes	CPF (11 digits) or CNPJ (14 digits) of the payer
name	string	No	Display name of the payer
frequency	string	Yes	weekly, monthly, quarterly, annual
initial_date	string	Yes	Start date (YYYY-MM-DD)
final_date	string	No	End date (YYYY-MM-DD)
value_type	string	Yes	fixed or variable
value	number	Conditional	Required for fixed value type
minimum_value	number	Conditional	Used for variable value type
maximum_value	number	No	Used for variable value type
description	string	No	Description of the recurrence purpose
contract_id	string	No	External contract identifier
pix_key	string	No	Receiver's PIX key (uses account default if omitted)

Receiver Journey 2: Generate QR Code with Recurrence

Use this when you want to generate a QR code that any payer can scan to set up the recurrence.

┌─────────────────────────────────────────────────────────────────────────────┐
│            RECEIVER JOURNEY 2: GENERATE QR CODE WITH RECURRENCE              │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Receiver calls POST /auto-pix/qrcode
        {
            "pix_key": "receiver@email.com",
            "frequency": "monthly",
            "value_type": "fixed",
            "value": 29.90,
            "initial_date": "2025-02-15"
        }
        ↓
Step 2: ZAPPY generates QR code via BaaS provider
        ↓
Step 3: Response:
        {
            "hash_code": "bx7k9m2p4q8r1t5w3y6z0abc",
            "qrcode_base64": "iVBORw0KGgo...",
            "document_number": 245188468,
            "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
        ↓
Step 4: Receiver displays QR code to potential payer
        (e.g., on a website, printed invoice, or point-of-sale display)
        ↓
Step 5: Payer scans QR code with their banking app
        ↓
Step 6: Payer's bank creates recurrence from QR code data
        ↓
Step 7: Same lifecycle as Receiver Journey 1 (Steps 5-8)

Request Fields:

Field	Type	Required	Description
pix_key	string	Yes	Receiver's registered PIX key
frequency	string	Yes	weekly, monthly, quarterly, annual
initial_date	string	Yes	Start date (YYYY-MM-DD)
final_date	string	No	End date (YYYY-MM-DD)
value_type	string	Yes	fixed or variable
value	number	Conditional	Required for fixed value type
minimum_value	number	Conditional	Used for variable value type
maximum_value	number	No	Used for variable value type
description	string	No	Description of the recurrence purpose
contract_id	string	No	External contract identifier
tax_number	string	No	Pre-fill payer's CPF/CNPJ
name	string	No	Pre-fill payer's name

Key Differences from Journey 1:

• A registered PIX key is required
• tax_number is optional (any payer can scan the QR code)
• Returns a QR code image (qrcode_base64) and a reference for later lookup
• The reference can be used with GET /auto-pix/qrcode/:reference to look up QR code details

---

Complete Lifecycle

Here is the end-to-end lifecycle of a PIX Automatic recurrence, from creation to payment:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    PIX AUTOMATIC - COMPLETE LIFECYCLE                         │
└─────────────────────────────────────────────────────────────────────────────┘

Phase 1: CONSENT CREATION
─────────────────────────
    Receiver creates consent (Journey 1 or Journey 2)
        ↓
    BaaS provider registers the recurrence
        ↓
    Consent status: PENDING


Phase 2: PAYER CONFIRMATION
───────────────────────────
    BaaS provider notifies the payer's bank
        ↓
    Webhook: pix.auto.consent.confirm
        ↓
    Payer reviews and decides:
        ├── Approves → Webhook: pix.auto.consent.approved
        │                Consent status: APPROVED
        │
        └── Rejects  → Webhook: pix.auto.consent.rejected
                         Consent status: REJECTED (terminal)


Phase 3: PAYMENT SCHEDULING (only if approved)
───────────────────────────────────────────────
    BaaS provider automatically creates schedules based on frequency
        ↓
    For each scheduled payment:
        ├── Execution succeeds → Webhook: pix.auto.schedule.settled
        │                         Schedule status: SETTLED
        │
        ├── Execution fails    → Webhook: pix.auto.schedule.failed
        │                         Schedule status: FAILED
        │                         (may retry up to 3 times over 7 days)
        │
        └── Canceled           → Webhook: pix.auto.schedule.canceled
                                  Schedule status: CANCELED


Phase 4: CONSENT TERMINATION (optional)
───────────────────────────────────────
    Either party cancels the consent:
        ↓
    Consent status: CANCELED
    Future schedules: CANCELED (subject to cutoff rules)

Lifecycle Timing Example

For a monthly fixed-value consent starting February 2025:

Date	Event	Status
Jan 20	Receiver creates consent	Consent: pending
Jan 20	BaaS provider sends confirmation request	Webhook: pix.auto.consent.pending
Jan 21	Payer approves consent	Webhook: pix.auto.consent.approved
Feb 15	First payment executes	Webhook: pix.auto.schedule.settled
Mar 15	Second payment executes	Webhook: pix.auto.schedule.settled
Apr 10	Payer cancels consent	Consent: canceled, future schedules: canceled

---

Webhook Events

All PIX Automatic webhook events are delivered to your configured endpoint via the ZAPPY Relay Service. Events use the pix.auto.* namespace.

Consent Events

pix.auto.consent.pending

Sent when a new consent is created and awaiting payer approval. This is the initial notification for a new recurring payment consent.

Payload:

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "pending",
    "description": "Monthly subscription - Premium Plan",
    "contract_id": "CONTRACT001",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value_type": "fixed",
    "value": 29.90,
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15"
}

pix.auto.consent.approved

Sent when the payer approves a consent.

Payload:

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "approved",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value_type": "fixed",
    "value": 29.90,
    "frequency": "monthly",
    "initial_date": "2025-02-15",
    "final_date": "2026-02-15",
    "message": "Consent approved by payer"
}

pix.auto.consent.rejected

Sent when the payer rejects a consent.

Payload:

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "rejected",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "message": "Consent rejected by payer"
}

pix.auto.consent.canceled

Sent when a consent is canceled by either party.

Payload:

{
    "type": "pix_auto_consent",
    "recurrence_id": "REC123456",
    "status": "canceled",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "message": "Consent canceled"
}

Schedule Events

pix.auto.schedule.settled

Sent when a scheduled payment is executed successfully.

Payload:

{
    "type": "pix_auto_schedule",
    "schedule_id": "SCH001",
    "end_to_end_id": "E12345678202501151200abcdef123456",
    "status": "settled",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value": 29.90,
    "payment_date": "2025-02-15",
    "guidance": ""
}

pix.auto.schedule.failed

Sent when a scheduled payment execution fails. The payment may be retried automatically.

Payload:

{
    "type": "pix_auto_schedule",
    "schedule_id": "SCH002",
    "end_to_end_id": "",
    "status": "failed",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value": 29.90,
    "payment_date": "2025-02-15",
    "guidance": "Insufficient funds"
}

pix.auto.schedule.canceled

Sent when a scheduled payment is canceled.

Payload:

{
    "type": "pix_auto_schedule",
    "schedule_id": "SCH003",
    "end_to_end_id": "",
    "status": "canceled",
    "receiver": {
        "tax_number": "12345678000199",
        "name": "Streaming Service Inc"
    },
    "payer": {
        "tax_number": "98765432100",
        "name": "John Doe"
    },
    "value": 29.90,
    "payment_date": "2025-03-15",
    "guidance": "Consent canceled by payer"
}

Webhook Metadata (Pub/Sub Attributes)

Each webhook message includes metadata attributes used for routing and idempotency:

Attribute	Description	Example
event_type	The event type	pix.auto.consent.approved
type	Transaction type	debit
account_id	Resolved account UUID	uuid-string
webhook_id	Unique webhook identifier	uuid-string
correlation_id	Distributed tracing ID	uuid-string
dedup_key	Idempotency key	pix_auto_recurrence:REC123456

Event Filtering

Subscribe to PIX Automatic events using wildcard patterns:

Pattern	Events Matched
pix.auto.*	All PIX Automatic events
pix.auto.consent.*	All consent events (pending, approved, rejected, canceled)
pix.auto.schedule.*	All schedule events (pending, settled, failed, canceled)
pix.auto.consent.approved	Only consent approval events
pix.auto.schedule.settled	Only successful payment events

---

Business Rules

PIX Automatic operates under strict Central Bank of Brazil regulations. These rules are enforced by the platform and cannot be bypassed.

Scheduling Window

All scheduled payments must fall within the allowed scheduling window:

Constraint	Value	Description
Minimum	D+2	Payment must be scheduled at least 2 business days in advance
Maximum	D+10	Payment must be scheduled no more than 10 business days in advance

Example: If today is January 15th, valid payment dates are January 17th through January 25th.

Requests with payment dates outside this window will be rejected with error code ZPY.PXA.007.

Cancellation Cutoff Times

Different actors have different deadlines for canceling scheduled payments. All times are in America/Sao_Paulo timezone.

Actor	Cutoff Time	Description
Payer	11:59 PM on D-1	Payer can cancel until 1 minute before midnight on the day before payment
Receiver	9:59 PM on D-1	Receiver can cancel until 2 hours before payer cutoff

Example: For a payment scheduled on January 20th:

• Payer can cancel until January 19th at 11:59 PM
• Receiver can cancel until January 19th at 9:59 PM

Consent Cancellation Impact on Schedules

When a consent is canceled, the impact on existing schedules depends on timing:

Actor	Cancellation Time	D+1 Schedules	D+2+ Schedules
Payer	Any time	Canceled	Canceled
Receiver	Before 10:00 PM	Canceled	Canceled
Receiver	After 10:00 PM	Preserved	Canceled

Important: When a receiver cancels a consent after 10 PM, the next-day (D+1) payment will still be executed. This protects payers from unexpected last-minute cancellations.

Value Type Rules

Fixed Value Consent:

• Payment amount is set at consent creation and cannot be modified
• The value field contains the immutable payment amount
• To change the amount, the consent must be canceled and a new one created

Variable Value Consent:

• Receiver sets minimum_value at creation (immutable)
• Payer sets maximum_value during confirmation (can be modified later)
• Actual payment amounts can vary between minimum and maximum
• Important: Receiver cannot see the payer's maximum_value

Field	Set By	Modifiable	Visible To
minimum_value	Receiver	No	Both
maximum_value	Payer	Yes (by payer only)	Payer only

Retry Logic

Failed payments are automatically retried according to Central Bank rules:

Parameter	Value
Maximum retry attempts	3
Retry period	Up to 7 days
Retry windows per day	Up to 2
Payer notification	Required 24+ hours before retry

Retry logic is handled automatically by the BaaS provider. Your application will receive webhook notifications (pix.auto.schedule.failed or pix.auto.schedule.settled) for each attempt result.

---

Status Definitions

Consent Status

Status	Description
pending	Consent request received, awaiting payer confirmation
approved	Payer has approved, consent is active for scheduling
rejected	Payer has rejected the consent request (terminal)
canceled	Consent was canceled by payer or receiver (terminal)

Status Transitions:

pending ──► approved ──► canceled
   │
   └──────► rejected

Schedule Status

Status	Description
pending	Payment is scheduled, awaiting execution date
settled	Payment was executed successfully (terminal)
failed	Payment execution failed (may be retried automatically)
canceled	Payment was canceled before execution (terminal)

Status Transitions:

pending ──► settled
   │
   ├──────► failed (may retry → pending)
   │
   └──────► canceled

---

Error Codes

PIX Automatic specific error codes:

Code	HTTP Status	Message	Description
ZPY.PXA.001	404	Automatic Pix consent not found	The specified recurrence ID does not exist
ZPY.PXA.002	404	Automatic Pix schedule not found	The specified schedule ID does not exist
ZPY.PXA.003	502	Failed to confirm Automatic Pix consent	BaaS provider error during consent confirmation
ZPY.PXA.004	502	Failed to modify Automatic Pix consent	BaaS provider error during consent modification
ZPY.PXA.005	502	Failed to cancel Automatic Pix consent	BaaS provider error during consent cancellation
ZPY.PXA.006	404	Automatic Pix QR code not found	Invalid or expired QR code reference
ZPY.PXA.007	400	Cancellation cutoff time has passed	Cannot cancel after cutoff deadline
ZPY.PXA.008	502	Failed to create Automatic Pix consent	BaaS provider error during consent creation
ZPY.PXA.009	502	Failed to generate Automatic Pix QR code	BaaS provider error during QR code generation

---

Architecture Overview

System Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                         PIX AUTOMATIC ARCHITECTURE                           │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌──────────────┐
                    │  Your App    │
                    │  (Client)    │
                    └──────┬───────┘
                           │ REST API (JWT Auth)
                           ▼
                    ┌──────────────┐
                    │ ZAPPY BaaS   │ ◄── Webhook Endpoint (Basic Auth)
                    │  Service     │         from BaaS Provider
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │   BaaS   │ │  Redis   │ │  Relay   │
      │ Provider │ │  Cache   │ │ Service  │
      └──────────┘ └──────────┘ └────┬─────┘
                                     │
                                     ▼
                              ┌──────────────┐
                              │ Google Cloud  │
                              │   Pub/Sub     │
                              └──────┬───────┘
                                     │
                                     ▼
                              ┌──────────────┐
                              │  Your App    │
                              │  (Webhook)   │
                              └──────────────┘

API Request Flow

1. Client sends request to ZAPPY BaaS Service (e.g., POST /auto-pix/consents)
2. BaaS Service validates the request and resolves the account via BFF
3. BaaS Service forwards the request to the BaaS provider
4. BaaS provider processes the request and returns a response
5. BaaS Service transforms the response to ZAPPY format and returns to client

Webhook Processing Flow

1. BaaS provider sends webhook to ZAPPY BaaS Service (POST /webhooks/fitbank/auto-pix)
2. BaaS Service determines event type from Method field and transforms the payload:
   • NotifyRecurrencePixAutomatic → consent events (AutoPixConsentWebhookMessage)
   • NotifySchedulePixAutomatic → schedule events (AutoPixScheduleWebhookMessage)
3. BaaS Service resolves the account UUID via BFF (using debtor/payer tax number)
4. BaaS Service generates event type, correlation ID, and dedup key
5. BaaS Service sends the transformed payload to the Relay Service
6. Relay Service publishes to Google Cloud Pub/Sub (topic: fitbank-pix-auto)
7. Pub/Sub push subscription delivers the webhook to your configured endpoint

Caching Strategy

The BaaS Service uses Redis for caching frequently accessed data:

Cache Key Pattern	TTL	Purpose
fitbank:pix-auto:consent:{recurrence_id}	24h	Consent detail cache (reduces BaaS provider API calls)
fitbank:pix-auto:schedule:{schedule_id}	24h	Schedule detail cache
fitbank:pix-auto:webhook:{identifier}	24h	QR code metadata for webhook resolution

Cache Invalidation: Cache entries are automatically deleted after:

• Confirming a consent
• Modifying a consent
• Canceling a consent
• Canceling a schedule

Account Resolution for Webhooks

When a PIX Automatic webhook arrives, the system resolves the account UUID through this flow:

1. Extract debtor/payer TaxNumber from the webhook payload
2. Query the BFF service to find the account associated with that tax number
3. Use the resolved account UUID for Pub/Sub message routing

This ensures webhooks are delivered to the correct customer endpoint based on their account.

Permission Matrix

Access to operations depends on the caller's role:

Operation	Payer	Receiver	Notes
Create Consent	-	Yes	Receiver initiates recurrence
Generate QR Code	-	Yes	Receiver generates QR code
Confirm/Reject Consent	Yes	-	Payer exclusive
List Consents	Yes	Yes	See own consents
View Consent Details	Yes	Yes	maximum_value hidden from receiver
Modify Notification	Yes	-	Payer preference
Modify Credit Line	Yes	-	Payer preference
Modify Maximum Value	Yes	-	Variable value only
Modify Payer Name	-	Yes	Receiver can update display name
Modify First Payment	-	Yes	Only when status is pending
Cancel Consent	Yes	Yes	Both can cancel (different cutoff times)
List Schedules	Yes	Yes	See own schedules
View Schedule Details	Yes	Yes	Full details
Cancel Schedule	Yes*	Yes*	Subject to cutoff times

*Payer cutoff: 11:59 PM D-1 | Receiver cutoff: 9:59 PM D-1

ZAPPY_ERROR_CODES.md

WS ZAPPYPAG - API Error Codes

Complete reference of all error codes with their default messages and HTTP status mappings.

Format

• Code: ZPY.<CATEGORY>.<NUMBER>
• Category: Max 3 characters
• Number: 3-digit numeric code

---

AUT - Authentication & Authorization

Code	Constant	Message	HTTP Status
ZPY.AUT.001	CodeAutMissingToken	Authorization token is required	401
ZPY.AUT.002	CodeAutInvalidFormat	Invalid authorization token format	401
ZPY.AUT.003	CodeAutTokenExpired	The authentication token has expired	401
ZPY.AUT.004	CodeAutTokenNotYetValid	The authentication token is not yet valid	401
ZPY.AUT.005	CodeAutInvalidSignature	Invalid token signature	401
ZPY.AUT.006	CodeAutInvalidCreds	Invalid username or password	401
ZPY.AUT.007	CodeAutInvalidRefresh	Invalid or expired refresh token	401
ZPY.AUT.008	CodeAutSessionFailed	Session validation failed	401
ZPY.AUT.009	CodeAutInvalidScheme	Invalid authorization scheme	401
ZPY.AUT.010	CodeAutUnauthorized	You are not authorized to access this resource	401

---

VAL - Validation

Code	Constant	Message	HTTP Status
ZPY.VAL.001	CodeValRequired	One or more required fields are missing	400
ZPY.VAL.002	CodeValInvalidEmail	Invalid email address format	400
ZPY.VAL.003	CodeValInvalidPass	Password must be 8-64 characters with at least one letter, number, and special character	400
ZPY.VAL.004	CodeValLength	Field length does not meet requirements	400
ZPY.VAL.005	CodeValInvalidEnum	Invalid value provided for field	400
ZPY.VAL.006	CodeValInvalidUUID	Invalid UUID format	400
ZPY.VAL.007	CodeValInvalidDate	Invalid date format	400
ZPY.VAL.008	CodeValInvalidRange	Invalid date range provided	400
ZPY.VAL.009	CodeValInvalidNumeric	Invalid numeric value	400
ZPY.VAL.010	CodeValInvalidZip	Invalid ZIP code format (must be 8 digits)	400
ZPY.VAL.011	CodeValInvalidPayload	Request payload is malformed or invalid	400

---

ACC - Account Management

Code	Constant	Message	HTTP Status
ZPY.ACC.001	CodeAccNotFound	Account not found	404
ZPY.ACC.002	CodeAccNotActive	Account is not active	400
ZPY.ACC.003	CodeAccNotVerified	Account is not verified	400
ZPY.ACC.004	CodeAccInvalidStatus	Account status is invalid for this operation	400
ZPY.ACC.005	CodeAccFetchFailed	Failed to retrieve account information	502
ZPY.ACC.006	CodeAccBalanceFailed	Failed to retrieve account balance	502
ZPY.ACC.007	CodeAccTransactionFailed	Failed to retrieve account transactions	502

---

USR - User Management

Code	Constant	Message	HTTP Status
ZPY.USR.001	CodeUsrNotFound	User not found	404
ZPY.USR.002	CodeUsrAlreadyExists	A user with this email already exists	409
ZPY.USR.003	CodeUsrCreateFailed	Failed to create user	500
ZPY.USR.004	CodeUsrUpdateFailed	Failed to update user	500

---

PIX - PIX Operations

Code	Constant	Message	HTTP Status
ZPY.PIX.001	CodePixKeyNotRegistered	No PIX key registered for this account	400
ZPY.PIX.002	CodePixKeyNotFound	PIX key not found	404
ZPY.PIX.003	CodePixInvalidKeyType	Invalid PIX key type	400
ZPY.PIX.004	CodePixQRCreateFailed	Failed to generate PIX QR code	502
ZPY.PIX.005	CodePixQRNotFound	QR code not found or has expired	404
ZPY.PIX.006	CodePixQRCancelFailed	Failed to cancel QR code	502
ZPY.PIX.007	CodePixTxFetchFailed	Failed to retrieve PIX transactions	502
ZPY.PIX.008	CodePixRefundFailed	Failed to process PIX refund	502
ZPY.PIX.009	CodePixRefundNotFound	Refund transaction not found	404
ZPY.PIX.010	CodePixWithdrawFailed	Failed to process withdrawal	502
ZPY.PIX.011	CodePixWithdrawNotFound	Withdrawal transaction not found	404
ZPY.PIX.012	CodePixInvalidMethod	Invalid payment method	400
ZPY.PIX.013	CodePixMissingBankInfo	Bank account information is required for this payment method	400
ZPY.PIX.014	CodePixMissingKeyInfo	PIX key information is required for this payment method	400
ZPY.PIX.015	CodePixKeyStatusFailed	Failed to retrieve PIX key status	502
ZPY.PIX.016	CodePixKeyCancelFailed	Failed to cancel PIX key	502
ZPY.PIX.017	CodePixTxNotFound	PIX transaction not found	404

---

BNK - FitBank Integration

Code	Constant	Message	HTTP Status
ZPY.BNK.001	CodeBnkUnavailable	Banking service is temporarily unavailable	503
ZPY.BNK.002	CodeBnkRequestFailed	Banking service request failed	502
ZPY.BNK.003	CodeBnkReturnedError	Banking service returned an error	502
ZPY.BNK.004	CodeBnkParseFailed	Failed to process banking service response	502
ZPY.BNK.005	CodeBnkTimeout	Banking service request timed out	502
ZPY.BNK.006	CodeBnkInvalidCreds	Invalid banking service credentials	502

---

BFF - Backend For Frontend Integration

Code	Constant	Message	HTTP Status
ZPY.BFF.001	CodeBFFUnavailable	BFF service is temporarily unavailable	503
ZPY.BFF.002	CodeBFFRequestFailed	BFF service request failed	502
ZPY.BFF.003	CodeBFFReturnedError	BFF service returned an error	502
ZPY.BFF.004	CodeBFFParseFailed	Failed to process BFF service response	502
ZPY.BFF.005	CodeBFFTimeout	BFF service request timed out	502

---

WHK - Webhook Processing

Code	Constant	Message	HTTP Status
ZPY.WHK.001	CodeWhkInvalidPayload	Invalid webhook payload	400
ZPY.WHK.002	CodeWhkMissingAttrs	Missing required webhook attributes	400
ZPY.WHK.003	CodeWhkProcessFailed	Webhook processing failed	500
ZPY.WHK.004	CodeWhkDuplicate	Duplicate webhook message detected	500
ZPY.WHK.005	CodeWhkDeliveryFailed	Failed to deliver webhook	500
ZPY.WHK.006	CodeWhkTimeout	Webhook delivery timed out	500
ZPY.WHK.007	CodeWhkResolveFailed	Failed to resolve account from webhook	500
ZPY.WHK.008	CodeWhkDLQDetected	Dead letter queue message detected	500

---

RLY - Message Relay Operations

Code	Constant	Message	HTTP Status
ZPY.RLY.001	CodeRlyPublishFailed	Failed to publish message to relay	500
ZPY.RLY.002	CodeRlyInvalidFormat	Invalid relay message format	400
ZPY.RLY.003	CodeRlyDecodeFailed	Failed to decode relay message	400
ZPY.RLY.004	CodeRlyResolveFailed	Failed to resolve account UUID	500
ZPY.RLY.005	CodeRlyDeliveryFailed	Relay delivery failed	500

---

SYS - System/Internal Errors

Code	Constant	Message	HTTP Status
ZPY.SYS.001	CodeSysInternal	An internal server error occurred	500
ZPY.SYS.002	CodeSysUnavailable	Service is temporarily unavailable	503
ZPY.SYS.003	CodeSysConfig	Configuration error	500
ZPY.SYS.004	CodeSysUnexpected	An unexpected error occurred	500
ZPY.SYS.005	CodeSysMarshalFailed	Data serialization failed	500
ZPY.SYS.006	CodeSysTimeout	Operation timed out	500
ZPY.SYS.007	CodeSysDBConnFailed	Database connection failed	500
ZPY.SYS.008	CodeSysDBQueryFailed	Database query failed	500
ZPY.SYS.009	CodeSysDBTxFailed	Database transaction failed	500
ZPY.SYS.010	CodeSysDBNotFound	Record not found in database	404
ZPY.SYS.011	CodeSysDBDuplicate	Record already exists in database	409
ZPY.SYS.012	CodeSysDBConstraint	Database constraint violation	500
ZPY.SYS.013	CodeSysCacheUnavail	Cache service unavailable	503
ZPY.SYS.014	CodeSysCacheFailed	Cache operation failed	500
ZPY.SYS.015	CodeSysCacheParseFailed	Failed to parse cached data	500

---

Response Format

Standard Error Response

{
  "code": "ZPY.AUT.006",
  "message": "Invalid username or password"
}

Error with Details

{
  "code": "ZPY.ACC.001",
  "message": "Account not found",
  "details": {
    "account_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Validation Error

{
  "code": "ZPY.VAL.001",
  "message": "One or more required fields are missing",
  "details": {
    "errors": {
      "username": ["Username is required"],
      "password": ["Password is required"]
    }
  }
}