Availability:
  • CB_VISA_MASTERCARD only
Note - Multi-capture not possible with 30-day preauthorizationMulti-capture is only available for 7-day preauthorization.
Mangopay’s 30-day preauthorization feature is a two-step process, and uses two API objects:
  • The Deposit Preauthorization to request the card authorization, which involves the user completing 3DS
  • The Deposit Preauthorized PayIn to capture the funds without the user present and based on the authorization

​
How to process a 30-day card preauthorization

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

​
1. Secure the funds

Create a deposit preauthorization to hold funds for 30 days:
POST /v2.01/{ClientId}/deposit-preauthorizations/card/direct 
{
    "AuthorId": "203063430",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 20000
    },
    "CardId": "203076791",
    "SecureModeReturnURL": "https://docs.mangopay.com/please-ignore",
    "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": "97d6:24d6:357a:8acc:5190:606b:91a2:f60c",
    "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"
        }
    },
    "Tag": "Created using Mangopay API Postman Collection"
}
In the information returned, retain the Id of the Deposit Preauthorization for the next steps.

​
2. 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.

​
3. Capture the funds

Once the Deposit Preauthorization’s PaymentStatus is WAITING, the funds are authorized to be captured within 29.5 days.
Note - Multiple captures not possibleCapturing the preauthorized amount can only be done once. It is possible to do a partial capture (for an amount less than the preauthorized amount).
To capture the funds, create the pay-in using the Id of the Deposit Preauthorization obtained previously as the DepositId. 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 
{
    "AuthorId": "203063430",
    "CreditedWalletId": "203063456",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 20000
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "DepositId": "09d21294-f9ac-4797-b2b9-8cc7b4f05f1d",
    "Tag": "Created using Mangopay API Postman Collection"
}
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 GET View a Deposit Preauthorization endpoint to see these details.
API response
...
    "PaymentStatus": "VALIDATED",
    "PayinsLinked": {
        "PayinCaptureId": "1719d157-5a97-4af3-91b0-7d660b34b21c",
        "PayinComplementId": null
    },
...
Once the PaymentStatus is VALIDATED, no further action is possible.

​
4. Cancel hold if not used

In the scenario where the capture is not needed, you should release the user’s funds proactively rather than letting the hold expire after 29.5 days. You can release the preauthorized funds by changing the Deposit Preauthorization’s PaymentStatus to CANCELED:
PUT /v2.01/{ClientId}/deposit-preauthorizations/{DepositId} 
{
   "PaymentStatus": "CANCELED"
}
Once the PaymentStatus is CANCELED, no further action is possible.
API response parameters - Canceled
...
    "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

Guide

Learn how to process a one-time card payment

Endpoint

The Deposit Preauthorization object