MagenMagen Docs
教程

内部转账

POSTPOST /internal-transferGETGET /internal-transfer幂等性Webhooks

使用场景

  • 同一业务实体下不同账户之间的划转（总部/分部）
  • 向同为 Magen 客户的合作伙伴付款
  • 内部余额调拨（钱包、运营子账户）

创建转账

您需要付款方和收款方双方的 accountNumber（6 位数字）。付款方必须与 token 认证的账户一致。

curl -X POST https://api.magen.processamento.com/v1/internal-transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payerAccountNumber": "513579",
    "receiverAccountNumber": "987654",
    "amount": 100.50,
    "description": "Pagamento referente a fatura #1234",
    "callbackUrl": "https://seusite.com.br/webhooks/magen",
    "clientReference": "transfer-abc-123"
  }'
const res = await fetch('https://api.magen.processamento.com/v1/internal-transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAGEN_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payerAccountNumber: '513579',
    receiverAccountNumber: '987654',
    amount: 100.50,
    description: 'Pagamento referente a fatura #1234',
    callbackUrl: 'https://seusite.com.br/webhooks/magen',
    clientReference: 'transfer-abc-123',
  }),
});
res = requests.post(
    'https://api.magen.processamento.com/v1/internal-transfer',
    headers={
        'Authorization': f'Bearer {os.environ["MAGEN_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        'payerAccountNumber': '513579',
        'receiverAccountNumber': '987654',
        'amount': 100.50,
        'description': 'Pagamento referente a fatura #1234',
        'callbackUrl': 'https://seusite.com.br/webhooks/magen',
        'clientReference': 'transfer-abc-123',
    },
)

字段说明

字段类型是否必填说明
payerAccountNumberstring是付款账户（6 位数字）。必须与 token 一致。
receiverAccountNumberstring是收款账户（6 位数字）。
amountnumber是金额（BRL）。最低 R$ 0,01。
descriptionstring否自由文本，最多 140 个字符。
callbackUrlstring否接收状态更新的 URL。
clientReferencestring否外部标识符（幂等性）。最多 64 字符。
virtualAccountstring否虚拟子账户（多租户）。最多 50 字符。

完整 schema 见 POST /internal-transfer。

查询

支持 id、clientReference 或 virtualAccount（仅使用其中一个）。

curl "https://api.magen.processamento.com/v1/internal-transfer?clientReference=transfer-abc-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

与 Pix 提现的差异

维度内部转账Pix 提现 (/withdraw)
目的地Magen 账户任意银行/账户
费率按账户费率表按费率表
清算即时Pix 秒级到账
标识符accountNumber（6 位数字）Pix 密钥或 QR Code

收款账户的 accountNumber 由 Magen 合作伙伴提供。平台不公开账户目录。

Enviar Pix

Dois caminhos para enviar Pix da sua conta Magen para um destinatário externo. Saque por chave Pix (com validação DICT) ou pagar QR Code. Inclui acompanhamento de status e download de comprovante.

Conciliação

Mesmo com callbacks confiáveis, todo sistema sério bate as transações da Magen com o banco interno diariamente. Aqui você aprende a listar transações em tempo real, gerar relatórios assíncronos para janelas grandes e usar clientReference para fechar o ciclo.

On this page

使用场景创建转账字段说明查询与 Pix 提现的差异