Sign your Request

A signature proves that the request was created using your API secret and has not changed since it was signed. Calculate it from the same method, path, query, headers, and raw body that you send.

Prepare the body and headers

Serialize the JSON body once and retain its exact raw bytes. Generate a fresh nonce for each call and a Unix timestamp in milliseconds.

Header	Requirement	Value
`Content-Type`	Required	`application/json`
`X-Client-ID`	Required	Your client ID.
`X-Timestamp`	Required	The current Unix timestamp in milliseconds.
`X-Nonce`	Required	A fresh nonce for this request.
`X-Signature`	Required	The lowercase hexadecimal HMAC-SHA256 signature calculated below.
`X-Content-Hash`	Optional	The lowercase hexadecimal SHA-256 digest of the exact raw body.
`X-ISPB`, `X-Account-Number`	Depends on credential and endpoint	Both account-target values, when required or permitted.

Requests outside the five-minute timestamp window are rejected. Nonces are retained for ten minutes to prevent replay.

Build the canonical string

Calculate the lowercase hexadecimal SHA-256 hash of the raw body, even if you omit the optional X-Content-Hash header.Join the following seven components with a single line feed (\n). Do not add a trailing line feed:

UPPERCASE_METHOD
normalized_path
canonical_query
canonical_headers
content_hash
timestamp
nonce

An empty query still occupies its blank line. For a documented path such as /v3/bank_account, use the path without the base URL.Canonical headers: use lowercase names, trim values, and sort names lexically. Always include content-type, x-client-id, x-nonce, and x-timestamp. Include x-content-hash, x-account-number, and x-ispb only when those headers are sent. Do not include X-Signature itself.Canonical query: sort parameter names lexically, preserve the original value order for repeated names, and encode names and values using Go url.QueryEscape semantics.

Calculate the signature

Calculate HMAC-SHA256 over the canonical string using your API secret. Encode the result as 64 lowercase hexadecimal characters and send it as X-Signature.Send the exact raw body used to calculate the hash. Changing whitespace, property order, or other body bytes after signing changes the signature input.

Example header set for USER account access

For an account-level operation with a USER credential, add both target headers before calculating the signature. These are illustrative values; generate a current timestamp, fresh nonce, body hash, and signature for your request.

Content-Type: application/json
X-Client-ID: ak_user_demo
X-ISPB: 12345678
X-Account-Number: 00012345
X-Timestamp: 1710000000000
X-Nonce: 00112233445566778899aabbccddeeff
X-Content-Hash: LOWERCASE_SHA256_OF_RAW_BODY
X-Signature: LOWERCASE_HMAC_SHA256_SIGNATURE

For this header set, the canonical names are ordered as content-type, x-account-number, x-client-id, x-content-hash, x-ispb, x-nonce, and x-timestamp. Omit x-content-hash from the canonical headers only if you omit that request header.

Send your first request

Use Get Bank Account to retrieve account information without initiating a payment. It accepts an empty JSON object and requires an ACCOUNT credential or a USER credential with both account-target headers.

POST /v3/bank_account

The following request template uses an ACCOUNT credential bound to the account you want to retrieve. Set BASE_URL and CLIENT_ID from your issued configuration, then calculate TIMESTAMP_MS, NONCE, CONTENT_HASH, and SIGNATURE using the signing steps above. The body to hash and send is exactly {}.

curl --request POST "${BASE_URL}/v3/bank_account" \
  --header "Content-Type: application/json" \
  --header "X-Client-ID: ${CLIENT_ID}" \
  --header "X-Timestamp: ${TIMESTAMP_MS}" \
  --header "X-Nonce: ${NONCE}" \
  --header "X-Content-Hash: ${CONTENT_HASH}" \
  --header "X-Signature: ${SIGNATURE}" \
  --data-binary '{}'

Using a USER credential? Add X-ISPB and X-Account-Number to both the request and canonical headers, then recalculate the signature. A PLATFORM credential cannot call this endpoint.

A successful response contains account identifiers, balances, active PIX keys, limits, webhooks, and fee information. See the endpoint reference for the complete response and fallback behavior.

Handle the response

Normal API processing returns a JSON envelope. The example below illustrates its structure; data varies by endpoint.

{
  "code": 200,
  "message": "success",
  "data": {},
  "time": 1710000000000
}

HTTP 200 does not necessarily mean the operation succeeded. Enveloped errors also use HTTP 200. Treat the outer JSON code as the business result: 200 means success; every other value means failure.

Check the HTTP response and whether it contains a JSON envelope.
For an envelope, read the outer code. On failure, data is null.
Choose your error-handling action by code, not by the localized message text.
Handle non-envelope responses separately. Malformed input can return HTTP 400 with plain text; unhandled failures can return plain text, normally with HTTP 500.

Historical error or result fields nested inside data do not override the outer result. Use Error Catalog for the full response contract.

Troubleshoot your first request

Outer code	What to check
`4004102`	Required request headers and metadata.
`4004103`	Whether the request’s source IP is allowlisted.
`4004104`	Whether the body hash matches the exact bytes sent.
`4004105`	The timestamp unit, current time, and five-minute window.
`4004106`	Nonce validity and whether the nonce was reused.
`4004107`	The canonical string, matching API secret, and signature.
`4004003`	Credential permissions and account scope.
`4004008` / `4004010`	Whether the selected account is active and exists.

For every retry, generate a fresh timestamp, nonce, body hash, and signature. Follow the endpoint’s retry and duplicate-handling rules before repeating an operation.

Connect webhooks

Webhooks notify your application about transaction, KYB, and MED events. Pagsmile sends signed HTTP POST requests to your callback URL.

Choose your events and subscription scope

Use Webhooks to identify the event family and permitted owner scope. For the supported PIX and KYB event values, see Webhook Management. MED uses a separate subscription family; it is not represented by the numeric event values accepted by the management API.

Verify each delivery

Retain the raw request body and verify the content hash, signature, timestamp, and nonce before processing the event. Follow Signature Verification.

Accept and process events reliably

Store the event with its documented idempotency key, then return HTTP 200 after durable acceptance. Process asynchronously and handle duplicate or out-of-order deliveries. Use a callback URL that returns HTTP 200 directly, without redirects. See Delivery and Retries.

Before handling live operations

Confirm the assigned environment, credential scope, and target account for each operation.
Check both successful and failed responses; do not infer success from HTTP status alone.
Use decimal strings and decimal arithmetic for monetary values. See Object & Enums References.
Verify webhook signatures and duplicate handling before relying on event notifications.
Keep API secrets and one-time credential values out of logs.

Choose an API operation

Explore endpoints for accounts, transfers, charges, and refunds.

Handle errors consistently

Map business result codes to the right client behavior.

Getting started

API Reference

Send your first request

Handle the response

Connect webhooks

Before handling live operations

Choose an API operation

Handle errors consistently

​Send your first request

​Handle the response

​Connect webhooks

​Before handling live operations

Choose an API operation

Handle errors consistently

Send your first request

Handle the response

Connect webhooks

Before handling live operations