> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/preauthorizations/preauthorization-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Preauthorization object
### Description
The Preauthorization object enables you to reserve funds on a card so they can be captured later. A preauthorization thus has two parts:
* Authorization of the transaction, handled by the Preauthorization object
* Capture of the funds, handled by the Preauthorized PayIn object
The preauthorized funds can be captured within 6.5 days of a successful authorization.
If you require a hold period of longer than 6.5 days, see the Extended Preauthorization object.
Note that preauthorizations may not be permitted by some issuers and for some card types.
> **Note**
>
> **Note – Multi-capture available with Visa, Mastercard, CB, and AMEX**
>
> Multiple partial captures of the preauthorized amount is possible on the card types:
>
> * `CB_VISA_MASTERCARD`
> * `AMEX`
>
> Further captures of the `RemainingFunds` can be made if the `PaymentStatus` is `WAITING`.
>
> There is no limit to the number of captures that can be made if each is valid.
### Attributes
### Schema (`PreauthorizationResponse`)
```yaml
components:
schemas:
Tag:
type: string
description: >-
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers
in your system. To store multiple values, you can serialize them into a
single string, for example a JSON object:
`"{\"id_1\":AB123,\"id_2\":DE456}"`.
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
AuthorId:
type: string
description: The unique identifier of the user at the source of the transaction.
title: AuthorId
FlowDescriptorResponseBeneficiariesItems:
type: object
properties:
UserId:
type: string
description: >-
The unique identifier of the Natural User or Legal User declared as
a beneficiary of the pay-in.
title: FlowDescriptorResponseBeneficiariesItems
FlowDescriptorResponse:
type: object
properties:
FlowId:
type: string
description: >-
Unique identifier of the payment flow, used by Mangopay for internal
purposes.
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorResponseBeneficiariesItems'
description: >-
Max. length: 5 items
The list of up to 5 Natural or Legal Users declared as beneficiaries
of the pay-in, who must all be KYC/KYB verified when the pay-in
request is made. The pay-in also fails if the `Beneficiaries` array
contains nulled objects or invalid `UserId` values.
description: >
Information about the Owner beneficiaries targeted by the pay-in and its
subsequent transfers, who must all be KYC/KYB verified when the pay-in
request is made ([read more](/guides/payin-beneficiaries)).
If the `FlowDescriptor.Beneficiaries` is sent in the API request, then:
- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB
checks.
- **ALL** `UserId` values in the array must be one of:
- `OWNER` whose `KYCLevel` is `REGULAR`
- `PLATFORM`
The pay-in `Status` becomes `FAILED` with `ResultCode`
[002951](/errors/codes/002951) if at least one
`FlowDescriptor.Beneficiaries.UserId` is:
- `PAYER`
- `OWNER` whose `KYCLevel` is `LIGHT`
If the `FlowDescriptor.Beneficiaries` is not sent in the API request,
then the `CreditedWalletId` holder is subject to KYC/KYB checks. This
property is optional for backwards compatibility but is recommended for
all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER`
or the same value as one of the `FlowDescriptor.Beneficiaries`.
title: FlowDescriptorResponse
Currency:
type: string
description: >-
**Allowed values:** The three-letter ISO 4217
code (EUR, GBP, etc.) of a supported currency (depends on feature, contract,
and activation settings).
The currency of the amount.
title: Currency
Amount:
type: integer
description: >-
The amount of the currency in its minor unit. For example, EUR 12.60
would be represented as `1260` whereas JPY 12 would be represented as
just `12`.
title: Amount
PreauthorizationResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the preauthorized funds.
title: PreauthorizationResponseDebitedFunds
PreauthorizationResponseRemainingFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the remaining preauthorized funds.
title: PreauthorizationResponseRemainingFunds
AuthorizationStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the authorization.
title: AuthorizationStatus
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
SecureModeReturnURL:
type: string
description: >-
Max. length: 255 characters
The URL to which users are automatically returned after 3DS2 if it is
triggered (i.e., if the `SecureModeNeeded` parameter is set to `true`).
title: SecureModeReturnURL
StatementDescriptor_22:
type: string
description: >-
Max. length: 22 characters; only alphanumeric and spaces
Custom description to appear on the user’s bank statement along with the
platform name. Different banks may show more or less information. See
the Customizing bank statement references
article for details.
title: StatementDescriptor_22
AVSResult:
type: object
properties:
AVSResult:
type: string
description: >-
The result of the Address Verification System check (only available
for UK, US, and Canada).
description: Information regarding security and anti-fraud tools.
title: AVSResult
BrowserInfo:
type: object
properties:
AcceptHeader:
type: string
description: >-
The exact content of the HTTP accept headers as sent to the platform
from the end user's browser.
JavaEnabled:
type: boolean
description: >-
Whether or not the end user's browser has the ability to execute
Java.
Language:
type: string
description: >-
Format: Two-letter language code (ISO 639-1 alpha-2) followed by
two-letter country code (ISO 3166-1 alpha-2), separated by a hyphen
(example: `en-US`; pattern:`^[a-zA-Z]{2}(-[a-zA-Z]{2})?$`)
The language of the browser.
ColorDepth:
type: integer
description: >-
The value representing the depth of the screen's color palette for
displaying images, in bits per pixel.
ScreenHeight:
type: integer
description: The height of the screen in pixels.
ScreenWidth:
type: integer
description: The width of the screen in pixels.
TimeZoneOffset:
type: integer
description: The difference in minutes between the browser's timezone and UTC.
UserAgent:
type: string
description: The exact content of the HTTP User-Agent header.
JavascriptEnabled:
type: boolean
description: >-
Whether or not the end user's browser has the ability to execute
JavaScript.
required:
- AcceptHeader
- JavaEnabled
- Language
- ColorDepth
- ScreenHeight
- ScreenWidth
- TimeZoneOffset
- UserAgent
- JavascriptEnabled
description: >-
Information about the browser used by the end user (author) to perform
the payment.
title: BrowserInfo
IpAddress:
type: string
description: >-
The IP address of the end user initiating the transaction, in IPV4 or
IPV6 format.
title: IpAddress
Address:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: >-
The postal code of the address. The postal code can contain the
following characters: alphanumeric, dashes, and spaces.
Country:
type: string
description: >-
Format: Two-letter country code ([ISO 3166-1 alpha-2
format](/api-reference/overview/data-formats))
The country of the address.
description: The postal address.
title: Address
Billing_DefaultsShippingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address'
description: >-
**Default values:** `FirstName`, `LastName`, and `Address` information
of the `Shipping` object if sent, otherwise of the `AuthorId` (if
address values present).
Information about the billing address.
title: Billing_DefaultsShippingUser_Response
Address_SubPropsRequired:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: >-
The postal code of the address. The postal code can contain the
following characters: alphanumeric, dashes, and spaces.
Country:
type: string
description: >-
Format: Two-letter country code ([ISO 3166-1 alpha-2
format](/api-reference/overview/data-formats))
The country of the address.
required:
- AddressLine1
- City
- PostalCode
- Country
description: The postal address.
title: Address_SubPropsRequired
Shipping_DefaultsBillingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address_SubPropsRequired'
description: >-
**Default values:** `FirstName`, `LastName`, and `Address` information
of the `Billing` object if sent, otherwise of the `AuthorId` (if address
values present).
Information about the shipping address.
title: Shipping_DefaultsBillingUser_Response
PreferredCardNetwork:
type: string
description: >-
**Allowed values:** `VISA`, `MASTERCARD`, `CB`, `MAESTRO`
The card network to use, as chosen by the cardholder, in case of co-branded cards.
title: PreferredCardNetwork
PaymentCategory:
type: string
description: >-
**Default value:** `ECommerce`
**Allowed values:** `ECommerce`, `TelephoneOrder`
The channel through which the user provided their card details, used to
indicate mail-order and telephone-order (MOTO) payments:
- `ECommerce` – Payment received online.
- `TelephoneOrder` – Payment received via mail order or telephone order
(MOTO).
title: PaymentCategory
CardInfo:
type: object
properties:
BIN:
type: string
description: The bank identification number (BIN) of the card.
IssuingBank:
type: string
description: The name of the bank that issued the card.
IssuerCountryCode:
type: string
description: The country code of the card issuer.
Type:
type: string
description: The type of card (for example, `CREDIT` or `DEBIT`).
SubType:
type:
- string
- 'null'
description: The sub-type of the card, if available.
Brand:
type: string
description: The card brand (for example, `VISA` or `MASTERCARD`).
description: >-
Information about the card used for the transaction. If the information
or data is not available, `null` is returned.
title: CardInfo
AuthenticationResult:
type: object
properties:
AuthenticationType:
type:
- string
- 'null'
description: >-
**Returned values:** `CHALLENGE`, `FRICTIONLESS`,
`DIRECT_AUTHORIZATION`
The type of authentication:
- `CHALLENGE` – The issuer requested SCA to be enforced (for
example, using 3DS).
- `FRICTIONLESS` – The transaction was exempted from SCA because an
exemption was granted by the issuer.
- `DIRECT_AUTHORIZATION` – The transaction was sent to the issuer
for authorization without any frictionless or challenge (for
example, if SCA doesn't apply). A `null` value typically indicates
that authentication was not requested (for example, because the
request failed before being sent) or a decision was not received.
A `null` value typically indicates that authentication was not
requested (for example, because the request failed before being
sent) or a decision was not received.
description: >-
Information about the authentication result, based on the request made
by Mangopay and the decision of the issuer regarding the type of
authentication to be enforced (if applicable).
title: AuthenticationResult
PreauthorizationResponse:
type: object
properties:
Id:
type: string
description: |-
Max. length: 255 characters
The unique identifier of the preauthorization.
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
$ref: '#/components/schemas/AuthorId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
DebitedFunds:
$ref: '#/components/schemas/PreauthorizationResponseDebitedFunds'
description: Information about the preauthorized funds.
RemainingFunds:
$ref: '#/components/schemas/PreauthorizationResponseRemainingFunds'
description: Information about the remaining preauthorized funds.
AuthorizationDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time successful authorization
occurred. If authorization failed, the value is `null`.
Status:
$ref: '#/components/schemas/AuthorizationStatus'
PaymentStatus:
type: string
description: >-
**Returned values:** `WAITING`, `CANCELED`, `EXPIRED`, `VALIDATED`
The status of the preauthorization object:
- `WAITING` – The remaining preauthorized funds can be captured by
making one or several preauthorized pay-ins. Pay-ins can only be
made against a preauthorization with the `WAITING` status.
- `CANCELED` – The preauthorization was canceled manually before any
preauthorized pay-ins were made, or it was canceled automatically
because the authorization failed.
- `EXPIRED` – The hold period on the preauthorized funds has ended
without any preauthorized pay-ins taking place.
- `VALIDATED` – During the hold period: Indicates that all the
preauthorized funds have been captured (`RemainingFunds` is zero)
and no more preauthorized pay-ins can be made. After the hold
period: Indicates that at least one capture was made during the hold
period.
ExpirationDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time the hold period ends and
the preauthorized funds are released. At the expiration date, the
preauthorization's `PaymentStatus` changes to `EXPIRED` if no
captures were made or `VALIDATED` if at least one capture was made.
PayInId:
type: string
description: The unique identifier of the pay-in.
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
SecureMode:
type: string
description: >-
**Returned values:** `DEFAULT`, `FORCE`, `NO_CHOICE`
The mode applied for the 3DS2 protocol for CB, Visa, and Mastercard.
The options are:
- `DEFAULT` – Requests an exemption to strong customer
authentication (SCA), and thus a frictionless payment experience, if
allowed by your Mangopay contract and accepted by the issuer.
- `FORCE` – Requests SCA.
- `NO_CHOICE` – Leaves the choice to the issuer whether to allow for
a frictionless payment experience or to enforce SCA.
CardId:
type: string
description: >-
The unique identifier of the Card object, obtained during the card
registration process.
SecureModeReturnURL:
$ref: '#/components/schemas/SecureModeReturnURL'
SecureModeRedirectURL:
type: string
description: |-
Max. length: 255 characters
The URL to which to redirect the user to proceed to 3DS2 validation.
SecureModeNeeded:
type: boolean
description: Whether or not the `SecureMode` was used.
PaymentType:
type: string
description: |-
**Returned values:** `CARD`
The payment type of the preauthorization.
ExecutionType:
type: string
description: |-
**Returned values:** `DIRECT`
The execution type of the preauthorization.
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor_22'
Culture:
type: string
description: >-
**Returned values:** One of the supported languages in the [ISO
639-1 format](/api-reference/overview/data-formats): DE, EN, ES, FR,
IT, NL, PL, PT.
The language in which the payment page is to be displayed.
SecurityInfo:
$ref: '#/components/schemas/AVSResult'
MultiCapture:
type: boolean
description: |-
**Default value:** true
Whether multiple captures are activated for the preauthorization.
BrowserInfo:
$ref: '#/components/schemas/BrowserInfo'
IpAddress:
$ref: '#/components/schemas/IpAddress'
Billing:
$ref: '#/components/schemas/Billing_DefaultsShippingUser_Response'
Shipping:
$ref: '#/components/schemas/Shipping_DefaultsBillingUser_Response'
Requested3DSVersion:
type: string
description: |-
**Returned values:** `V1`, `V2_1`
The 3DS protocol version to be applied to the transaction.
Applied3DSVersion:
type: string
description: |-
**Returned values:** `V1`, `V2_1`
The 3DS protocol version applied to the transaction.
PreferredCardNetwork:
$ref: '#/components/schemas/PreferredCardNetwork'
PaymentCategory:
$ref: '#/components/schemas/PaymentCategory'
CardInfo:
$ref: '#/components/schemas/CardInfo'
AuthenticationResult:
$ref: '#/components/schemas/AuthenticationResult'
title: PreauthorizationResponse
```
### Related resources
#### [Guide](/guides/payment-methods/card/preauthorization)
Learn more about 7-day preauthorization