How to process a 30-day card preauthorization
Introduction
This how-to guide will show you how to preauthorize funds on a card for 30 days and then debit the payment. The 30-day preauthorization feature gives flexibility for several use cases, and this guide shows you each of them.
Learn more about deposit preauthorizations →
Prerequisites
- A
ClientIdand an API key – if you don’t have these, contact Sales to get access to the Mangopay Hub - 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
1. Secure the funds
Create a deposit preauthorization to hold funds for 30 days.
Make the request
POST /v2.01/{ClientId}/deposit-preauthorizations/card/direct
In the information returned, retain the Id of the Deposit Preauthorization for the next steps.
{
"Id": "524a7e9c-cad9-4df7-9fe3-03b8948930fe",
"CreationDate": 1669137219,
"ExpirationDate": 1671729219,
"AuthorId": "156671912",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 500
},
"Status": "CREATED",
"PaymentStatus": "WAITING",
"PayinsLinked": {
"PayinCaptureId": null,
"PayinComplementId": null
},
"ResultCode": null,
"ResultMessage": null,
"CardId": "156674899",
"PreferredCardNetwork": null,
"SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?depositId=524a7e9c-cad9-4df7-9fe3-03b8948930fe",
"SecureModeRedirectURL": "https://api.sandbox.mangopay.com/deposit-preauthorizations/Acs/Redirect?secureSessionToken=8bf75b26-01c1-4745-8f82-727e8a047dcb",
"SecureModeNeeded": true,
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"StatementDescriptor": null,
"Culture": "EN",
"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": "80.236.38.245",
"Billing": {
"FirstName": "Joe",
"LastName": "Bloggs",
"Address": {
"AddressLine1": null,
"AddressLine2": null,
"City": null,
"Region": null,
"PostalCode": null,
"Country": null
}
},
"Shipping": {
"FirstName": "Joe",
"LastName": "Bloggs",
"Address": {
"AddressLine1": null,
"AddressLine2": null,
"City": null,
"Region": null,
"PostalCode": null,
"Country": null
}
},
"Requested3DSVersion": null,
"Applied3DSVersion": "V2_1",
"Tag": "Custom meta",
"CardInfo": {
"BIN": "497010",
"IssuingBank": "LA BANQUE POSTALE",
"IssuerCountryCode": "MA",
"Type": "CREDIT",
"Brand": "VISA",
"SubType": null
}
}
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. Use the deposit preauthorization
Once the Deposit Preauthorization’s PaymentStatus is WAITING, you can use the hold on the funds in a number of ways.
Set up webhook notifications for the following event types in order to be notified when a deposit preauthorization is ready to use, or when it has expired and can no longer be used:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_WAITING
- DEPOSIT_PREAUTHORIZATION_PAYMENT_EXPIRED
There are 3 ways you can use a Deposit Preauthorization and, if it won’t be used, you can cancel it manually to release the preauthorized funds for the user.
- A. Full or partial capture without complement
- B. Full capture with complement
- C. No-show with complement
- D. Cancel
In the following calls, use the Id of the Deposit Preauthorization obtained previously as the DepositId.
Caution - All actions must be taken within 30 days
Any captures or complements must be requested within 30 days, whether or not they are preceded by a capture or no-show.
A. Full or partial capture without complement
This option involves only one step:
- Capture the preauthorized funds either in full or partially
Note - Multiple captures not possible
Capturing the preauthorized amount (without a complement) can only be done once. It is possible to do a partial capture (for an amount less than the preauthorized amount).
To capture the preauthorized funds without taking advantage of the complement feature, use the dedicated Create a Deposit Preauthorized PayIn without complement endpoint.
Specify the Amount values of debited funds and fees. The amount of the DebitedFunds must be less than or equal to the preauthorized amount.
POST /v2.01/{ClientId}/payins/deposit-preauthorized/direct/full-capture
If the preauthorized pay-in is successful, the deposit preauthorization’s PaymentStatus becomes VALIDATED. In the PayinsLinked parameter, the Id of the capture is linked as the PayinCaptureId.
You can set up a webhook for the following event type to be notified of the status change:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_VALIDATED
Use the View a Deposit Preauthorization endpoint to see these details.
Once the PaymentStatus is VALIDATED, no further action is possible.
...
"PaymentStatus": "VALIDATED",
"PayinsLinked": {
"PayinCaptureId": "1719d157-5a97-4af3-91b0-7d660b34b21c",
"PayinComplementId": null
},
...
B. Full capture with complement
This option is a two-step process:
- Capture the full amount of the preauthorized funds
- Capture the complement
Note - Partial capture not possible
Capturing part of the initially preauthorized amount is not possible if it is followed by a complement.
To capture the preauthorized funds and also capture an additional amount as a complement, use the dedicated Create a Deposit Preauthorized PayIn prior to complement endpoint.
POST /v2.01/{ClientId}/payins/deposit-preauthorized/direct/capture-with-complement
If the preauthorized pay-in is successful, the deposit preauthorization’s PaymentStatus becomes TO_BE_COMPLETED. In the PayinsLinked parameter, the Id of the capture is linked as the PayinCaptureId.
You can set up a webhook for the following event type to be notified of the status change:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_TO_BE_COMPLETED
Use the View a Deposit Preauthorization endpoint to see these details.
...
"PaymentStatus": "TO_BE_COMPLETED",
"PayinsLinked": {
"PayinCaptureId": "265d22b6-a3dc-48a4-a685-8655e5bcac6f",
"PayinComplementId": null
},
...
To capture the complement, use the dedicated Create a Deposit Preauthorized PayIn complement endpoint:
{
"AuthorId": "203063430",
"CreditedWalletId": "203063456",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 10000
},
"Fees": {
"Currency": "EUR",
"Amount": 1000
},
"DepositId": "09d21294-f9ac-4797-b2b9-8cc7b4f05f1d",
"Tag": "Created using Mangopay API Postman Collection"
}
After a successful pay-in complement, the deposit preauthorization’s PaymentStatus becomes VALIDATED. In the PayinsLinked parameter, the Id of the complement is linked as the PayinComplementId.
You can set up a webhook for the following event type to be notified of the status change:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_VALIDATED
Use the View a Deposit Preauthorization endpoint to see these details.
Once the PaymentStatus is VALIDATED, no further action is possible.
...
"PaymentStatus": "VALIDATED",
"PayinsLinked": {
"PayinCaptureId": "265d22b6-a3dc-48a4-a685-8655e5bcac6f",
"PayinComplementId": "0c267115-230a-4333-bcc1-2edac84c8224"
},
...
C. No-show with complement
This option is a two-step process:
- Request a no-show, indicating that the preauthorized funds were not used
- Capture a complement, for example as a penalty or other service charge
To request a no-show, change the PaymentStatus to NO_SHOW_REQUESTED.
{
"PaymentStatus": "NO_SHOW_REQUESTED"
}
If the request is successful, the PaymentStatus in the response is NO_SHOW.
...
"PaymentStatus": "NO_SHOW",
"PayinsLinked": {
"PayinCaptureId": null,
"PayinComplementId": null
},
...
You can set up a webhook for the following event types to be notified of the status changes:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_NO_SHOW_REQUESTED
- DEPOSIT_PREAUTHORIZATION_PAYMENT_NO_SHOW
To capture the complement, use the dedicated Create a Deposit Preauthorized PayIn complement endpoint.
POST /v2.01/{ClientId}/payins/deposit-preauthorized/direct/complement
After a successful pay-in complement, the deposit preauthorization’s PaymentStatus becomes VALIDATED. In the PayinsLinked parameter, the Id of the complement is linked as the PayinComplementId.
You can set up a webhook for the following event type to be notified of the status change:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_VALIDATED
Use the View a Deposit Preauthorization endpoint to see these details.
...
"PaymentStatus": "VALIDATED",
"PayinsLinked": {
"PayinCaptureId": null,
"PayinComplementId": "7c89d633-2023-440c-843a-ac8ce2a683a4"
},
...
Once the PaymentStatus is VALIDATED, no further action is possible.
D. Cancel
If the Deposit Preauthorization won’t be used, either to capture the preauthorized funds or a complement, you can release the preauthorized funds by changing the PaymentStatus to CANCELED.
Once the PaymentStatus is CANCELED, no further action is possible.
...
"PaymentStatus": "CANCELED",
"PayinsLinked": {
"PayinCaptureId": null,
"PayinComplementId": null
},
...
You can set up a webhook for the following event types to be notified of the status changes:
- DEPOSIT_PREAUTHORIZATION_PAYMENT_CANCEL_REQUESTED
- DEPOSIT_PREAUTHORIZATION_PAYMENT_CANCELED