Sipay Business Api
English
  • Turkish
  • English
English
  • Turkish
  • English
English
  • Turkish
  • English
  1. Webhook
  • Overview
    • Sipay Business API
    • Partner Wallet Flow Guide
  • Authentication
    • Get Access Token
      POST
  • Account
    • Get Business Account
      POST
    • Check Personal Wallet (AccountNumber)
      POST
    • Check Personal Wallet (PhoneNumber)
      POST
  • Wallet
    • Create Wallet For Business Account
      POST
    • Wallet Info
      POST
    • Wallet List By Filter
      POST
  • Transaction
    • Business To Personal Transfer
      POST
    • Business To Business Transfer
      POST
    • Send Money To Bank Account
      POST
    • Transfer To Virement
      POST
    • Get Payment Types
      GET
  • Transaction Data
    • Transaction Type Code List
    • How to payout status check?
    • Summary Record By Filter
      POST
    • Get Request Withdraw List By Filter
      POST
    • Get Request Withdraw By Ext Id
      POST
    • Transaction Receipt
      POST
  • Webhook
    • Bank Transfer Webhook
    • Top-up Webhook
    • Failed Top-Up Webhook
  1. Webhook

Bank Transfer Webhook

Bank Transfer Webhook
Payout instructions created through POST /v1/Transaction/SendMoneyToBankAccount can be reported through asynchronous webhook notifications.

Webhook types#

Two separate webhook events are available for bank withdrawals:
EventDescription
WithdrawalTransferResultReports payout results such as completion, failure, cancellation, and refund using the dedicated payload documented on this page.
WithdrawCompletedSends the standard SummaryRecord payload only for successfully completed payouts.
These events are configured separately. Enabling WithdrawalTransferResult does not automatically enable WithdrawCompleted. If both events are enabled, a successful payout may generate two separate webhook notifications.
The remainder of this page documents the WithdrawalTransferResult webhook payload. The SummaryRecord payload is not the payload of this webhook.

Successful transaction webhook#

When a payout is successfully completed by the bank, a webhook with the following structure is sent:
{
  "tenant_id": 5,
  "amount": 25,
  "currency_code": "TRY",
  "ext_transaction_id": "EXT-EXAMPLE-001",
  "request_withdraw_id": 2610095975284361006,
  "transaction_id": 2610099713036521748,
  "account_type_id": 1,
  "account_number": "12345678",
  "wallet_number": "87654321",
  "before_process_status": 0,
  "after_process_status": 1,
  "money_transfer_state": 0,
  "money_transfer_type": 3,
  "to_iban": "TR000000000000000000000000",
  "response_status": 0,
  "response_code": "100",
  "response_message": "İşlem başarılı",
  "transaction_type": "A01",
  "to_name": "EXAMPLE USER",
  "reason": ""
}
The following values together indicate a successfully completed payout:
money_transfer_state = 0
after_process_status = 1
transaction_id > 0
In the standard Pending → Completed flow, before_process_status = 0. The previous status may be different if the payout was completed following operational processing.

Outcome mappings#

The financial outcome should be determined by evaluating money_transfer_state, before_process_status, after_process_status, and transaction_id together.
Outcomemoney_transfer_statebefore_process_statusafter_process_statusDescription
Completed0Usually 0 or 31The payout is completed and transaction_id should be greater than zero.
Provider failure / operational processing1Usually 03Not financially final; the payout may later become Completed or Rejected/Cancelled.
Cancelled4Usually 0 or 32The instruction is cancelled and there is no outstanding fund-out.
Refund after completion512A previously completed payout was refunded by the bank.
after_process_status = 5 does not indicate a refund. It represents the ClosedManually status.

Duplicate Completed notification#

The same Completed notification may be received again after the payout has already been processed. Such a notification may contain:
before_process_status = 1
after_process_status = 1
money_transfer_state = 0
response_status = 2
response_code = "312"
This is not a new financial failure. It is an idempotent duplicate indicating that the payout was already completed and must not trigger another financial action.

Failed transaction scenarios#

API request is not accepted#

If SendMoneyToBankAccount rejects the request before the payout instruction is accepted, no webhook is generated. For example:
{
  "status": 2,
  "code": "311",
  "message": "Cüzdan bakiyeniz yetersiz olduğundan işlemi gerçekleştiremiyoruz"
}

Provider reports the transfer as Failed#

money_transfer_state = 1
after_process_status = 3
This state is not financially final. The payout may later transition to Completed or Rejected/Cancelled following operational processing. Use GetRequestWithdrawByExtId to track the current status.

Provider cancels the transfer#

money_transfer_state = 4
after_process_status = 2
This combination indicates that the payout instruction was cancelled and there is no outstanding fund-out.

Refund after a successful payout#

If the bank refunds a previously completed payout, a new webhook is sent for the same ext_transaction_id:
money_transfer_state = 5
before_process_status = 1
after_process_status = 2
transaction_id > 0
The refund notification must not be discarded as a duplicate of the earlier Completed notification.

Manual or operational processing#

Entering manual review does not itself generate a webhook. During this stage, GetRequestWithdrawByExtId may return:
process_level_status = 3
This state is not financially final. The payout may later become Completed or Rejected/Cancelled. If the provider also reports a Failed result, a WithdrawalTransferResult webhook with money_transfer_state = 1 and after_process_status = 3 may be received.

response_* fields#

response_status, response_code, and response_message describe how the provider notification was processed by the platform. They do not directly represent the provider's financial outcome.
The financial result must not be determined from these fields alone. The following fields should be evaluated together:
money_transfer_state
before_process_status
after_process_status
transaction_id

Delayed or missing webhook#

The primary notification is the WithdrawalTransferResult webhook. If the webhook is not received, the result is ambiguous, or reconciliation is required, use the following service with the same ext_transaction_id:
process_level_status values:
ValueStatusDescription
0PendingProcessing continues; not financially final.
1CompletedThe payout is completed. A separate refund notification may still arrive later.
2RejectedThere is no outstanding fund-out. It may represent an initial rejection/cancellation or a later refund.
3Failed / Operational ProcessingNot financially final; continue checking the status.
4CancelledThe payout is cancelled and there is no outstanding fund-out.
5ClosedManuallyDoes not determine the financial outcome by itself; operations/support confirmation is required.
process_level_status = 3 is not a terminal state.

Reporting and reconciliation#

The standard record of a completed transaction can optionally be queried through:
This service is intended for reporting, audit, and reconciliation. It must not be used to determine the status of an open or in-flight payout.

Delivery and idempotency#

Webhooks are sent asynchronously and delivery order is not guaranteed.
Any HTTP 2xx response acknowledges successful receipt.
Do not deduplicate webhook deliveries by ext_transaction_id alone. A successful payout and a later refund use the same ext_transaction_id.
An idempotency combination such as the following can be used:
ext_transaction_id
+ money_transfer_state
+ after_process_status
+ transaction_id
A repeated Completed notification must not trigger another financial action.
A later Refunded notification must still be processed.
A delayed Completed notification must not overwrite an already processed Refunded result.
Previous
Transaction Receipt
Next
Top-up Webhook
Built with