Ensure the Owner user is verified
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.Create the Payout request
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, 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 for more details.Handle the outcome
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
.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).Ensure the Owner user is verified
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.Check reachability of the payout
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: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:ResultCode
).INSTANT_PAYMENT
or INSTANT_PAYMENT_ONLY
. If this is not the case, then a duplicate transaction response (130008) is returned.Configure your fallback and initiate payout
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
.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.Handle the outcome
CREATED
. This triggers a webhook notification for the event type PAYOUT_NORMAL_CREATED
(regardless of the PayoutModeRequested
).An SCT Inst payout is usually processed within 10 seconds.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
– The ModeRequested
was INSTANT_PAYMENT
or INSTANT_PAYMENT_ONLY
and the payout could not be sent via SCT Inst scheme.ModeRequested
is INSTANT_PAYMENT
, 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.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.ModeRequested
was INSTANT_PAYMENT_ONLY
), then the payout returns a FAILED
status and ModeApplied
is NONE
.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
.ModeRequested
, ModeApplied
, and FallbackReason
given more information in case of fallback. The ResultCode
and ResultMessage
give more information in case of payout failure.Register the bank account (if not already registered)
RecipientScope
can be PAYIN
if the user is a PAYER
, as this type does not require SCA.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.Initiate the payout
PaymentRef
body parameter:ReasonType
value to PAYIN_REFUND
to indicate that the payout is serving as a refundId
of the initial pay-in as the ReferenceId
valuePaymentRef
object containing the PAYIN_REFUND
value and initial pay-in Id
as the ReferenceId
PAYIN_REFUND
payouts:
ReferenceId
value must be the Id
of a pay-in that was successful (it’s Status
is SUCCEEDED
)Fees
value can’t be negative, meaning that you can’t reimburse any fees taken on the initial bank wire pay-inId
PAYIN_REFUND
reference is returned, it follows the same process as other payouts.