Withdrawal Experience

The withdrawal flow is different from the deposit flow. This section documents user-facing flows, but the withdrawal experience remains partner-owned. In the current External API contract, POST /external/withdrawals does not return a hosted withdrawal URL to open for the user.

This is an intentional separation:

• The partner site backend opens the withdrawal request.
• The partner site collects the user's IBAN and holder name.
• The payout request is processed.
• The result is delivered to the partner site backend by webhook.

Flow

1. The user completes the withdrawal form on the partner site.
2. The partner backend runs fraud, balance, and business-rule checks.
3. The partner backend sends POST /external/withdrawals to Pientegra.
4. Pientegra returns withdrawalId and referenceNo.
5. The payout is processed.
6. Pientegra sends the result to the partner backend with a withdrawal.* webhook.
7. The partner site updates the user balance and withdrawal state.

Why there is no hosted withdrawal page

On the withdrawal side, the source of truth is usually the partner site's user account, KYC/fraud rules, and balance ledger. Keeping the user experience inside the partner site makes that ownership clear.

Pientegra's role is to receive the payout request, process it, and report the outcome with a signed webhook.

Partner UI recommendation

The partner site can show these states on the withdrawal screen:

Balance model selection

There are two safe models for withdrawals:

The pre-reserve model is more common in gaming and wallet systems because the user cannot open another withdrawal against the same balance. The right model still depends on the partner ledger design.

If a public hosted withdrawal confirmation flow is introduced in a future version, it will be documented as a separate integration model.