​
Initiate a payout

Mangopay’s e-wallet system allows users of the Owner category to hold funds in their wallets. To exceed the KYC/KYB limits of the platform’s contract, the Owner user must also be KYC/KYB verified. For most platforms, this means the user needs to be verified to request a payout.

The basic flow for initiating a payout are as follows:

1

Ensure the Owner user is verified

Check that the user’s KYCLevel is REGULAR to enable them to exceed the KYC/KYB limits.

For more about how to get a user verified, see the verification section.

2

Ensure the Recipient has the correct PayoutMethod

The payout rail used is determined by the Recipient’s PayoutMethod – read more.

You may need to register the user’s bank account again as another Recipient – read more.

3

Create the Payout request

Specifying the Recipient Id as the BankAccountId, initiate your payout request using the POST Create a 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, set the mode to RTGS_PAYMENT.

For SCT Inst, you are strongly recommended to check reachability beforehand, and you can choose to apply a fallback to SCT or not. See initiate an SCT Inst payout for more details.

4

Handle the outcome

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 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).

​
Initiate an SCT Inst payout

For local payouts in EUR, Mangopay offers a choice of payout routes

1

Ensure the Owner user is verified

Check that the user’s KYCLevel is REGULAR to enable them to exceed the KYC/KYB limits.

For more about how to get a user verified, see the verification section.

2

Ensure the Recipient has the correct PayoutMethod

The payout rail used is determined by the Recipient’s PayoutMethod – read more.

You may need to register the user’s bank account again as another Recipient – read more.

3

Check reachability of the payout

Before initiating an instant payout request, you should always check the eligibility of the receiving bank and your payout request using the dedicated endpoint:

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:

{
    "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 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) is returned.
4

Configure your fallback and initiate payout

Mangopay offers a fallback to standard processing via the SEPA Credit Transfer scheme which your platform can choose to apply or not.

On a request to POST Create a 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.
  • 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 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 value is set.

5

Handle the outcome

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).

An SCT Inst payout usually succeeds in 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 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 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, then an SCT payout is being attempted instead and the Status stays as CREATED. SCT payouts are usually processed the same business day and arrive the following day.

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 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), 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 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.

​
Refunds using payouts

A Refund object cannot be created to reimburse the initial pay-in on two payment methods:

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

1

Register the bank account (if not already registered)

Create the Recipient or Bank Account object needed for a payout.

If using recipients, 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). 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.

2

Initiate the payout

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. 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 endpoint, shows the PaymentRef object containing the PAYIN_REFUND value and initial pay-in Id as the ReferenceId

PAYIN_REFUND
{
    "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.

Endpoint

POST Create a Payout

Endpoint

GET View Payout and check mode applied