✅ Successful Transaction Webhook#
We configure the Bank Transfer Webhook for payouts, which notifies you when funds are transferred to the bank.
For payins, we use the Top-Up Webhook, sending notifications to your provided URLs whenever money is loaded into your accounts.
successfully and the transaction is also successfully completed by the bank,
the webhook will be sent as shown below:{
"tenant_id": 5,
"amount": 50,
"currency_code": "TRY",
"ext_transaction_id": "54171323223317131311333332552",
"request_withdraw_id": 2505267108142371608,
"transaction_id": 2505266701488343592,
"account_type_id": 2,
"account_number": "12345678",
"wallet_number": "23456789",
"before_process_status": 1,
"after_process_status": 1,
"money_transfer_state": 0,
"money_transfer_type": 3,
"to_iban": "TR000000000000000000000000",
"response_status": 2,
"response_code": "312",
"response_message": "Bu işlem daha önce başarıyla gerçekleştirilmiştir.",
"transaction_type": "A01",
"to_name": "Fxxxx",
"reason": "Basarili"
}
after_process_status = 1 and transaction_id > 0 → This means the transaction was successfully completed.
However, in rare cases, the bank may refund the transaction. In such
cases:A webhook is sent with after_process_status = 5. This indicates a refund, not a failure.
❌ Failed Transaciton Scenarios#
If the API returns an error (e.g., due to insufficient balance), no webhook is sent.
Example error:
{ "status": 2, "code": "311", "message": "Cüzdan bakiyeniz yetersiz olduğundan işlemi gerçekleştiremiyoruz" }
2.
If the API Call Succeeds But the Bank Rejects the Transaction:
after_process_status = 2 or 4.
A webhook is sent, but the transaction is considered failed.
{
"tenant_id": 5,
"amount": 50,
"currency_code": "TRY",
"ext_transaction_id": "54171323223317131311333332552",
"request_withdraw_id": 2505267108142371608,
"transaction_id": 2505266701488343592,
"account_type_id": 2,
"account_number": "12345678",
"wallet_number": "23456789",
"before_process_status": 1,
"after_process_status": 2,
"money_transfer_state": 0,
"money_transfer_type": 3,
"to_iban": "TR000000000000000000000000",
"response_status": 2,
"response_code": "312",
"response_message": "Bu işlem daha önce başarıyla gerçekleştirilmiştir.",
"transaction_type": "A01",
"to_name": "Fxxx",
"reason": "Basarili"
}
⚠️ Manuel Approval Process (Operational Status)#
If the transaction falls into manual operation, no webhook will be sent.After_process_status will be 3.
He operations team will manually approve the transaction; to track it, a request should be made to the GetRequestWithdrawByExtId service using the ext_transaction_id.
This scenario typically occurs in cases that require manual intervention, such as mismatches between the IBAN and the name-surname.
📌 Important Notes#
Webhooks are always sent asynchronously
For guaranteed confirmation, also check the transaction status via GetRequestWithdrawByExtId.
🔁 Webhook Delayed or Missing? Secondary Check#
Primary signal: Successful Transaction WebhookFallback: Poll by your own ext_transaction_id.When to use: If you don’t receive the webhook within your retry window (e.g., 60–90s) or your system couldn’t process it.1.
Keep your ext_transaction_id when calling POST /v1/Transaction/SendMoneyToBankAccount.
2.
Poll the withdraw status by ext_transaction_id:POST /v1/TransactionData/GetRequestWithdrawByExtId
Check process_level_status:1 = Completed (funds sent — treat as fund-out)
Stop polling when you reach a terminal state (1/2/3). Treat 1 as confirmed fund-out.
3.
(Optional) Verify the final ledger record for audit:POST /v1/TransactionData/SummaryRecordByFilter with your ext_transaction_id
Use transaction_status_id where 20 = Completed and log completed_date_utc as the completion timestamp.
Note: This endpoint lists settled/posted transactions; don’t use it for open/pending ones.
If a payout falls into manual approval (operational review), no webhook is sent during this stage.
You must poll GetRequestWithdrawByExtId until it transitions to a terminal state.
Typical trigger example: IBAN vs. name-surname mismatches.
Use exponential backoff (e.g., 2s → 4s → 8s … up to a sane cap).
Dedupe by ext_transaction_id in case a delayed webhook arrives later.
Persist the final state you obtained first (Completed/Rejected/Failed) and treat subsequent signals idempotently.
