Payloads des Webhooks
Exemples de payloads envoyes pour chaque type d'evenement. Tous les webhooks sont envoyes en HTTP POST avec Content-Type: application/json.
En-tetes de securite
Chaque notification inclut les en-tetes X-Owem-Signature (HMAC-SHA256), X-Owem-Timestamp, X-Owem-Event-Id et X-Owem-Event-Type. Consultez Webhooks — Vue d'ensemble pour les details de validation.
Reference des Statuts
Tous les evenements ne signifient pas que la transaction est terminee. Utilisez le tableau ci-dessous pour savoir quand les fonds ont ete effectivement regles.
| Evenement | Statut | Signification | Fonds regles ? |
|---|---|---|---|
pix.charge.created | created | QR code genere ou cash-in initie. En attente de paiement. | Non — juste cree |
pix.charge.paid | paid | PIX recu et regle sur le compte. Solde mis a jour, frais debites. | Oui |
pix.charge.expired | expired | QR code expire sans paiement. | N/A |
pix.charge.cancelled | cancelled | QR code annule avant paiement. | N/A |
pix.payout.processing | processing | PIX envoye, en attente de confirmation du destinataire. Solde reserve (hold). | Non — peut etre annule |
pix.payout.confirmed | settled | PIX envoye confirme par le destinataire. Debit definitif. | Oui |
pix.payout.failed | rejected | PIX envoye rejete par le destinataire. Hold libere, solde restaure. | Non |
pix.payout.returned | returned | PIX envoye retourne apres reglement. | Oui (inverse) |
pix.refund.requested | requested | Remboursement PIX demande (MED ou volontaire). Reserve creee. | Partiel |
pix.refund.completed | completed | Remboursement PIX complete et regle. Debit definitif. | Oui |
pix.return.received | received | Retour PIX recu (credit sur le compte). | Oui |
webhook.test | test | Evenement de test declenche manuellement. | N/A |
Regle : Pour la reconciliation financiere, seuls les statuts paid, settled, received ou completed sont definitifs. Tous les autres sont intermediaires.
Champs communs
Tous les payloads de webhook incluent ces champs :
| Champ | Type | Description |
|---|---|---|
event_type | string | Type d'evenement ayant declenche le webhook (ex : pix.charge.paid) |
status | string | Statut de l'operation — voir la Reference des Statuts |
account_id | integer | Numero de votre compte chez Owem |
entity_id | string (UUID) | Identifiant d'entite Owem |
Valeurs monetaires : Tous les montants sont en subcentavos (1 BRL = 10 000 subcentavos). Pour convertir en reais : montant / 10000. Exemple : 300000 / 10000 = R$ 30,00.
pix.charge.paid
Envoye quand un PIX est recu et regle sur le compte. C'est l'evenement qui confirme que l'argent est arrive.
Exemple — lie a un QR code
{
"event_type": "pix.charge.paid",
"status": "paid",
"account_id": 10014,
"amount": 300000,
"fee_amount": 400,
"end_to_end_id": "E9040088820260402095758709999671",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "u5f26sfyrq4plkw7tjwa",
"counterparty_name": "MARIA SANTOS",
"paid_at": "2026-04-02T09:58:05Z"
}Exemple — transfert direct (sans QR)
{
"event_type": "pix.charge.paid",
"status": "paid",
"account_id": 10014,
"amount": 300000,
"fee_amount": 400,
"end_to_end_id": "E9040088820260402095758709999671",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": null,
"counterparty_name": "JOAO SILVA",
"paid_at": "2026-04-02T10:15:22Z"
}| Champ | Type | Description |
|---|---|---|
event_type | string | Toujours pix.charge.paid |
status | string | Toujours paid |
account_id | integer | Numero de compte ayant recu le PIX |
amount | integer | Montant recu en subcentavos. 300000 = R$ 30,00 |
fee_amount | integer | Frais debites en subcentavos. 400 = R$ 0,04 |
end_to_end_id | string | Identifiant E2E du BACEN (unique par transaction PIX) |
entity_id | string (UUID) | Identifiant d'entite Owem |
tx_id | string ou null | ID de transaction. Present quand lie a un QR code. null pour les transferts directs |
counterparty_name | string ou null | Nom du payeur (expediteur) |
paid_at | string (ISO 8601) | Horodatage du reglement (UTC) |
pix.charge.created
Envoye quand un QR code est genere ou un cash-in est initie. Aucun mouvement financier n'a eu lieu.
{
"event_type": "pix.charge.created",
"status": "created",
"account_id": 10014,
"amount": 500000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "abc123def456ghi789"
}pix.payout.confirmed
Envoye quand un PIX envoye est confirme par l'institution destinataire. Debit definitif.
{
"event_type": "pix.payout.confirmed",
"status": "settled",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"pix_key": "destinataire@email.com",
"description": "Paiement fournisseur"
}pix.payout.processing
Envoye quand un PIX envoye est en cours de traitement. Le solde est reserve (hold) mais pas definitif.
{
"event_type": "pix.payout.processing",
"status": "processing",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}pix.payout.failed
Envoye quand un PIX envoye est rejete. Hold libere, solde restaure.
{
"event_type": "pix.payout.failed",
"status": "rejected",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"error_reason": "Compte destinataire introuvable"
}pix.refund.completed
Envoye quand un remboursement PIX est traite et complete.
{
"event_type": "pix.refund.completed",
"status": "completed",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"original_end_to_end_id": "E9040088820260402095758709999671",
"return_code": "MD06"
}pix.return.received
Envoye quand un retour PIX est recu (credit sur le compte).
{
"event_type": "pix.return.received",
"status": "received",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"return_e2e_id": "D9040088820260402111500000001",
"original_e2e_id": "E9040088820260402095758709999671",
"return_code": "MD06"
}webhook.test
Evenement de test declenche manuellement pour valider la configuration du webhook.
{
"event_type": "webhook.test",
"status": "test",
"account_id": 10014,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"message": "Webhook test event"
}Comment interpreter les webhooks
Pour confirmer que l'argent est arrive : Attendez pix.charge.paid avec status: "paid". C'est le seul evenement qui garantit que le montant a ete credite et les frais debites.
Pour confirmer que l'argent a ete envoye : Attendez pix.payout.confirmed avec status: "settled". Le statut processing est intermediaire — le solde est reserve mais peut etre annule si rejete.
Pour les retours : pix.return.received avec status: "received" confirme le credit sur le compte.
Deduplication : Utilisez l'en-tete X-Owem-Event-Id ou le champ end_to_end_id comme cle d'idempotence.