Start integrating
Learn how to register and complete the identity or business verification required for your account.
Explore the API
Find request parameters, response fields, validation rules, and examples for each operation.
What you can build
Choose the workflow that matches your application.Product Capabilities
| Capability | Supported Features |
|---|---|
| Account Opening & Management | MOR, VA, and PA account creation and inquiry |
| Account & Funds Inquiry | Bank account information, balances, frozen amounts, fee and limit configurations, and transaction history |
| Pix Key Management | Create, retrieve active Pix Keys associated with an account, and delete Pix Keys |
| Payment Collection | Generate dynamic and static Pix QR Codes, retrieve QR Code details, and query Pix incoming payment details |
| Payments & Transfers | Pix Key payments, Pix QR Code payments, Pix bank account transfers, TED bank account transfers, and internal transfers within the same financial institution |
| Refunds | Refund original Pix incoming payments, retrieve refund details, and check refund status |
| Dispute Management | Create, query, and cancel eligible MED cases; query Infraction records |
| Event Notifications | Manage webhook subscriptions for Pix incoming and outgoing payments, refunds, and account compliance events |
Relationship Between Accounts and Payment Functions
- After opening an account, verify its compliance status and confirm that the bank account is ready before using the enabled account services and payment capabilities.
- Collections, payments, and account inquiries must use the appropriate authorization context for the target account. Account ownership and hierarchy do not imply automatic balance aggregation.
- Pix refunds must be linked to the original collection transaction. MED cases must also be linked to the original Pix transaction and meet their respective business requirements. The connections indicate business relationships, not call sequences or quantity relationships.
- Webhooks notify the business of changes based on subscribed event types and scopes. Use detail, status, and transaction record queries to confirm processing results. MED callbacks are subject to the enabled services and agreed delivery scope.
Key Terminology
| Term | Definition |
|---|---|
| MA / Master Account | The master account that establishes the business entity and defines ownership and management relationships for managed accounts. |
| Managed Account | A managed account, including MOR, VA, and PA. |
| MOR | An operational account that reuses the approved compliance records of its associated MA. |
| VA | A managed account that must belong to a parent MA and maintains its own compliance records and bank account. |
| PA | A payment account that must belong to a parent MA or a VA under that MA, and maintains its own compliance records and bank account. |
| PLATFORM / USER / ACCOUNT | The three API credential identities: platform-level, user-level, and bank account-level. |
| ISPB | The bank institution identifier, which is used together with the bank account number to identify an account. |
| Pix Key | An identifier that points to a Pix receiving account. It is distinct from API signing credentials. |
| EndToEnd ID | The identifier of the original Pix transaction, used to link transactions and perform operations such as MED case handling. |
| Webhook | A mechanism for notifying the integrating party of business events by sending callbacks to a designated URL. |
| MED / Infraction | A special Pix return and recovery mechanism, and the associated violation reports. |
Pagsmile Feature Overview
The Pagsmile Open API integrates account and payment services into your business system. Through the API, you can create managed accounts, retrieve bank account information, manage Pix Keys, initiate payments and refunds, and track processing results through query APIs and event notifications. Business operations use POST requests with JSON request bodies and AK/SK signature authentication. Account permissions are determined by the credential type, account ownership, and target account.Intended Audience
The Open API is designed for businesses and platforms that need to manage accounts, payments, and transaction results within their own systems. Integrators can manage their own primary accounts. With the appropriate permissions for managed accounts, they can also create Virtual Accounts (VAs) or Platform Accounts (PAs) for their business entities and manage each account’s information and transaction records separately. Account creation and management, fund operations, and event subscriptions have different authorization scopes. Before integration, configure the appropriate credentials based on the features you need to use.Start your integration
1
Set up your account
Register and complete the verification required for your individual or business account.Follow the account setup guide →
2
Prepare your API access
Confirm your base URL and matching credentials with your Pagsmile integration representative. Check which credential type your chosen operation requires.Configure your environment →
3
Build a signed request
API requests use JSON and an HMAC-SHA256 signature. Follow the integration guide to prepare the headers, sign the request, and read the response.Learn how to authenticate requests →
4
Connect your payment workflow
Use the reference for your chosen operation, then implement status checks and webhook handling where applicable. Some operations finish asynchronously, so an accepted request may still be processing.Choose an API operation → · Handle webhook events →
Keep these references handy
- Error catalog — understand response codes and investigate failed requests.
- Objects and enums — look up shared fields, types, and status values.
- Webhook delivery and retries — handle acknowledgements, duplicate events, and delivery order.