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
string
required
key ou hash.string
required
Só em
key. Chave Pix de destino.string
required
Só em
key. email, phone, cpf, cnpj ou random.integer
required
Só em
key. Valor em centavos, maior que zero.string
required
Só em
hash. BR Code (copia-e-cola).string
Até 140 caracteres.
string
Data do pagamento no formato
YYYY-MM-DD. Padrão: hoje.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 |