Introduction
This how-to guide will show you how to preauthorize funds on a card for 7 days and then debit the payment.Prerequisites
- A
ClientIdand an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard - A User object created for your end user, and their associated Wallet
- A registered card (CB, Visa, or Mastercard), which is
VALIDor registered less than 24 hours ago, to make the payments - The URL of a page on your platform to return the end user to after authentication
- Preauthorize the funds to hold them for a defined period
- Make the capture of the funds before the end of the hold period
1. Secure the funds
Create a preauthorization to request to hold funds for 7 days.Make the request
POST /v2.01/{ClientId}/preauthorizations/card/direct
Id of the Preauthorization for the next steps.
API response
Redirect the user to 3DS protocol (if required)
Redirect the user to theSecureModeRedirectURL value to complete strong customer authentication, unless it is null. If SecureModeRedirectURL is null, this means that 3DS is not required and no redirection is needed.
You can also use the SecureModeNeeded boolean to determine this redirection behavior.
For more information on how to handle 3DS redirection, see Steps 4, 6, and 7 of the How to process a card payment guide.
2. Capture the funds
Once the PreauthorizationPaymentStatus is WAITING, you can capture the funds with a preauthorized pay-in.
The preauthorized pay-in must be:
- For an amount equal to or less than the preauthorized amount (full or partial capture)
- Done within 6.5 days of a successful authorization
EventType in order to be notified when it is possible or too late to make a pay-in against a preauthorization:
- PREAUTHORIZATION_PAYMENT_WAITING
- PREAUTHORIZATION_PAYMENT_EXPIRED
Id of the Preauthorization obtained previously as the PreauthorizationId.
Make a full capture
Use the Create a Preauthorized PayIn endpoint and make sure theAmount value of the DebitedFunds is equal to the preauthorized funds.
POST /v2.01/{ClientId}/payins/preauthorized/direct
PaymentStatus changes to VALIDATED as there are no RemainingFunds left to be captured.
Use the View a Preauthorization endpoint to see this:
API response
Make a partial capture
Use the Create a Preauthorized PayIn endpoint and specify the portion of the preauthorized funds you want to capture.POST /v2.01/{ClientId}/payins/preauthorized/direct
- The
RemainingFundsequals the initial preauthorized funds minus de pay-inDebitedFundsandFees. - The
PaymentStatusremains asWAITING, allowing you to make another capture for the remaining funds.
API response - View a Preauthorization
CardType is CB_VISA_MASTERCARD, you can make as many partial captures as needed until you reach the preauthorized amount.
If you know that you won’t use the remaining preauthorized funds before the end of the hold period, you can release the funds manually to free them for the user (see Step 3).
Once the hold period is over:
- If at least one capture was made, the Preauthorization’s
PaymentStatuschanges toVALIDATED. - If no capture was made, the Preauthorization’s
PaymentStatuschanges toEXPIRED.
3. Release manually unused funds (recommended)
You can manually close the preauthorization hold period before theExpirationDate to release the preauthorized funds for the user. If you don’t do this, the funds will be released at the ExpirationDate
Validate a partially used preauthorization
If at least one preauthorized pay-in has been made to capture funds (partial capture), you can release the remaining preauthorized funds by changing thePaymentStatus to VALIDATED.
PUT /v2.01/{ClientId}/preauthorizations/{PreauthorizationId}
Cancel an unused preauthorization
If no preauthorized pay-in has been made to capture the funds, you can release the remaining funds by changing thePaymentStatus to CANCELED.
PUT /v2.01/{ClientId}/preauthorizations/{PreauthorizationId}