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
ClientId and 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
VALID or 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
The preauthorization feature allows you to reserve funds on a card so they can be captured later. It’s a two-step process:
- Preauthorize the funds to hold them for a defined period
- Make the capture of the funds before the end of the hold period
This guide focuses on the 7-day preauthorization feature.
Learn more about preauthorizations
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
{
"AuthorId": "user_m_01HWAR82HD4D8CQ67J02YMKM82",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 10000
},
"Billing": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Culture": "EN",
"CardId": "204068248",
"SecureModeReturnURL": "https://docs.mangopay.com/please-ignore",
"IpAddress": "036b:fb18:4568:4031:76a9:2aac:13c7:3cf0",
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": 60,
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
}
}
In the information returned, make sure you keep the Id of the Preauthorization for the next steps.
{
"Id": "205734378",
"Tag": null,
"CreationDate": 1696847591,
"AuthorId": "204068024",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 10000
},
"RemainingFunds": {
"Currency": "EUR",
"Amount": 10000
},
"AuthorizationDate": null,
"Status": "CREATED",
"PaymentStatus": "WAITING",
"ExpirationDate": null,
"PayInId": null,
"ResultCode": null,
"ResultMessage": null,
"SecureMode": "DEFAULT",
"CardId": "204068248",
"SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?preAuthorizationId=205734378",
"SecureModeRedirectURL": "https://api.sandbox.mangopay.com:443/Redirect/ACSWithoutValidation?token=1fd1781c9a404280acbb94fa48d40a3f&mgpsecureid=1fd1781c9a404280acbb94fa48d40a3f",
"SecureModeNeeded": true,
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"StatementDescriptor": null,
"Culture": "EN",
"SecurityInfo": {
"AVSResult": "NO_CHECK"
},
"MultiCapture": true,
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": 60,
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"IpAddress": "036b:fb18:4568:4031:76a9:2aac:13c7:3cf0",
"Billing": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Requested3DSVersion": null,
"Applied3DSVersion": "V2_1"
}
Redirect the user to 3DS protocol (if required)
Redirect the user to the SecureModeRedirectURL 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 Preauthorization PaymentStatus 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
Set up webhook notifications for the following 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
In the following calls, use the Id of the Preauthorization obtained previously as the PreauthorizationId.
Make a full capture
Use the Create a Preauthorized PayIn endpoint and make sure the Amount value of the DebitedFunds is equal to the preauthorized funds.
POST /v2.01/{ClientId}/payins/preauthorized/direct
{
"DebitedFunds": {
"Currency": "EUR",
"Amount": 10000
},
"Fees": {
"Currency": "EUR",
"Amount": 0
},
"CreditedWalletId": "204089031",
"PreauthorizationId": "205734378"
}
If the preauthorized pay-in is successful, the corresponding preauthorization is updated accordingly: it’s PaymentStatus changes to VALIDATED as there are no RemainingFunds left to be captured.
Use the View a Preauthorization endpoint to see this:
{
"Id": "205734378",
"Tag": null,
"CreationDate": 1696847591,
"AuthorId": "204068024",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 10000
},
"RemainingFunds": {
"Currency": "EUR",
"Amount": 0
},
"AuthorizationDate": 1696847611,
"Status": "SUCCEEDED",
"PaymentStatus": "VALIDATED",
"ExpirationDate": 1697409211,
"PayInId": "205736202",
"ResultCode": "000000",
"ResultMessage": "Success",
"SecureMode": "DEFAULT",
"CardId": "204068248",
"SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?preAuthorizationId=205734378",
"SecureModeRedirectURL": null,
"SecureModeNeeded": true,
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"StatementDescriptor": null,
"Culture": "EN",
"SecurityInfo": {
"AVSResult": "NO_CHECK"
},
"MultiCapture": true,
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": 60,
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"IpAddress": "036b:fb18:4568:4031:76a9:2aac:13c7:3cf0",
"Billing": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Requested3DSVersion": null,
"Applied3DSVersion": "V2_1"
}
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
{
"DebitedFunds": {
"Currency": "EUR",
"Amount": 500
},
"Fees": {
"Currency": "EUR",
"Amount": 0
},
"CreditedWalletId": "204089031",
"PreauthorizationId": "205734378"
}
If the preauthorized pay-in is successful, the corresponding preauthorization is updated accordingly:
- The
RemainingFunds equals the initial preauthorized funds minus de pay-in DebitedFunds and Fees.
- The
PaymentStatus remains as WAITING, allowing you to make another capture for the remaining funds.
You can View a Preauthorization to see these details.
API response - View a Preauthorization
{
"Id": "205734378",
"Tag": null,
"CreationDate": 1696847591,
"AuthorId": "204068024",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 5000
},
"RemainingFunds": {
"Currency": "EUR",
"Amount": 5000
},
"AuthorizationDate": 1696847611,
"Status": "SUCCEEDED",
"PaymentStatus": "WAITING",
"ExpirationDate": 1697409211,
"PayInId": "205736202",
"ResultCode": "000000",
"ResultMessage": "Success",
"SecureMode": "DEFAULT",
"CardId": "204068248",
"SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?preAuthorizationId=205734378",
"SecureModeRedirectURL": null,
"SecureModeNeeded": true,
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"StatementDescriptor": null,
"Culture": "EN",
"SecurityInfo": {
"AVSResult": "NO_CHECK"
},
"MultiCapture": true,
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": 60,
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"IpAddress": "036b:fb18:4568:4031:76a9:2aac:13c7:3cf0",
"Billing": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Alex",
"LastName": "Smith",
"Address": {
"AddressLine1": "6 rue de la Cité",
"AddressLine2": "Appartement 3",
"City": "Paris",
"Region": "Île-de-France",
"PostalCode": "75004",
"Country": "FR"
}
},
"Requested3DSVersion": null,
"Applied3DSVersion": "V2_1"
}
If the registered card 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
PaymentStatus changes to VALIDATED.
- If no capture was made, the Preauthorization’s
PaymentStatus changes to EXPIRED.
3. Release manually unused funds (recommended)
You can manually close the preauthorization hold period before the ExpirationDate 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 the PaymentStatus to VALIDATED.
PUT /v2.01/{ClientId}/preauthorizations/{PreauthorizationId}
{
"PaymentStatus": "VALIDATED"
}
Once this is done, no more captures can be made against the preauthorization.
Cancel an unused preauthorization
If no preauthorized pay-in has been made to capture the funds, you can release the remaining funds by changing the PaymentStatus to CANCELED.
PUT /v2.01/{ClientId}/preauthorizations/{PreauthorizationId}
{
"PaymentStatus": "CANCELED"
}
Once a preauthorization has been validated or canceled, no more captures can be made against it.
