You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
IAM Service (Identity and Access Management): User authentication, JWT tokens, session management
BaaS Service (Banking as a Service): Banking API integration, PIX operations, webhook reception and message transformation
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.
{
"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.
{
"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.
{
"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.
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 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, or PIX key status changes occur. 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.
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.
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.
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.
{
"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.
{
"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.
{
"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.
{
"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.
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.
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).
{
"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.
Retrieves the current status of a specific PIX key. PIX keys can have various statuses during their lifecycle including "registering", "registered", "canceling", and "canceled".
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.
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.
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:
Transaction is stored with Created status immediately upon creation
No webhook notification is received at creation time
You must use the Get Withdrawal endpoint to query the transaction status during the waiting period
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.
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.
{
"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.
{
"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.
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.
{
"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
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.
Note: Only final transaction states trigger webhook notifications. Intermediate processing states (such as registration or validation) do not generate webhook events.
