​
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 Hub
  • 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

In the information returned, make sure you keep the Id of the Preauthorization for the next steps.

API response
{
    "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://mangopay.com/docs/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

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:

API response
{
    "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://mangopay.com/docs/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

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://mangopay.com/docs/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.

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}

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}

Once a preauthorization has been validated or canceled, no more captures can be made against it.

Guide

Learn more about 7-day preauthorization

Endpoint

The Preauthorization object

How to

Learn how to process a card payment

Was this page helpful?

OverviewOverview