PIX Cash Out Copier-Coller

Effectue un virement PIX en utilisant le code EMV (copier-coller) extrait d'un QR Code PIX.

Endpoint

POST /api/external/pix/cash-out

En-tetes

En-tete	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
Content-Type	String	Oui	application/json
hmac	String	Oui	Signature HMAC-SHA512 du body (hex)
Idempotency-Key	String	Non	Cle unique pour eviter le traitement en double (max 256 chars)

Request Body

Champ	Type	Obligatoire	Description
amount	Integer	Oui	Montant en centavos. R$ 30,00 = 3000
emv_code	String	Oui	Code EMV copier-coller du QR Code PIX
description	String	Non	Description du virement (max 140 caracteres)
external_id	String	Non	Identifiant de votre systeme pour le suivi. Max 128 chars. Uniquement a-zA-Z0-9._:-. Retourne dans les reponses et webhooks.

Code Copier-Coller

Le champ emv_code accepte le code EMV complet copie depuis un QR Code PIX. L'API extrait automatiquement la cle PIX, les donnees du beneficiaire et le montant original de la facturation a partir du payload EMV.

Montant du virement

Le champ amount doit etre renseigne meme lorsque le QR Code contient deja un montant. L'API valide que le montant indique est compatible avec le QR Code (statique ou dynamique).

Valeurs monetaires

Les valeurs d'entree sont en centavos (R$ 1,00 = 100). Les valeurs de reponse sont en unites de base (R$ 1,00 = 10000). Pour convertir la reponse en reais, divisez par 10 000. N'utilisez jamais de virgule flottante.

Exemple

curl -X POST https://api.owem.com.br/api/external/pix/cash-out \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d '{
    "amount": 3000,
    "emv_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR5913NOME RECEBEDOR6008BRASILIA62070503***6304ABCD",
    "description": "Pagamento via QR Code",
    "external_id": "invoice-4521"
  }'

Reponse de Succes -- 200

{
  "worked": true,
  "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603091530abcdef01",
  "external_id": "invoice-4521",
  "amount": 300000,
  "fee_amount": 350,
  "net_amount": 300350,
  "status": "processing",
  "detail": "PIX enviado para processamento"
}

Champ	Type	Description
worked	Boolean	true indique que la requete a ete acceptee
transaction_id	String	Identifiant unique de la transaction
end_to_end_id	String	Identifiant End-to-End dans le SPI/BACEN
external_id	String	Votre identifiant, retourne tel qu'envoye. null si non renseigne
amount	Integer	Montant du virement en unites de base (/ 10 000 pour reais). 300000 = R$ 30,00
fee_amount	Integer	Frais factures en unites de base (/ 10 000 pour reais)
net_amount	Integer	Montant net (amount + fee) en unites de base
status	String	processing (en liquidation) ou completed (liquide)
detail	String	Message descriptif

Reponse d'Erreur -- 400

{
  "worked": false,
  "detail": "Codigo EMV invalido ou nao reconhecido"
}

Reponse d'Erreur -- 422

{
  "worked": false,
  "detail": "Saldo insuficiente"
}

Prochaines Etapes

Apres avoir cree le virement, suivez le statut via :

• Consulter par ID
• Consulter par E2E ID
• Consulter par Tag
• Consulter par External ID -- GET /api/external/transactions/ref/{external_id}

Ou recevez la confirmation automatiquement via Webhook.