You are viewing the docs for an old API version (v2) → View v2.01

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

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
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

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 or a deposit 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, NO_CHOICE

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

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

Billing
Billing

Billing:

View Sub-parameters

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters

The name of the user.

Billing.LastName
string

string:

Maximum length is 255 characters

The last name of the user.

Billing.Address
Address

Address:

View Sub-parameters

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

SecurityInfo
SecurityInfo

SecurityInfo:

View Sub-parameters

Contains useful informations related to security and fraud

SecurityInfo.AVSResult
AVSResult

AVSResult:

NO_CHECK, NO_MATCH, ADDRESS_MATCH_ONLY, POSTAL_CODE_MATCH_ONLY, FULL_MATCH

Result of Address Verification System check (only available for UK, US and Australia)

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage

The language to use for the mandate confirmation page - needs to be the ISO code of the language

{
"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",
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"SecurityInfo": {
"AVSResult": "NO_CHECK"
},
"Culture": "EN"
}

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/ClientId

The ID of your client account

/preauthorizations/card/direct

Parameters

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
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

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)

Billing
Billing

Billing:

View Sub-parameters

optional

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters

required

The name of the user.

Billing.LastName
string

string:

Maximum length is 255 characters

required

The last name of the user.

Billing.Address
Address

Address:

View Sub-parameters

required

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters

required

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters

optional

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters

required

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters

required

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters

required

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

required

The Country of the Address

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage

optional

The language to use for the payment page - needs to be the ISO code of the language

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE

optional

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../preauthorizations/card/direct HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Culture": "EN",
"SecureMode": "DEFAULT",
"CardId": "14213157",
"SecureModeReturnURL": "http://www.my-site.com/returnURL"
}
POST .../preauthorizations/card/direct HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Billing": {
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
}
},
"Culture": "",
"SecureMode": "",
"CardId": "",
"SecureModeReturnURL": ""
}

View a PreAuthorization

GET .../v2/ClientId

The ID of your client account

/preauthorizations/PreAuthorizationId

The ID of a card pre-authorisation

/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../preauthorizations/:PreAuthorizationId/ HTTP/1.1
GET .../preauthorizations// HTTP/1.1

Cancel a PreAuthorization

PUT .../v2/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 or a deposit 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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
PUT .../preauthorizations/:PreAuthorizationId/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"PaymentStatus": "CANCELED"
}
PUT .../preauthorizations// HTTP/1.1
Body Parameters :
{
"Tag": "",
"PaymentStatus": ""
}

List preauthorizations for a card

GET .../v2/ClientId

The ID of your client account

/cards/CardId

The ID of a card

/preauthorizations

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

CreationDate:ASC / CreationDate:DESC

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

ResultCode
string

string:

Maximum length is 255 characters

optional

The result code of the transaction (you can filter your transactions list by multiple ResultCode values, each one must be separated by a comma)

Status
PreAuthorizationStatus

PreAuthorizationStatus:

CREATED , SUCCEEDED, FAILED

The status of the preauthorization

optional

Status of the PreAuthorization

PaymentStatus
PaymentStatus

PaymentStatus:

WAITING, CANCELED, EXPIRED, VALIDATED

The status of the payment for a preauthorization or a deposit preauthorization

optional

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

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../cards/:CardId/preauthorizations HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"ResultCode": "000000,009199",
"Status": "CREATED",
"PaymentStatus": "WAITING"
}
GET .../cards//preauthorizations HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"ResultCode": "",
"Status": "",
"PaymentStatus": ""
}

List preauthorizations for a user

GET .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/preauthorizations

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

CreationDate:ASC / CreationDate:DESC

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

Status
PreAuthorizationStatus

PreAuthorizationStatus:

CREATED , SUCCEEDED, FAILED

The status of the preauthorization

optional

Status of the PreAuthorization

ResultCode
string

string:

Maximum length is 255 characters

optional

The result code of the transaction (you can filter your transactions list by multiple ResultCode values, each one must be separated by a comma)

PaymentStatus
PaymentStatus

PaymentStatus:

WAITING, CANCELED, EXPIRED, VALIDATED

The status of the payment for a preauthorization or a deposit preauthorization

optional

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

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../users/:UserId/preauthorizations HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"Status": "CREATED",
"ResultCode": "000000,009199",
"PaymentStatus": "WAITING"
}
GET .../users//preauthorizations HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"Status": "",
"ResultCode": "",
"PaymentStatus": ""
}
Share feedback