The PreAuthorization object
The PreAuthorization object ensures the solvency of a registered card for 7 days. The overall process is as follows:
- Register a card (CardRegistration)
- Create a PreAuthorization with the CardId. This allows you to charge an amount on a card.
- Charge the card using the Card PreAuthorized PayIn (payins/preauthorized/direct)
How does PreAuthorization work?
- Once the
PreAuthorization
object is created theStatus
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" andPaymentStatus
= "WAITING" you can charge the card. - The pay-in amount has to be less than or equal to the amount authorized.
- There is no limit to the number of captures that can be made, so long as each of these is valid.
For more information on making multiple pay-ins against a pre-authorization, please refer to Multi-capture.
Multiple captures are only possible with the payment method CB/Visa/Mastercard.
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 pay-in with it
Parameters
AuthorId
string:
Maximum length is 255 characters
A user's ID
DebitedFunds
MoneyCard:
View Sub-parameters
Information about the funds that are being debited
DebitedFunds.Currency
CurrencyCard:
AED, AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
The currency of the card payment - should be ISO_4217 format
DebitedFunds.Amount
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)
RemainingFunds
MoneyCard:
View Sub-parameters
Value of the funds remaining on a pre-authorization
RemainingFunds.Currency
CurrencyCard:
AED, AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
The currency of the card payment - should be ISO_4217 format
RemainingFunds.Amount
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:
CREATED , SUCCEEDED, FAILED
The status of the preauthorization
Status of the PreAuthorization
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:
Maximum length is 255 characters
The result code
ResultMessage
string:
Maximum length is 255 characters
A verbal explanation of the ResultCode
ExecutionType
PreAuthorizationExecutionType:
DIRECT
The execution type for a preauthorization
How the PreAuthorization has been executed
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:
Maximum length is 255 characters
The ID of a card
SecureModeNeeded
bool:
true, false
The value is 'true' if the SecureMode was used
SecureModeRedirectURL
string:
Maximum length is 255 characters
This is the URL where to redirect users to proceed to 3D secure validation
SecureModeReturnURL
string:
Maximum length is 255 characters
This is the URL where users are automatically redirected after 3D secure validation (if activated)
ExpirationDate
timestamp
The date when the payment is to be processed by
PayInId
string:
Maximum length is 255 characters
The Id of the associated PayIn
Billing
Billing:
View Sub-parameters
Contains every useful informations related to the user billing
Billing.FirstName
string:
Maximum length is 255 characters
The name of the user.
Billing.LastName
string:
Maximum length is 255 characters
The last name of the user.
Billing.Address
Address:
View Sub-parameters
The address
Billing.Address.AddressLine1
string:
Maximum length is 255 characters
The first line of the address
Billing.Address.AddressLine2
string:
Maximum length is 255 characters
The second line of the address
Billing.Address.City
string:
Maximum length is 255 characters
The city of the address
Billing.Address.Region
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:
Maximum length is 50 characters
The postal code of the address - can be alphanumeric, dashes or spaces
Billing.Address.Country
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:
View Sub-parameters
Contains useful informations related to security and fraud
SecurityInfo.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:
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 payment page - needs to be the ISO code of the language
MultiCapture
bool:
true, false
Indicates wether this feature is active
IpAddress
string:
Maximum length is 255 characters
IP Address of the end user (format IPV4 or IPV6)
BrowserInfo
BrowserInfo:
This object describes the Browser being user by an end user
View Sub-parameters
This object describes the Browser being user by an end user
BrowserInfo.AcceptHeader
string:
Maximum length is 255 characters
Exact content of the HTTP accept headers as sent to the merchant from the shopper’s browser
BrowserInfo.JavaEnabled
bool:
true, false
Whether the user browser has Java enabled
BrowserInfo.Language
string:
Maximum length is 255 characters
Language of the browser of the user
BrowserInfo.ColorDepth
int
Value representing the bit depth of the colour palette for displaying images, in bits per pixel
BrowserInfo.ScreenHeight
int
The height of the screen in pixels
BrowserInfo.ScreenWidth
int
The width of the screen in pixels
BrowserInfo.TimeZoneOffset
int
UTC time offset in minutes
BrowserInfo.UserAgent
string:
Maximum length is 255 characters
Exact content of the HTTP user-agent header
BrowserInfo.JavascriptEnabled
bool:
true, false
Whether the browser is Javascript enabled
Shipping
Shipping:
View Sub-parameters
Contains every useful information's related to the user shipping
Shipping.FirstName
string:
Maximum length is 100 characters
The name of the user.
Shipping.LastName
string:
Maximum length is 100 characters
The last name of the user.
Shipping.Address
Address:
View Sub-parameters
The address
Shipping.Address.AddressLine1
string:
Maximum length is 255 characters
The first line of the address
Shipping.Address.AddressLine2
string:
Maximum length is 255 characters
The second line of the address
Shipping.Address.City
string:
Maximum length is 255 characters
The city of the address
Shipping.Address.Region
string:
Maximum length is 255 characters
The region of the address - this is optional except if the Country
is US, CA or MX
Shipping.Address.PostalCode
string:
Maximum length is 50 characters
The postal code of the address - can be alphanumeric, dashes or spaces
Shipping.Address.Country
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