Skip to main content
Build your integration with Pagsmile Open API v3. Choose an operation below to work with accounts, PIX and TED transfers, refunds, QR codes, onboarding, and webhook subscriptions.

​
Before your first request

1

Make sure you have successfully onboarded on our system

Complete your account registration and activation, then check your account type to see which features are available to you.
2

Choose your environment and the right credential

Use the base URL and matching credentials supplied for your integration.See Environments
3

Check access and sign the request

Identify your credential owner, check the endpoint’s account-target rules, and generate the HMAC-SHA256 signature.See Sign your Request
4

Read the result in context

Check the outer API result code, then interpret the returned operation status.See Error Catalog and Object & Enums References

​
Find an endpoint

​
Accounts and payments

Bank Account & Statements

Inspect account details and balances, then retrieve statement entries.

Transfers

Initiate and confirm PIX transfers, send PIX or TED to bank accounts, and check transfer results.

Charges

Retrieve the details of an incoming PIX charge by transaction identifier.

Refunds

Refund an eligible incoming PIX payment and inspect its details or processing status.

QR Codes

Generate static or dynamic PIX QR codes and retrieve QR-code details.

PIX Keys

Create or delete PIX keys for an account.

​
Onboarding and operations

Master Accounts

Create and manage master-account onboarding records, or retrieve an existing account.

Managed Accounts

Manage MOR, VA, and PA accounts and retrieve credentials for eligible active MOR or VA accounts.

Webhook Management

Create, retrieve, list, update, or delete callback subscriptions within your credential-owner scope.

MED & Infractions

Manage payer-side MED cases and inspect related infraction records available to your account.
Managed-account credential rotation is documented in the HTTP contract, but the current service returns an unsupported-operation error. It is not an available production capability. See Managed Accounts.

​
Common integration tasks

A successful API call does not by itself confirm final settlement. PIX key and QR-code transfers require an initiate/confirm flow. Follow the endpoint-specific status rules, and check the original operation’s outcome before retrying an uncertain submission.

​
Request rules

The following rules apply across the reference. Always check the endpoint’s Authentication and target section for its supported credential owners and any route-specific exceptions.

​
Authentication model

X-Client-ID identifies one of three credential owners. The credential owner determines which operations are allowed and whether an account target is required.

​
Conditional account-target headers

Send both headers together with non-empty values on permitted routes. A request is rejected when only one is present, either value is empty, or the target does not satisfy the credential rules.

​
Request signing

Every request is signed with HMAC-SHA256. Prepare the headers and signature from the exact request you will transmit.
1

Prepare the request headers

2

Assemble StringToSign

Join the following values with a line feed (\n) in this order:
  1. Uppercase HTTP method
  2. Request path
  3. Canonical query string
  4. Canonical headers
  5. Content hash
  6. Timestamp
  7. Nonce
3

Apply the canonicalization rules

Expand each rule below when implementing the signature. The canonical values must match the request received by the server.
Parse all query parameters, sort keys lexically, apply URL query escaping to every key and value, and join pairs as key=value&key2=value2.
Always include these lowercase names:
  • content-type
  • x-client-id
  • x-nonce
  • x-timestamp
Include x-content-hash only when a non-empty X-Content-Hash header is sent. When the account-target pair is sent, also include x-account-number and x-ispb.Trim every value, sort the included lowercase header names lexically, and join the lines as key:value with a line feed between lines. The canonical values must exactly match the headers received by the server.
If X-Content-Hash is supplied, use that value in the signature and ensure it equals the lowercase SHA-256 hex digest of the exact raw request body. If the header is omitted, the server computes the body hash; do not include x-content-hash in canonical headers.

​
Validation requirements

  • Use a unique nonce for each client request.
  • Send the timestamp as Unix milliseconds within the accepted clock-skew window.
  • Call from an IP address in the configured allowlist.
  • Sign the exact path, query, headers, and raw body that are transmitted.
Follow each endpoint’s Authentication and target section for the allowed credential owners and account-target behavior.
For a walkthrough, open Sign your request. If a call fails, use the authentication and permission codes to choose the next check.