The PreAuthorization Object

The PreAuthorization Object ensures the solvency of a registered card for 7 days. The overall process is as follows:

  1. Register a card (CardRegistration)
  2. Create a PreAuthorization with the CardId. This allows you to charge an amount on a card
  3. Charge the card through the PreAuthorized PayIn object (Payins/preauthorized/direct)

How does PreAuthorization work?

  • Once the PreAuthorization object is created the Status is "CREATED" until 3D secure validation.
  • If the authorization is successful the status is "SUCCEEDED" if it failed the status is "FAILED".
  • Once Status = "SUCCEEDED" and PaymentStatus = "WAITING" you can charge the card.
  • The Pay-In amount has to be less than or equal to the amount authorized.

In Italy, Greece and Spain, the pre-authorization has a particular running. In fact, the pre-authorized amount is debited from the bank account. Pre-authorized funds are stored by the bank. The user will get his/her funds back within 7 days. This case appears on several Banks (we don’t have exhaustive list) in Spain, Italy and Greece. Mangopay recommends you to inform your users or only create €1.00 pre-authorizations in these countries.

Note that a preauthorization is automatically cancelled after the ExpirationDate if you do not cancel it yourself, nor do a payin with it

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Status
PreAuthorizationStatus

PreAuthorizationStatus:

CREATED , SUCCEEDED, FAILED

The status of the preauthorization

Status of the PreAuthorization

PaymentStatus
PaymentStatus

PaymentStatus:

WAITING, CANCELED, EXPIRED, VALIDATED

The status of the payment for a preauthorization

The status of the payment after the PreAuthorization. You can pass the PaymentStatus from "WAITING" to "CANCELED" should you need/want to

ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

ExecutionType
PreAuthorizationExecutionType

PreAuthorizationExecutionType:

DIRECT

The execution type for a preauthorization

How the PreAuthorization has been executed

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE

The SecureMode corresponds to '3D secure' for CB Visa and MasterCard. This field lets you activate it manually. The field lets you activate it automatically with "DEFAULT" (Secured Mode will be activated from €50 or when MANGOPAY detects there is a higher risk ), "FORCE" (if you wish to specifically force the secured mode).

CardId
string

string:

Maximum length is 255 characters

The ID of a card

SecureModeNeeded
bool

bool:

true, false

The value is 'true' if the SecureMode was used

SecureModeRedirectUrl
string

string:

Maximum length is 255 characters

This is the URL where to redirect users to proceed to 3D secure validation

SecureModeReturnURL
string

string:

Maximum length is 255 characters

This is the URL where users are automatically redirected after 3D secure validation (if activated)

ExpirationDate
timestamp

timestamp

The date when the payment is to be processed by

PayInId
string

string:

Maximum length is 255 characters

The Id of the associated PayIn

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"AuthorId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Status": "CREATED",
"PaymentStatus": "WAITING",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"ExecutionType": "DIRECT",
"SecureMode": "DEFAULT",
"CardId": "14213157",
"SecureModeNeeded": false,
"SecureModeRedirectUrl": "http://www.a-url.com/3DS-redirect",
"SecureModeReturnURL": "http://www.my-site.com/returnURL",
"ExpirationDate": 1463495916,
"PayInId": "12639163"
}

Create a PreAuthorization

Note that if you do not cancel the preauthorization yourself, nor do a payin with the preauth, we will automatically cancel it for you after the ExpirationDate

POST .../v2.01/ClientId

The ID of your client account

/preauthorizations/card/direct

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

AuthorId
string

string:

Maximum length is 255 characters

required

A user's ID

DebitedFunds
Money

Money:

View Sub-parameters

required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int

required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE

optional

The SecureMode corresponds to '3D secure' for CB Visa and MasterCard. This field lets you activate it manually. The field lets you activate it automatically with "DEFAULT" (Secured Mode will be activated from €50 or when MANGOPAY detects there is a higher risk ), "FORCE" (if you wish to specifically force the secured mode).

CardId
string

string:

Maximum length is 255 characters

required

The ID of a card

SecureModeReturnURL
string

string:

Maximum length is 255 characters

required

This is the URL where users are automatically redirected after 3D secure validation (if activated)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../preauthorizations/card/direct HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"AuthorId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"SecureMode": "DEFAULT",
"CardId": "14213157",
"SecureModeReturnURL": "http://www.my-site.com/returnURL"
}
require_once("mangopay.php");

try {


$CardPreAuthorization = new \MangoPay\CardPreAuthorization();
$CardPreAuthorization->Tag = "custom meta";
$CardPreAuthorization->AuthorId = "8494514";
$CardPreAuthorization->DebitedFunds = new \MangoPay\Money();
$CardPreAuthorization->DebitedFunds->Currency = "EUR";
$CardPreAuthorization->DebitedFunds->Amount = 12;
$CardPreAuthorization->SecureMode = "DEFAULT";
$CardPreAuthorization->CardId = "14213157";
$CardPreAuthorization->SecureModeReturnURL = "http://www.my-site.com/returnURL";

$Result = $Api->CardPreAuthorizations->Create($CardPreAuthorization);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../preauthorizations/card/direct HTTP/1.1
Body Parameters :
{
"Tag": "",
"AuthorId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"SecureMode": "",
"CardId": "",
"SecureModeReturnURL": ""
}

View a PreAuthorization

GET .../v2.01/ClientId

The ID of your client account

/preauthorizations/PreAuthorizationId

The ID of a card pre-authorisation

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../preauthorizations/:PreAuthorizationId/ HTTP/1.1
require_once("mangopay.php");

try {

$PreAuthorizationId = 12639123;

$CardPreAuthorization = $Api->CardPreAuthorizations->Get($PreAuthorizationId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../preauthorizations// HTTP/1.1

Cancel a PreAuthorization

PUT .../v2.01/ClientId

The ID of your client account

/preauthorizations/PreAuthorizationId

The ID of a card pre-authorisation

/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

PaymentStatus
PaymentStatus

PaymentStatus:

WAITING, CANCELED, EXPIRED, VALIDATED

The status of the payment for a preauthorization

required

The status of the payment after the PreAuthorization. You can pass the PaymentStatus from "WAITING" to "CANCELED" should you need/want to

A canceled PreAuthorization CANNOT be reused.

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../preauthorizations/:PreAuthorizationId/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"PaymentStatus": "CANCELED"
}
require_once("mangopay.php");

try {

$CardPreAuthorization = new \MangoPay\CardPreAuthorization();
$CardPreAuthorization->Tag = "custom meta";
$CardPreAuthorization->Id = 12639123;
$CardPreAuthorization->PaymentStatus = "CANCELED";

$Result = $Api->CardPreAuthorizations->Update($CardPreAuthorization);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../preauthorizations// HTTP/1.1
Body Parameters :
{
"Tag": "",
"PaymentStatus": ""
}