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 through the PreAuthorized
PayInobject (Payins/preauthorized/direct)
How does PreAuthorization work?
- Once the
PreAuthorizationobject is created theStatusis "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.
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
AuthorIdstring:
Maximum length is 255 characters
A user's ID
DebitedFundsMoney:
View Sub-parameters
Information about the funds that are being debited
DebitedFunds.CurrencyCurrency:
AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
The currency - should be ISO_4217 format
DebitedFunds.Amountint
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)
StatusPreAuthorizationStatus:
CREATED , SUCCEEDED, FAILED
The status of the preauthorization
Status of the PreAuthorization
PaymentStatusPaymentStatus:
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
ResultCodestring:
Maximum length is 255 characters
The result code
ResultMessagestring:
Maximum length is 255 characters
A verbal explanation of the ResultCode
ExecutionTypePreAuthorizationExecutionType:
DIRECT
The execution type for a preauthorization
How the PreAuthorization has been executed
SecureModeSecureMode:
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.
CardIdstring:
Maximum length is 255 characters
The ID of a card
SecureModeNeededbool:
true, false
The value is 'true' if the SecureMode was used
SecureModeRedirectURLstring:
Maximum length is 255 characters
This is the URL where to redirect users to proceed to 3D secure validation
SecureModeReturnURLstring:
Maximum length is 255 characters
This is the URL where users are automatically redirected after 3D secure validation (if activated)
ExpirationDatetimestamp
The date when the payment is to be processed by
PayInIdstring:
Maximum length is 255 characters
The Id of the associated PayIn
BillingBilling:
View Sub-parameters
Contains every useful informations related to the user billing
Billing.FirstNamestring:
Maximum length is 255 characters
The name of the user.
Billing.LastNamestring:
Maximum length is 255 characters
The last name of the user.
Billing.AddressAddress:
View Sub-parameters
The address
Billing.Address.AddressLine1string:
Maximum length is 255 characters
The first line of the address
Billing.Address.AddressLine2string:
Maximum length is 255 characters
The second line of the address
Billing.Address.Citystring:
Maximum length is 255 characters
The city of the address
Billing.Address.Regionstring:
Maximum length is 255 characters
The region of the address - this is optional except if the Country is US, CA or MX
Billing.Address.PostalCodestring:
Maximum length is 50 characters
The postal code of the address - can be alphanumeric, dashes or spaces
Billing.Address.CountryCountryIso:
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
SecurityInfoSecurityInfo:
View Sub-parameters
Contains useful informations related to security and fraud
SecurityInfo.AVSResultAVSResult:
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)
CultureCultureCode:
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