Place a hold for a payment
When you create a payment, your consumer authorizes the payment with the payment method and Mollie automatically collect the funds for you.
With certain payment methods you can break this process up into two separate steps. First, you gather the consumerβs authorization to place a hold for a specified amount on their account. Then at a later point you can decide whether you want Mollie to collect (capture) the pending funds either fully or partially, or to cancel (void) the authorization.
Placing a hold is recommended in cases where you are not yet sure up front if and when you will be able to fulfil the order completely. It reduces the risk of chargebacks and operational efforts of handling refunds in case you cannot fulfil the order.
Payment method support
Mollie offers the ability to manually capture for several payment methods. For some methods you will always need to capture manually.
Payment method | Automatic Capture | Manual Capture |
---|---|---|
Cards | β | β |
Klarna | β | β |
Billie | β | β |
Riverty | β | β |
Requesting an authorization-only payment
To place a hold, simply create a payment via the Create payment endpoint with captureMode
set to manual
.
curl -X POST https://api.mollie.com/v2/payments \
-H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
-d "amount[currency]=EUR" \
-d "amount[value]=10.00" \
-d "description=Order #12345" \
-d "redirectUrl=https://webshop.example.org/order/12345/" \
-d "method=creditcard" \
-d "captureMode=manual"
Have your customer authorize the payment by redirecting them to the checkout URL just like they would complete a regular payment. See the guide on building your own checkout for more details.
Once your customer authorizes the payment, the payment status will change to authorized
.
Mollie Checkout
When you do not provide a payment method, your customer will be directed to Mollie Checkout. If the customer completes the payment with a payment method that does not support manual capture, the payment status will be
paid
.
Capturing the authorized funds
To collect the funds that the consumer authorized, you can create a capture on the payment using the Create capture endpoint. For most payment methods a capture can either be for the full amount or for a reduced amount. If you leave the amount field empty, Mollie will capture the full authorized amount. You can optionally provide a description
. If not provided, Mollie automatically generates one that uses the description and id of the related payment.
curl -X POST https://api.mollie.com/v2/payments/tr_.../captures \
-H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
-d "amount[currency]=EUR" \
-d "amount[value]=10.00" \
-d "description=Capture for order #12345"
Riverty only supports full captures.
Captures have their own status. We will call your webhook when the status changes.
Status | Description |
---|---|
pending | The capture is created but is not yet processed, this is the initial status. |
succeeded | The capture was successful. The payment status will change to paid if there is no authorized amount available anymore. |
failed | The capture failed. For example, the capture will be rejected when the authorization has expired. Please refer to the βAuthorization expiration windowβ section below for further details. |
Multiple captures
Some payment methods support multiple captures. When a partial capture succeeds, the remaining authorized amount will still be available to capture at a later time. The payment will therefore remain in the authorized
state. Once the full amount has been captured or the authorization is not longer valid, the status of the payment will change to paid
.
Payment methods that do not support multiple captures will immediately transition to paid
and the remaining authorized amount will be released.
Payment method | Multiple Captures |
---|---|
Cards | β * |
Klarna | β |
Billie | β |
Riverty | β |
*Multiple Captures for Cards is by default deactivated. To activate multiple capture you need to requests this feature from your Mollie contact person.
Release an authorization
To release an authorization, cancel the payment in the Mollie Dashboard or call the release-authorization
endpoint on a payment that has a status of authorized
.
curl -X POST https://api.mollie.com/v2/payments/tr_.../release-authorization \
-H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
Releasing an authorization will release the full remaining amount.
Mollie will do its best to process release requests, but we cannot guarantee that requests will succeed. It is up to the issuing bank if and when the hold will be released.
If the request does succeed, the payment status will change to canceled
for payments without captures. If there is a successful capture, the payment will transition to paid
.
Authorization expiration window
An authorized payment is a guaranteed amount, yet authorizations are generally not meant to remain open for a longer period. The exact allowed authorization window depends on the payment method and/or type of card your customer used. Below an overview of the default expiration window.
Payment method | Expires after |
---|---|
Cards Mastercard | 30 days |
Cards Visa | 7 days |
Cards American Express | 7 days |
Cards Cartes Bancaires | 30 days |
Klarna | 28 days |
Billie | 28 days |
Riverty | 30 days |
It is highly recommended to capture payments as soon as you can fulfil the order and within the recommended time period. If you do not capture a payment in time the authorization will expire and you will not be able to collect the funds.
The Payments API will include a captureBefore
field on authorized payments that indicates by when you need to capture the payment, to prevent you from being unable to capture the funds. It is not possible to extend the authorization period.
When the authorization expires, the payment status will change to expired
for payments without captures. If the payment was partially captured, the payment will transition to paid
.
Extending the authorization date, also known as an incremental authorization, is not supported.
Delayed automatic capturing
Delayed automatic capture is only available for card payments.
In some cases you may want Mollie to always capture the funds after a number of days, unless you explicitly cancel the authorization in the meantime.
In these cases you can set captureMode
back to automatic
, and provide a captureDelay
. The payment will then first move to authorized
, and after the delay you specified Mollie will automatically capture the funds. As mentioned, you will still be able to either cancel the payment or to use the Captures API to manually capture the payment before the automatic capture is executed by Mollie.
Since the exact authorization window depends on the card used by the consumer, and the card is not known up front, we only support automatic capturing for up to 7 days after the authorization.
curl -X POST https://api.mollie.com/v2/payments \
-H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
-d "amount[currency]=EUR" \
-d "amount[value]=10.00" \
-d "description=Order #12345" \
-d "redirectUrl=https://webshop.example.org/order/12345/" \
-d "method=creditcard" \
-d "captureDelay=2 days"
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");
$payment = $mollie->payments->create([
"amount" => [
"currency" => "EUR",
"value" => "10.00"
],
"description" => "Order #12345",
"redirectUrl" => "https://webshop.example.org/order/12345/",
"method" => "creditcard",
"captureMode" => "manual"
]);
Updated 12 days ago