> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Extended Preauthorization object
### Description
The Extended Preauthorization object enables you to reserve funds on a card so they can be captured later, using two API calls:
* Authorization of the transaction, handled by the Extended Preauthorization object
* Capture of the funds, handled by the Extended Preauthorized PayIn object
The Extended Preauthorization object is used for two payment methods, indicated by the `PaymentType`:
* `CARD` – Created using [POST Create a Card Extended Preauthorization](/api-reference/extended-preauthorizations/create-card-extended-preauthorization)
* `PAYPAL` – Created using [POST Create a PayPal Extended Preauthorization](/api-reference/extended-preauthorizations/create-paypal-extended-preauthorization)
In both cases, the capture is made with the same endpoint, [POST Create an Extended Preauthorized PayIn](/api-reference/extended-preauthorizations/create-extended-preauthorized-payin):
* `CARD` – Within **29.5** days.
* `PAYPAL` – Within 3 days as recommended by PayPal, but the technical limit is **29** days (not 29.5).
Note that preauthorizations may not be permitted by some issuers and for some card types.
> **Note**
>
> **Note – Multi-capture not possible with the Extended Preauthorization**
>
> Multiple partial captures are not possible with the Extended Preauthorization, for either `CARD` or `PAYPAL`. In both cases however, the single capture can be for an amount less than the preauthorized amount.
### Attributes
### Schema (`ExtendedPreauthorizationResponse`)
```yaml
components:
schemas:
Id:
type: string
description: >-
Max length: 128 characters (see [data
formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.
title: Id
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
CardExtendedPreauthorizationResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the preauthorized funds.
title: CardExtendedPreauthorizationResponseDebitedFunds
AuthorizationStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the authorization.
title: AuthorizationStatus
CardExtendedPreauthorizationResponsePayinsLinked:
type: object
properties:
PayinCaptureId:
type: string
description: >-
The unique identifier of the preauthorized pay-in (capture) made
against the extended preauthorization to debit the preauthorized
funds.
PayinComplementId:
type: string
description: This deprecated parameter is always returned `null`.
description: >-
Information about the extended preauthorized pay-ins made against the
extended preauthorization.
title: CardExtendedPreauthorizationResponsePayinsLinked
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
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
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
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
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
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
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
CardExtendedPreauthorizationResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
CreationDate:
$ref: '#/components/schemas/CreationDate'
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
extended preauthorization's `PaymentStatus` changes to `EXPIRED` if
no captures were made.
AuthorizationDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time successful authorization
occurred. If authorization failed, the value is `null`.
AuthorId:
$ref: '#/components/schemas/AuthorId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
DebitedFunds:
$ref: >-
#/components/schemas/CardExtendedPreauthorizationResponseDebitedFunds
description: Information about the preauthorized funds.
Status:
$ref: '#/components/schemas/AuthorizationStatus'
PaymentStatus:
type: string
description: >-
**Returned values:** `WAITING`, `CANCELED`, `CANCEL_REQUESTED`,
`EXPIRED`, `VALIDATED`, `FAILED`
The payment status of the extended preauthorization object:
- `WAITING` – The extended preauthorization can be used: the
preauthorized funds can be captured (if `Status` is `SUCCEEDED`) or
the preauthorization can be canceled manually.
- `CANCELED` – Value to pass to manually cancel the extended
preauthorization before use; indicates that the extended
preauthorization was canceled manually.
- `CANCEL_REQUESTED` – The cancellation of the extended
preauthorization has been requested but not yet processed.
- `EXPIRED` – The hold period on the preauthorized funds has ended
without it being used.
- `VALIDATED` – Indicates that the preauthorized funds were
captured.
- `FAILED` – The pay-in against the preauthorization has failed, but
a retry may be possible.
PayinsLinked:
$ref: >-
#/components/schemas/CardExtendedPreauthorizationResponsePayinsLinked
description: >-
Information about the extended preauthorized pay-ins made against
the extended preauthorization.
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
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.
Shipping:
$ref: '#/components/schemas/Shipping_DefaultsBillingUser_Response'
Tag:
$ref: '#/components/schemas/Tag'
CardId:
type: string
description: >-
The unique identifier of the Card object, obtained during the card
registration process.
PreferredCardNetwork:
$ref: '#/components/schemas/PreferredCardNetwork'
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`).
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.
BrowserInfo:
$ref: '#/components/schemas/BrowserInfo'
IpAddress:
$ref: '#/components/schemas/IpAddress'
Billing:
$ref: '#/components/schemas/Billing_DefaultsShippingUser_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.
CardInfo:
$ref: '#/components/schemas/CardInfo'
AuthenticationResult:
$ref: '#/components/schemas/AuthenticationResult'
description: Response if Extended Preauthorization's `PaymentType` is `CARD`.
title: CardExtendedPreauthorizationResponse
PayPalExtendedPreauthorizationResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the preauthorized funds.
title: PayPalExtendedPreauthorizationResponseDebitedFunds
PayPalExtendedPreauthorizationResponsePayinsLinked:
type: object
properties:
PayinCaptureId:
type: string
description: >-
The unique identifier of the preauthorized pay-in (capture) made
against the extended preauthorization to debit the preauthorized
funds.
PayinComplementId:
type: string
description: This deprecated parameter is always returned `null`.
description: >-
Information about the extended preauthorized pay-ins made against the
extended preauthorization.
title: PayPalExtendedPreauthorizationResponsePayinsLinked
StatementDescriptor:
type: string
description: >-
Max. length: 10 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
PayPalExtendedPreauthorizationResponseTrackingsItems:
type: object
properties:
TrackingNumber:
type: string
description: The shipment's tracking number provided by the carrier.
Carrier:
type: string
description: >-
The carrier for the shipment. Use the country-specific version of
the carrier if it exists, otherwise use its global version.
NotifyBuyer:
type: boolean
description: >-
**Default value:** false
If `true`, sends an email notification to the
`PaypalBuyerAccountEmail` containing the `TrackingNumber` and
`Carrier`, which allows the end user to track their shipment with
the carrier.
title: PayPalExtendedPreauthorizationResponseTrackingsItems
PayPalExtendedPreauthorizationResponseLineItemsItems:
type: object
properties:
Name:
type: string
description: The name of the item.
Quantity:
type: integer
description: The quantity of the item.
UnitAmount:
type: integer
description: The cost of the item, excluding tax.
TaxAmount:
type: integer
description: The tax amount applied to the item.
Description:
type: string
description: >-
The platform's unique reference for the seller. This value must be
consistently used for the given seller. You can use, for example,
the Mangopay `UserId` or the seller's business name or first name
and last name.
**Caution:** Failure to use a unique seller identifier may result in
PayPal restricting your service.
Category:
type: string
description: >-
**Allowed values:** PHYSICAL_GOODS, DIGITAL_GOODS, DONATION
The category of the item:
- `PHYSICAL_GOODS` – Tangible items that can be physically shipped
and received with proof of delivery upon arrival.
- `DIGITAL_GOODS` – Products or services that are distributed and
consumed via digital platforms or devices.
- `DONATION` – Voluntary contribution made without any goods or
services received in return. Multiple line items can be categorized
as `DONATION` within a single transaction, however it is not
possible to combine `DONATION` other line item categories within the
same transaction.
Sku:
type: string
description: The SKU or reference for the item on your platform.
Discount:
type: integer
description: >-
The discount applied to the item, in the smallest currency
sub-division.
title: PayPalExtendedPreauthorizationResponseLineItemsItems
ReturnURL_255:
type: string
description: >-
Max. length: 255 characters
The URL to which the user is returned after the payment, whether the
transaction is successful or not.
title: ReturnURL_255
PayPalExtendedPreauthorizationResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
CreationDate:
$ref: '#/components/schemas/CreationDate'
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
extended preauthorization's `PaymentStatus` changes to `EXPIRED` if
no captures were made.
AuthorizationDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time successful authorization
occurred. If authorization failed, the value is `null`.
AuthorId:
$ref: '#/components/schemas/AuthorId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
DebitedFunds:
$ref: >-
#/components/schemas/PayPalExtendedPreauthorizationResponseDebitedFunds
description: Information about the preauthorized funds.
Status:
$ref: '#/components/schemas/AuthorizationStatus'
PaymentStatus:
type: string
description: >-
**Returned values:** `WAITING`, `CANCELED`, `CANCEL_REQUESTED`,
`EXPIRED`, `VALIDATED`, `FAILED`
The payment status of the extended preauthorization object:
- `WAITING` – The extended preauthorization can be used: the
preauthorized funds can be captured (if `Status` is `SUCCEEDED`) or
the preauthorization can be canceled manually.
- `CANCELED` – Value to pass to manually cancel the extended
preauthorization before use; indicates that the extended
preauthorization was canceled manually.
- `CANCEL_REQUESTED` – The cancellation of the extended
preauthorization has been requested but not yet processed.
- `EXPIRED` – The hold period on the preauthorized funds has ended
without it being used.
- `VALIDATED` – Indicates that the preauthorized funds were
captured.
- `FAILED` – The pay-in against the preauthorization has failed, but
a retry may be possible.
PayinsLinked:
$ref: >-
#/components/schemas/PayPalExtendedPreauthorizationResponsePayinsLinked
description: >-
Information about the extended preauthorized pay-ins made against
the extended preauthorization.
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
PaymentType:
type: string
description: |-
**Returned values:** `PAYPAL`
The payment type of the preauthorization.
ExecutionType:
type: string
description: |-
**Returned values:** `WEB`
The execution type of the preauthorization.
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor'
Shipping:
$ref: '#/components/schemas/Shipping_DefaultsBillingUser_Response'
Tag:
$ref: '#/components/schemas/Tag'
ShippingPreference:
type: string
description: >-
**Returned values:** `SET_PROVIDED_ADDRESS`, `GET_FROM_FILE`,
`NO_SHIPPING`
Information about the shipping address behavior on the PayPal
payment page:
- `SET_PROVIDED_ADDRESS` - The `Shipping` parameter becomes required
and its values are displayed to the end user, who is not able to
modify them.
- `GET_FROM_FILE` – The `Shipping` parameter is ignored and the end
user can choose from registered addresses.
- `NO_SHIPPING` – No shipping address section is displayed.
PaypalBuyerAccountEmail:
type: string
description: >-
The email address registered on the PayPal account used to make the
payment.
Reference:
type: string
description: |-
Max. length: 127 characters (truncated after)
The platform's order reference for the transaction.
CancelURL:
type: string
description: >-
The URL to which the user is returned after canceling the payment.
If not provided, the Cancel button returns the user to the
`RedirectURL`.
PaypalOrderID:
type: string
description: PayPal's unique identifier for the order.
BuyerCountry:
type: string
description: The country of the buyer.
BuyerFirstname:
type: string
description: The first name of the buyer.
BuyerPhone:
type: string
description: The mobile phone number of the buyer.
BuyerLastname:
type: string
description: The last name of the buyer.
PaypalPayerID:
type: string
description: The PayPal identifier of the buyer.
Trackings:
type: array
items:
$ref: >-
#/components/schemas/PayPalExtendedPreauthorizationResponseTrackingsItems
description: Shipping information of the `LineItems` added to the pay-in object.
LineItems:
type: array
items:
$ref: >-
#/components/schemas/PayPalExtendedPreauthorizationResponseLineItemsItems
description: >-
Information about the items purchased in the transaction. The total
of all line items' `UnitAmount` and `TaxAmount` must equal the
`DebitedFunds` amount (negative amounts not allowed).
Culture:
type: string
description: >-
**Returned values:** One of the supported languages in the [ISO
639-1 format](/api-reference/overview/data-formats): AT, BR, CA, CH,
CN, DE, DK, ES, FR, GB, ID, IL, IT, JK, JP, NL, NO, PL, PT, RU, SE,
TH, TR, TW, US.
The language in which the PayPal payment page is to be displayed.
Billing:
description: >-
Returned `null` because the billing address is not applicable to
PayPal preauth.
RedirectURL:
type: string
description: >-
The URL to which to redirect the user to complete the payment.
**Caution:** This variable URL is specific to each payment. You must
rely on the returned URL in full (host, path, and queries) and not
hardcode any part of it.
ReturnURL:
$ref: '#/components/schemas/ReturnURL_255'
description: Response if Extended Preauthorization's `PaymentType` is `PAYPAL`.
title: PayPalExtendedPreauthorizationResponse
ExtendedPreauthorizationResponse:
oneOf:
- $ref: '#/components/schemas/CardExtendedPreauthorizationResponse'
- $ref: '#/components/schemas/PayPalExtendedPreauthorizationResponse'
title: ExtendedPreauthorizationResponse
```
### Related resources
#### [Guide](/guides/payment-methods/card/extended-preauthorization)
Learn more about 30-day preauthorization