Pular para o conteúdo principal
POST
https://api.owem.com.br
/
v4
/
i
/
bank-accounts
/
{accountId}
/
transfer
/
external
Transferência Externa
curl --request POST \
  --url https://api.owem.com.br/v4/i/bank-accounts/{accountId}/transfer/external \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pixKey": "<string>",
  "amount": 123,
  "description": "<string>",
  "externalId": "<string>",
  "test": true,
  "testStatus": "<string>"
}
'
{
  "requestId": "a111b222-c333-4d44-8e55-f66677788899",
  "success": true,
  "size": 1,
  "data": {
    "metadata": {
      "idempotencyKey": "TX-202512241200-ABC123XYZ"
    },
    "type": "debit",
    "reason": "pix_out:processing",
    "status": "succeeded",
    "grossAmount": 125.75,
    "feeAmount": 0.08,
    "netAmount": 125.83,
    "externalId": "TX-20251224-EXEMPLO-001",
    "endToEndId": "E123456789202512240000000000001",
    "parentEndToEndId": null,
    "entryId": null,
    "requestId": "02000000-1111-2222-3333-444444444444",
    "userId": "usr_abc123def",
    "accountId": "123456789012",
    "createdAt": 1766523042000,
    "createdDate": "2025-12-24",
    "updatedAt": 1766523042000,
    "updatedDate": "2025-12-24",
    "payer": {
      "ispb": "12345678",
      "personType": "company",
      "cpfCnpj": "XX123456000XXX",
      "name": "EMPRESA EXEMPLO LTDA",
      "agency": "0001",
      "accountType": "checking",
      "accountNumber": "123456789012"
    },
    "receiver": {
      "ispb": "87654321",
      "personType": "company",
      "cpfCnpj": "XX654321000XXX",
      "name": "DESTINATARIO COMERCIAL LTDA",
      "agency": "0001",
      "accountType": "checking",
      "accountNumber": "765432"
    },
    "medId": null,
    "medCreatedAt": null,
    "medCreatedDate": null,
    "refundedEndToEndId": null,
    "errorMessage": null,
    "id": "E123456789202512240000000000001",
    "idempotencyKey": "debit:pix_out:processing:E123456789202512240000000000001"
  }
}

​
Finalidade

Envia valores de uma conta Owem para uma conta bancária externa via PIX. A API registra a operação na Ledger e retorna imediatamente o status inicial. Em caso de processing, a liquidação é assíncrona.

​
Autenticação

​
Authorization
string
obrigatório
Basic Auth obrigatório no formato: Basic {Base64(API_KEY:API_SECRET)}

​
Path Parameters

​
accountId
string
obrigatório
Conta de origem da transferência na Owem (12 dígitos)

​
Request Body

​
pixKey
string
obrigatório
Chave PIX de destino (telefone, e-mail, CPF/CNPJ ou chave aleatória)
​
amount
number
obrigatório
Valor em BRL (> 0, duas casas decimais)
​
description
string
Texto livre para identificação (máx. 140 caracteres)
​
externalId
string
Identificador único definido pelo cliente para idempotência
​
test
boolean
Define se é uma requisição de teste (não afeta saldo real)
​
testStatus
string
Status simulado quando test: true. Valores: processing, succeeded, failed

​
Resposta

​
requestId
string
UUID para rastreio
​
success
boolean
Status da operação
​
size
number
Quantidade de itens retornados
​
data
object
{
  "requestId": "a111b222-c333-4d44-8e55-f66677788899",
  "success": true,
  "size": 1,
  "data": {
    "metadata": {
      "idempotencyKey": "TX-202512241200-ABC123XYZ"
    },
    "type": "debit",
    "reason": "pix_out:processing",
    "status": "succeeded",
    "grossAmount": 125.75,
    "feeAmount": 0.08,
    "netAmount": 125.83,
    "externalId": "TX-20251224-EXEMPLO-001",
    "endToEndId": "E123456789202512240000000000001",
    "parentEndToEndId": null,
    "entryId": null,
    "requestId": "02000000-1111-2222-3333-444444444444",
    "userId": "usr_abc123def",
    "accountId": "123456789012",
    "createdAt": 1766523042000,
    "createdDate": "2025-12-24",
    "updatedAt": 1766523042000,
    "updatedDate": "2025-12-24",
    "payer": {
      "ispb": "12345678",
      "personType": "company",
      "cpfCnpj": "XX123456000XXX",
      "name": "EMPRESA EXEMPLO LTDA",
      "agency": "0001",
      "accountType": "checking",
      "accountNumber": "123456789012"
    },
    "receiver": {
      "ispb": "87654321",
      "personType": "company",
      "cpfCnpj": "XX654321000XXX",
      "name": "DESTINATARIO COMERCIAL LTDA",
      "agency": "0001",
      "accountType": "checking",
      "accountNumber": "765432"
    },
    "medId": null,
    "medCreatedAt": null,
    "medCreatedDate": null,
    "refundedEndToEndId": null,
    "errorMessage": null,
    "id": "E123456789202512240000000000001",
    "idempotencyKey": "debit:pix_out:processing:E123456789202512240000000000001"
  }
}

​
Códigos de Status

HTTPDescrição
200Transferência registrada
400Parâmetro inválido (pixKey, amount, etc.)
401Credenciais inválidas
403IP não allowlisted
404accountId não encontrado
422Saldo insuficiente ou limite excedido
429Rate limit excedido
500Erro interno

​
Status da Transferência

StatusDescrição
processingRegistrada, aguardando confirmação bancária
succeededTransferência confirmada
failedFalha (chave inválida, rejeição bancária)

​
Exemplo de Request

{
  "pixKey": "[email protected]",
  "amount": 125.75,
  "description": "Pagamento Fornecedor #123",
  "externalId": "TX-20251224-EXEMPLO-001"
}
Use externalId para garantir idempotência e rastreabilidade das operações.
Operações com test: true não afetam o saldo, não geram movimentação no Ledger e não disparam integração PIX real.