The ApiCardPreAuthorizations class provides methods to create and manage card pre-authorizations, which reserve funds on a card without immediately capturing them.
Methods
Create
Create a new pre-authorization.
public function Create($cardPreAuthorization, $idempotencyKey = null)
cardPreAuthorization
\MangoPay\CardPreAuthorization
required
The CardPreAuthorization object to create
Optional idempotency key for safe retries
\MangoPay\CardPreAuthorization - The created CardPreAuthorization object
Example:
$preAuth = new \MangoPay\CardPreAuthorization();
$preAuth->AuthorId = $userId;
$preAuth->DebitedFunds = new \MangoPay\Money();
$preAuth->DebitedFunds->Currency = 'EUR';
$preAuth->DebitedFunds->Amount = 5000;
$preAuth->CardId = 'card_123456';
$preAuth->SecureMode = 'DEFAULT';
$preAuth->SecureModeReturnURL = 'https://example.com/return';
$result = $api->CardPreAuthorizations->Create($preAuth);
Get
Get a pre-authorization by its ID.
public function Get($cardPreAuthorizationId)
The unique identifier of the pre-authorization
\MangoPay\CardPreAuthorization - The CardPreAuthorization object
Example:
$preAuth = $api->CardPreAuthorizations->Get('preauth_123456');
Update
Update a pre-authorization (typically to cancel it or adjust the payment status).
public function Update($cardPreAuthorization)
cardPreAuthorization
\MangoPay\CardPreAuthorization
required
The CardPreAuthorization object to update (must include Id)
\MangoPay\CardPreAuthorization - The updated CardPreAuthorization object
Example:
$preAuth = $api->CardPreAuthorizations->Get('preauth_123456');
$preAuth->PaymentStatus = 'CANCELED';
$result = $api->CardPreAuthorizations->Update($preAuth);
GetTransactions
Get all transactions (pay-ins) associated with a pre-authorization.
public function GetTransactions($cardPreAuthorizationId, & $pagination = null, $filter = null, $sorting = null)
The ID of the pre-authorization
Pagination object (passed by reference)
filter
\MangoPay\FilterTransactions
Filtering options
\MangoPay\Transaction[] - Array of Transaction objects
Example:
$pagination = new \MangoPay\Pagination();
$transactions = $api->CardPreAuthorizations->GetTransactions('preauth_123456', $pagination);
CardPreAuthorization Entity
The CardPreAuthorization entity represents a reservation of funds on a payment card.
Properties
The unique identifier of the pre-authorization
Unix timestamp of when the pre-authorization was created
The user ID of the pre-authorization author
The amount to pre-authorize on the card
The status of the pre-authorization: CREATED, SUCCEEDED, FAILED
The payment status: WAITING, CANCELED, EXPIRED, VALIDATED
The result code of the pre-authorization
The result message explaining the result code
A description that appears on the bank statement
How the pre-authorization is executed (always CARD)
The 3D Secure mode: DEFAULT, FORCE, NO_CHOICE
The ID of the registered card to use
Whether 3D Secure validation was required
The URL to redirect users to for 3D Secure validation
The URL where users are redirected after 3D Secure validation
Unix timestamp when the pre-authorization expires (typically 30 days)
Unix timestamp when the pre-authorization was authorized
The type of payment (always CARD)
The ID of the associated pay-in (if captured)
Billing information for the transaction
Security validation information
Whether multiple captures are allowed for this pre-authorization
The remaining funds available for capture
The IP address of the user
Browser information for 3DS2
The requested 3D Secure version
The 3D Secure version that was applied
Information about the card used
The payment category: ECommerce (default), TelephoneOrder
AuthenticationResult
\MangoPay\AuthenticationResult
3DS authentication result
Usage Examples
Create a Pre-Authorization
$preAuth = new \MangoPay\CardPreAuthorization();
$preAuth->AuthorId = $userId;
$preAuth->DebitedFunds = new \MangoPay\Money();
$preAuth->DebitedFunds->Currency = 'EUR';
$preAuth->DebitedFunds->Amount = 5000; // €50.00
$preAuth->CardId = 'card_123456';
$preAuth->SecureMode = 'DEFAULT';
$preAuth->SecureModeReturnURL = 'https://example.com/return';
$preAuth->IpAddress = $_SERVER['REMOTE_ADDR'];
$result = $api->CardPreAuthorizations->Create($preAuth);
if ($result->SecureModeNeeded) {
// Redirect user to 3DS page
header('Location: ' . $result->SecureModeRedirectURL);
exit;
}
Capture Pre-Authorized Funds
// Create a pre-authorized pay-in to capture funds
$payIn = new \MangoPay\PayIn();
$payIn->AuthorId = $userId;
$payIn->CreditedWalletId = $walletId;
$payIn->DebitedFunds = new \MangoPay\Money();
$payIn->DebitedFunds->Currency = 'EUR';
$payIn->DebitedFunds->Amount = 5000;
$payIn->Fees = new \MangoPay\Money();
$payIn->Fees->Currency = 'EUR';
$payIn->Fees->Amount = 100;
$payIn->PaymentType = 'PREAUTHORIZED';
$payIn->ExecutionType = 'DIRECT';
$paymentDetails = new \MangoPay\PayInPaymentDetailsPreAuthorized();
$paymentDetails->PreauthorizationId = 'preauth_123456';
$payIn->PaymentDetails = $paymentDetails;
$executionDetails = new \MangoPay\PayInExecutionDetailsDirect();
$payIn->ExecutionDetails = $executionDetails;
$result = $api->PayIns->Create($payIn);
Cancel a Pre-Authorization
$preAuth = $api->CardPreAuthorizations->Get('preauth_123456');
$preAuth->PaymentStatus = 'CANCELED';
$result = $api->CardPreAuthorizations->Update($preAuth);
if ($result->PaymentStatus === 'CANCELED') {
echo "Pre-authorization canceled successfully";
}
Pre-authorizations typically expire after 30 days. Make sure to capture the funds before the expiration date.
The full pre-authorized amount is reserved on the user’s card. If you capture a smaller amount, the remaining funds will be released automatically.
