Criar transferência
curl --request POST \
--url https://api.upag.io/v1/transfers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"pixKey": "<string>",
"pixKeyType": "<string>",
"amount": 123,
"hash": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: '<string>',
pixKey: '<string>',
pixKeyType: '<string>',
amount: 123,
hash: '<string>'
})
};
fetch('https://api.upag.io/v1/transfers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/transfers';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: '<string>',
pixKey: '<string>',
pixKeyType: '<string>',
amount: 123,
hash: '<string>'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Transferências Pix
Criar transferência
Envia um Pix pela chave de API (sem PIN)
POST
https://api.upag.io
/
v1
/
transfers
Criar transferência
curl --request POST \
--url https://api.upag.io/v1/transfers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"pixKey": "<string>",
"pixKeyType": "<string>",
"amount": 123,
"hash": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: '<string>',
pixKey: '<string>',
pixKeyType: '<string>',
amount: 123,
hash: '<string>'
})
};
fetch('https://api.upag.io/v1/transfers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/transfers';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: '<string>',
pixKey: '<string>',
pixKeyType: '<string>',
amount: 123,
hash: '<string>'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Envia um Pix da conta, para uma chave Pix (
O valor é lido do QR code (valor final, em centavos na resposta); não envie
A transferência nasce em
type: "key") ou para um copia-e-cola (type: "hash"). Com chave secreta o Pix de saída não exige PIN. Valores em centavos.
Permissão: transfer.write. Apenas chave secreta (sk_…). Transferência para beneficiário salvo (type: "beneficiary") não está disponível pela chave de API.
Os exemplos usam o sandbox (
https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_….Endpoint
Chave Pix
curl -X POST https://api.upag.dev/v1/transfers \
-H "Authorization: Bearer sk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"type": "key",
"pixKey": "55ce1aae-0d2b-4d76-bc77-294d6407349e",
"pixKeyType": "random",
"amount": 10000,
"description": "Pagamento fornecedor"
}'
import { Upag } from 'upag';
const upag = new Upag('sk_test_your_api_key');
const transfer = await upag.transfers.create({
type: 'key',
pixKey: '55ce1aae-0d2b-4d76-bc77-294d6407349e',
pixKeyType: 'random',
amount: 10000,
description: 'Pagamento fornecedor',
});
Copia-e-cola
curl -X POST https://api.upag.dev/v1/transfers \
-H "Authorization: Bearer sk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"type": "hash",
"hash": "00020126580014br.gov.bcb.pix..."
}'
import { Upag } from 'upag';
const upag = new Upag('sk_test_your_api_key');
const transfer = await upag.transfers.create({
type: 'hash',
hash: '00020126580014br.gov.bcb.pix...',
});
amount com hash. Consulte antes com Consultar destino se quiser conferir titular e valor.
Parâmetros
Resposta
201 Created. A transferência vem com transaction, o débito lançado no extrato da conta.
Response
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"direction": "out",
"type": "key",
"amount": 10000,
"pixKey": "55ce1aae-0d2b-4d76-bc77-294d6407349e",
"pixKeyType": "random",
"from": {
"name": "Acme LTDA",
"taxNumber": "12345678000199",
"bankName": "Upag"
},
"to": {
"name": "Maria Receiver",
"taxNumber": "111.444.777-35",
"bankName": "FitBank"
},
"endToEndId": null,
"providerTransactionId": "555",
"url": null,
"createdAt": "2026-03-18T12:00:00.000Z",
"updatedAt": "2026-03-18T12:00:00.000Z",
"transaction": {
"id": "880e8400-e29b-41d4-a716-446655440000",
"entryType": "debit",
"amount": 10000,
"description": "Pagamento fornecedor",
"endToEndId": null,
"availableAt": "2026-03-18T12:00:00.000Z",
"source": {
"type": "transfer",
"id": "770e8400-e29b-41d4-a716-446655440000"
},
"createdAt": "2026-03-18T12:00:00.000Z"
}
}
processing; o status final (completed ou failed) chega por webhook ou consultando Obter transferência. Campos em Referência.
Erros
| Status | Mensagem | Causa |
|---|---|---|
400 | Account is not active | Conta inativa ou sem dados bancários para Pix |
400 | Os dados da conta de origem e destino são iguais | Copia-e-cola da própria conta |
403 | — | Chave sem transfer.write, ou chave publicável |
404 | Account not found | Conta não encontrada |
422 | VALIDATION_FAILED | Corpo inválido (inclusive type: "beneficiary") |
500 | Transfer provider acceptance requires reconciliation | O provedor aceitou o Pix mas o registro local falhou. Confira o status em Listar transferências antes de enviar de novo |