PIX Transfer
Overview
The POST /dict/pix endpoint initiates a PIX transfer to the specified key. The key can be a CPF, CNPJ, email, phone number, or EVP (random key).
This endpoint follows the Central Bank specification for PIX transfers via DICT (Directory of Transactional Account Identifiers).
Endpoint
POST /dict/pixAuthentication
Bearer token obtained via /oauth/token.
Unique request identifier for idempotency support. Must be a UUID v4.
Example: 550e8400-e29b-41d4-a716-446655440000
Request Body
Destination PIX key. Can be:
- CPF: 11 numeric digits
- CNPJ: 14 numeric digits
- Email: valid email address
- Phone: +55AREACODENUMBER (e.g., +5511999999999)
- EVP: Random key (UUID)
Creditor's document (CPF or CNPJ). Required when priority = HIGH for instant validation.
Processing priority:
HIGH: Processed instantly (requirescreditorDocument)NORM: Standard queue processing
Message accompanying the PIX transfer. Will be displayed to the recipient.
Payment flow (optional). Used for internal categorization.
Maximum time in seconds that the operation can remain in the queue before being cancelled.
- Minimum: 1 second
- Maximum: 10800 seconds (3 hours)
- Default: 600 seconds (10 minutes)
Payment data.
List of ISPB codes for which payments will not be allowed. Useful for blocking transfers to specific institutions.
Example: ["12345678", "87654321"]
Request
curl -X POST https://api.safirapay.com/dict/pix \
-H "Authorization: Bearer <token>" \
-H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"pixKey": "12345678909",
"creditorDocument": "12345678909",
"priority": "NORM",
"description": "Pagamento referente a NF 12345",
"expiration": 600,
"payment": {
"currency": "BRL",
"amount": 100.50
}
}'const response = await fetch('https://api.safirapay.com/dict/pix', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'x-idempotency-key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
pixKey: '12345678909',
creditorDocument: '12345678909',
priority: 'NORM',
description: 'Pagamento referente a NF 12345',
expiration: 600,
payment: {
currency: 'BRL',
amount: 100.50,
},
}),
});
const transfer = await response.json();import requests
import uuid
response = requests.post(
'https://api.safirapay.com/dict/pix',
headers={
'Authorization': f'Bearer {token}',
'x-idempotency-key': str(uuid.uuid4()),
'Content-Type': 'application/json',
},
json={
'pixKey': '12345678909',
'creditorDocument': '12345678909',
'priority': 'NORM',
'description': 'Pagamento referente a NF 12345',
'expiration': 600,
'payment': {
'currency': 'BRL',
'amount': 100.50,
},
}
)
transfer = response.json()Response
{
"endToEndId": "550e8400-e29b-41d4-a716-446655440000",
"eventDate": "2024-01-15T10:30:00.000Z",
"id": 12345,
"payment": {
"amount": 100.50
},
"type": "PENDING"
}{
"statusCode": 400,
"message": "Chave PIX inválida",
"error": "Bad Request"
}{
"statusCode": 422,
"message": "Chave PIX não encontrada no DICT",
"error": "Unprocessable Entity"
}Response Fields
endToEndIdstringUnique PIX transaction identifier. The actual E2E value will be sent in the webhook when the transaction is settled.
eventDatestringEvent date and time (ISO 8601).
idnumberUnique transaction identifier.
paymentobjecttypestringTransaction type/status:
PENDING: Transfer is being processedCOMPLETED: Transfer completedERROR: Transfer failed
Idempotency
The x-idempotency-key header ensures that the same request is not processed more than once:
// Same idempotency key = same response
const key = '550e8400-e29b-41d4-a716-446655440000';
// First call - creates the transfer
const res1 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' }
// Second call with same key - returns the same transfer
const res2 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' } (does not create a new one)The x-idempotency-key is required. Requests without this header will be rejected.
Transfer Webhook
When the transfer is processed, you will receive a V2 webhook of type TRANSFER:
{
"type": "TRANSFER",
"data": {
"id": 12345,
"txId": null,
"pixKey": "12345678909",
"status": "LIQUIDATED",
"payment": {
"amount": "100.50",
"currency": "BRL"
},
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"creditorAccount": {
"name": "João Silva",
"document": "123.xxx.xxx-xx",
"ispb": "18236120"
},
"remittanceInformation": "Pagamento referente a NF 12345"
}
}TRANSFER Webhooks
See the full TRANSFER webhook documentation
PIX Key Types
| Type | Format | Example |
|---|---|---|
| CPF | 11 digits | 12345678909 |
| CNPJ | 14 digits | 12345678000195 |
| valid email | joao@email.com | |
| Phone | +55AREACODENUMBER | +5511999999999 |
| EVP | UUID | 7d9f0335-8dcc-4054-9bf9-0dbd61d36906 |
Processing Priority
ISPB Blocking
Use ispbDeny to block transfers to specific institutions:
{
"pixKey": "joao@email.com",
"payment": { "amount": 100.00 },
"ispbDeny": [
"12345678",
"87654321"
]
}If the PIX key belongs to a blocked institution, the transfer will be rejected.
Common Errors
| Code | Error | Solution |
|---|---|---|
| 400 | Invalid PIX key | Check the key format |
| 400 | Invalid value | Use a number with up to 2 decimal places |
| 400 | Missing idempotency key | Include the x-idempotency-key header |
| 401 | Invalid token | Renew the access token |
| 422 | Key not found | The key does not exist in the DICT |
| 422 | Insufficient balance | Check the available balance |
| 422 | Blocked ISPB | The institution is in the ispbDeny list |