> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate payout flows
## Initiate a payout
Mangopay's e-wallet system allows users of the Owner [category](/guides/users/categories) to hold funds in their wallets. To exceed the [KYC/KYB limits](/guides/users/limits) of the platform’s contract, the Owner user must also be [KYC/KYB verified](/guides/users/verification). For most platforms, this means the user needs to be verified to request a payout.
The basic flow for initiating a payout is as follows:
Check that the user's `KYCLevel` is `REGULAR` to enable them to exceed the [KYC/KYB limits](/guides/users/limits).
For more about how to get a user verified, see the [verification](/guides/users/verification) section.
The payout rail used is determined by the Recipient's `PayoutMethod` – [read more](/guides/payouts#how-mangopay-routes-funds).
You may need to register the user's bank account again as another Recipient – [read more](/guides/sca/recipients#how-to-register-a-recipient-for-payouts).
Specifying the Recipient `Id` as the `BankAccountId`, initiate your payout request using the [POST Create a Payout](/api-reference/payouts/create-payout) endpoint.
If the payout is in EUR, platforms can choose between SCT, SCT Inst, and T2 payout rails. Your choice must be specified in the `PayoutModeRequested` parameter of the request.
For T2 ([RTGS](/guides/payouts#real-time-gross-settlement-rtgs)), set the mode to `RTGS_PAYMENT`.
For SCT Inst, until acceptance is more widely supported, you are strongly recommended to check reachability beforehand. On the payout, you can choose to apply a fallback to SCT or not. See [initiate an SCT Inst payout](#initiate-an-sct-inst-payout) for more details.
Once the payout request is successfully initiated, its status becomes `CREATED`. This triggers a webhook notification for the event type `PAYOUT_NORMAL_CREATED` (regardless of the `PayoutModeRequested`).
You should set up hook notifications for the other payout event types to be notified of its progress:
* `PAYOUT_NORMAL_SUCCEEDED` – The payout is ready to be instructed by one of our providers and the wallet was debited. The payout `Status` changed to `SUCCEEDED`.
* `PAYOUT_NORMAL_FAILED` – The payout request was not created in Mangopay’s system or was created then failed for other reasons (rejection due to invalid data, rejection for compliance or fraud reasons, rejection by the clearing system or by the recipient bank, etc). The payout `Status` changed to `FAILED`.
The `SUCCEEDED` status indicates that Mangopay successfully processed the payout and sent the funds. There are some cases where the funds are returned by the receiving bank and Mangopay creates a payout refund (see [rejects and returns](/guides/payouts/rejects-returns)).
## Initiate an SCT Inst payout
For local payouts in EUR, Mangopay offers a choice of payout routes.
For SEPA Instant Credit Transfer (SCT Inst), the flow is slightly different:
Check that the user's `KYCLevel` is `REGULAR` to enable them to exceed the [KYC/KYB limits](/guides/users/limits).
For more about how to get a user verified, see the [verification](/guides/users/verification) section.
The payout rail used is determined by the Recipient's `PayoutMethod` – [read more](/guides/payouts#how-mangopay-routes-funds).
You may need to register the user's bank account again as another Recipient – [read more](/guides/sca/recipients#how-to-register-a-recipient-for-payouts).
Before initiating an instant payout request, we recommend you check the eligibility of the receiving bank and your payout request using the dedicated endpoint:
* [POST Check Instant Payout eligibility](/api-reference/payouts/check-instant-payout-eligibility)
In your request, set the `PayoutModeRequested` to `INSTANT_PAYMENT` and provide the same transaction amounts are other details that you intend to use for the payout.
As well as the reachability of the bank account, the other fields are also verified, meaning that you can check, for example, that there are sufficient funds in the wallet and that the user is not blocked.
The following response means that you can proceed with the payout request:
```json theme={null}
{
"InstantPayout": {
"IsReachable": true,
"UnreachableReason": null
}
}
```
Issues are returned in the `UnreachableReason` object.
There are two specific prerequisites that must be met for an SCT Inst request to be made. If not met, they can trigger a fallback (if requested) or failure:
1. **Receiving bank is reachable**, which you should check before making the request (see below). If this is not the case, an unreachability error is returned (either as a 400 HTTP response or the [130007](/errors/codes/130007) `ResultCode` ).
2. **No other instant payout request for the exact same amount and bank account has been made in the last 24 hours**, whether made with `INSTANT_PAYMENT` or `INSTANT_PAYMENT_ONLY`. If this is not the case, then a duplicate transaction response ([130008](/errors/codes/130008)) is returned.
The SCT Inst request must also for an amount below the threshold agreed with Mangopay, but limit is not reflected in the reachability endpoint – contact Mangopay via the Dashboard for details.
Mangopay offers a fallback to standard processing via the SEPA Credit Transfer (SCT) scheme which your platform can choose to apply or not.
On a request to [POST Create a Payout](/api-reference/payouts/create-payout), the `PayoutModeRequested` property allows you to choose the desired value:
* `INSTANT_PAYMENT` – Request via SCT Inst with a fallback to a `STANDARD` mode (SCT) request if an unmet prerequisite or other issue means the SCT Inst could not be made. An issue with the `STANDARD` mode request may still arise. If the payout is above the threshold agreed with Mangopay, the payout fails and there is no fallback.
* `INSTANT_PAYMENT_ONLY` – Request via SCT Inst without a fallback, meaning that if an unmet criteria or other issue arises, the funds are not debited from the wallet and the payout `Status` changes to `FAILED`.
In response to the [POST Create a Payout](/api-reference/payouts/create-payout) endpoint, for either of the instant payment `PayoutModeRequested` values above, the `ModeRequested` value is `INSTANT_PAYMENT`.
The `ModeApplied` field indicates the mode ultimately applied to the request, but in the API response the temporary value `PENDING_RESPONSE` is set.
Once the payout request is successfully initiated, its status becomes `CREATED`. This triggers a [webhook notification](/webhooks) for the event type `PAYOUT_NORMAL_CREATED` (regardless of the `PayoutModeRequested`).
An SCT Inst payout is usually processed within 10 seconds.
##### Success
A successful outcome is indicated by two webhook event types, which are both sent for SCT Inst:
* `INSTANT_PAYOUT_SUCCEEDED` – The payout is ready to be instructed by one of our providers and the wallet was debited. The `ModeRequested` was `INSTANT_PAYMENT` or `INSTANT_PAYMENT_ONLY` and the payout was sent via SCT Inst. The `Status` changed to `SUCCEEDED` and `ModeApplied` is `INSTANT_PAYMENT`.
* `PAYOUT_NORMAL_SUCCEEDED` – The payout is ready to be instructed by one of our providers and the wallet was debited. The payout `Status` changed to `SUCCEEDED`.
##### Instant payout failed
If the instant payout attempt fails, then the following webhook is triggered:
* `INSTANT_PAYOUT_FAILED` – The `ModeRequested` was `INSTANT_PAYMENT` or `INSTANT_PAYMENT_ONLY` and the payout could not be sent via SCT Inst scheme.
If the instant payout attempt fails, then there are two possibilities depending on whether the fallback was requested or not: fallback, or no fallback
##### Fallback
If `ModeRequested` is `INSTANT_PAYMENT`, and the payout amount was below the threshold agreed with Mangopay, then an SCT payout is being attempted instead and the `Status` stays as `CREATED`.
A fallback triggers a webhook notification for the event type:
* `INSTANT_PAYOUT_FALLBACKED` – The `ModeRequested` was `INSTANT_PAYMENT` but the request could not be made using the SCT Inst scheme, so the request was initiated using the SCT scheme instead.
Call the [GET View a Payout and check mode applied](/api-reference/payouts/view-payout-check-mode-applied) endpoint to retrieve more information. The `ModeApplied` is `STANDARD` and the `FallbackReason` contains information about why the fallback occurred.
Note that even if the payout is attempted via SCT, it can still fail for the same reasons as other SCT payouts.
##### No fallback – payout failed
If the fallback was not requested (`ModeRequested` was `INSTANT_PAYMENT_ONLY`), or if it was requested for an amount above the threshold agreed with Mangopay, then the payout returns a `FAILED` status and `ModeApplied` is `NONE`.
##### Payout failed
For all payouts, regardless of the `ModeRequested`, when the `Status` changes to `FAILED` it triggers the webhook:
* `PAYOUT_NORMAL_FAILED` – The payout request was not created in Mangopay’s system or was created then failed for other reasons (rejection due to invalid data, rejection for compliance or fraud reasons, rejection by the clearing system or by the recipient bank, etc). The payout `Status` changed to `FAILED`.
Once you receive the notification, call the [GET View a Payout and check mode applied](/api-reference/payouts/view-payout-check-mode-applied) endpoint to retrieve more information. The properties `ModeRequested`, `ModeApplied`, and `FallbackReason` given more information in case of fallback. The `ResultCode` and `ResultMessage` give more information in case of payout failure.
If the instant payout request exceeded the threshold agreed with Mangopay, then the result code and message are [008500](/errors/codes/008500) – `Transaction blocked by Fraud policy`. In this case the payout must be retried in `STANDARD` mode.
## Refunds using payouts
A [Refund](/api-reference/refunds/refund-object) object cannot be created to reimburse the initial pay-in on two [payment methods](/guides/payment-methods):
* [Bank wire pay-in](/api-reference/bank-wire-payins/bank-wire-payin-object)
* [Pay-in to virtual IBAN](/api-reference/virtual-accounts/external-instruction-bank-wire-payin-object)
In these cases, a payout must be used instead, as described below.
**Note – Refunds using payouts via the Dashboard**
The Mangopay Dashboard allows you to initiate refunds using payouts for bank wire and virtual IBAN pay-ins. To do so, use the ***Refund*** button on the pay-in details screen.
### Initiate a refund using a payout via API
Create the [Recipient](/api-reference/recipients/recipient-object) needed for a payout. The `RecipientScope` can be `PAYIN` if the user is a `PAYER`, as this type does not require SCA.
**Caution – Account number must match pay-in**
The destination bank account registered for the payout must be the same as the one debited during the pay-in (the account numbers must match).
For a pay-in to virtual IBAN, the account number is returned in the `DebitedBankAccount` when you call [GET View a PayIn (External Instruction)](/api-reference/virtual-accounts/view-payin-external-instruction). For a bank wire pay-in, the account number may be available in the returned `TransactionDetails`. Otherwise, you need to obtain the correct account number from the user.
For the payout to be correctly processed as a reimbursement, you must reference the initial transaction in the payout request.
Request the payout by calling [POST Create a Payout](/api-reference/payouts/create-payout). In your request, use the `PaymentRef` body parameter:
* Set the `ReasonType` value to `PAYIN_REFUND` to indicate that the payout is serving as a refund
* Provide the `Id` of the initial pay-in as the `ReferenceId` value
A full example request is provided below.
### Example API request
The payout request body below, to the [POST Create a Payout](/api-reference/payouts/create-payout) endpoint, shows the `PaymentRef` object containing the `PAYIN_REFUND` value and initial pay-in `Id` as the `ReferenceId`
```json PAYIN_REFUND {15-17} theme={null}
{
"AuthorId": "user_m_01JCQYJNHFPENP1SKTCBYER0F8",
"Tag": "Created using Mangopay API Postman Collection",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 24581
},
"Fees": {
"Currency": "EUR",
"Amount": 0
},
"DebitedWalletId": "wlt_m_01J9KR4A7BH8KVE4PG6DTNS817",
"BankAccountId": "bankacc_m_01JCN1X2EHWG0JNJNPNQ21CW5G",
"BankWireRef": "Example123",
"PaymentRef": {
"ReasonType": "PAYIN_REFUND",
"ReferenceId": "payin_m_01JCR21X56KVHF7F5TVGYNT9G7"
}
}
```
### Conditions and possibilities
Note the following conditions and possibilities for `PAYIN_REFUND` payouts:
* The `ReferenceId` value must be the `Id` of a pay-in that was successful (it's `Status` is `SUCCEEDED`)
* The `Fees` value can't be negative, meaning that you can't reimburse any fees taken on the initial bank wire pay-in
* You can create multiple payouts that reference the same pay-in `Id`
If a payout containing a `PAYIN_REFUND` reference is returned, it follows the same process as other payouts.
## Related resources
POST Create a Payout
GET View Payout and check mode applied