Authentication

Deposits Withdrawals Glossary Webhooks

Every call to the Conta Digital API uses a Bearer Token in the Authorization header. The token is provided in the PayZu Dashboard.

Header format

Every request requires two mandatory headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Example

curl https://pix.payzu.io/v1/user/balance \
  -H "Authorization: Bearer $PAYZU_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://pix.payzu.io/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

import os, requests

res = requests.get(
    'https://pix.payzu.io/v1/user/balance',
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)

Important

Keep the token secure, never share it publicly or commit it to a repository
Per-token permissions, each one carries scopes defined at creation time
Token compromised? Regenerate it immediately in the PayZu Dashboard and revoke the old one

Error format

Every error response follows the same format. The most important field is requestId, which identifies the call in PayZu's internal logs.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

Field	What it's for
`statusCode`	HTTP response code
`error`	Short error name
`message`	Description in PT of what happened
`requestId`	Unique ID of the call. Send it when opening a support ticket

Where to store

Where to store	OK?
Google Secret Manager	Yes
AWS Secrets Manager	Yes
HashiCorp Vault	Yes
Environment variable in CI	Yes
`.env` in production	No
Front-end (Web, Mobile)	Never

Support

Open ticket Support portal