Skip to main content

Reserve and capture

Reserve​

When a user accepts a payment request, it will go into the reserved state. It will remain there for up to 14 days (MobilePay) or 180 days (Vipps) until it is captured or canceled. The funds stay in the customer's account, but are not available to them.

Capture​

warning

You must capture within 14 days (MobilePay) or 180 days (Vipps) or the payment will be cancelled.

Capture is the operation that moves the money from the customer's account to the merchant's account. This can take a few days, depending on your bank. See Settlements for more details about settling payments.

Once the payment is captured, returning the money requires a refund operation and this may also take a few days. See refunds for details.

tip

Check the response of the capture call. It is only successful when the response is HTTP 200 OK. Attempting to capture an older payment will result in a HTTP 400 Bad Request.

Always use an idempotency key in the capture call because this ensures that the same request doesn't get created more than once.

For API details:

Reserve capture​

The default way to capture is the reserve capture, which works for all types of payments.

In this scenario, when a user authorizes a payment, it goes into the reserved or authorized state. You can then capture it at a later time, or you can cancel it.

For API details:

Partial capture​

info

You must capture within 14 days (MobilePay) or 180 days (Vipps) or the payment will be cancelled.

Limited availability for MobilePay. You must inquire during onboarding or contact customer service.

With partial capture, a part of the original authorized amount is captured, and the remaining amount continues to be available for capture.

Partial capture may be collected many times, for as long as there is a remaining reserved amount. You should capture or cancel the remainder when the order is complete. See Cancel a partially captured order.

For API details:

Direct capture​

Direct capture is only available in the Recurring API and eCom API.

When direct capture is activated, all payment reservations will instantly be captured. This is intended for situations where the product or service is immediately provided to the customer, and there is no chance that the service is not available or sold out, e.g. digital services. Direct capture requires additional compliance checks of the merchant. For eCom API, direct capture requires additional compliance checks of the merchant. For Recurring API, direct capture is enabled by default.

For API details:

Reserve and Capture FAQ​

For how long is a payment reserved?​

info

A payment is reserved for a maximum of 14 days (MobilePay) or 180 days (Vipps). After this time, it is automatically cancelled.

It varies. We don't control the behavior of the customer's card or account. The details may change, but the information below is the best we can offer.

  • VISA reservations are valid for 7 days (but only 5 for Visa Electron). The banks will release the reservation after 4-7 days, but if the capture is done within the 7 days, VISA guarantees that the capture will succeed. Our PSP is Adyen, and they have some documentation for VISA reservations.

  • MasterCard reservations are valid for 30 days. The banks may release the reservation before this, but if the capture is done within the 30 days, MasterCard guarantees that the capture will succeed. Our PSP is Adyen, and they have some documentation for Mastercard reservations.

We can't and don't automatically change the status of a reservation.

If a capture attempt is made more than 7 days (VISA) or 30 days (MasterCard) after the payment has been initiated, and the reservation has been released by the bank in the meantime, we will make a new payment request to the bank. If the account has sufficient funds, the payment will be successful.

If the user's account has insufficient funds at this time, the payment will either succeed and put the customer's card/account in the negative (as an overdraft), or fail because the customer's card/account cannot be put into the negative - for example youth accounts. We can't know in advance what will happen.

It is also possible that the card expires, is blocked, etc. somewhere between the time of reservation and the time of capture. We can't know in advance what will happen.

In many cases the bank will have a register of expired reservations, and they will force the capture through if the account allows this. This will put the account in the negative.

Customers may, understandably, be dissatisfied if the capture puts their account in the negative, so please avoid this.

Capture can be made up to 180 days after reservation. Attempting to capture an older payment will result in a HTTP 400 Bad Request.

Why does capture fail?​

The most common reasons are:

  1. Attempt at capturing a higher amount than the one that has been reserved: The user has approved a payment in the app, but you attempt to charge more.
  2. Attempt at capturing a payment that is not reserved: The user has not approved the payment.
  3. Attempt to capture a payment that is automatically cancelled. The time period for capturing the amount is 14 days (MobilePay) or 180 days (Vipps), before the payment is automatically cancelled.
info

A payment is reserved for a maximum of 14 days (MobilePay) or 180 days (Vipps). After this time, it is automatically cancelled.

All failed capture attempts get an error response from our API. The response contains the details of why the capture failed.

If the reserved amount is too low for shipping costs to be included, the capture will fail. The reserved amount must at least as high as the amount that is captured.

Example: If the value of the shopping cart is 1000 NOK, and the reserved amount is 1200 NOK, the shipping cost can be maximum 200 NOK to be within the reserved amount of 1200 NOK. If the shipping cost is 300 NOK, a capture of 1000 + 3000 NOK = 1300 NOK will fail.

It is not possible to capture more than the reserved amount, as that would make this sequence possible:

  1. The merchant initiates a payment of 1000 NOK
  2. The user confirms the 1000 NOK payment in the app
  3. The merchant captures 50 000 NOK from the user

Similarly: It is not possible to capture an amount that is not reserved, as that would make it possible to charge a user's card without requiring the user to confirm the payment first.

What is the difference between "Reserve Capture" and "Direct Capture"?​

Only the eCom API and Recurring API support direct capture.

  • Reserve capture is the default. When you initiate a payment it will be reserved until you capture it. The capture can be done a few seconds later, or several days later.
  • When direct capture is activated, all payment reservations will instantly be captured. This is intended for situations where the product or service is immediately provided to the customer, and there is no chance that the service is not available or sold out, e.g. digital services. Direct capture requires additional compliance checks of the merchant.
info

It's recommended to use reserve capture almost exactly like direct capture: Just do the capture immediately after the reservation. The user experience is exactly the same.

Some things to consider:

  • If a payment has been reserved (as with "reserve capture"), the merchant can make a /cancel call to immediately release the reservation and make available in the customer's account.
  • If a payment has been captured (as with "direct capture"), the merchant has to make a /refund call, and it then takes several days before the amount is available in the customer's account.
  • With "reserve capture" it is possible to reserve a higher amount and only capture a part of it (useful for electric car charging stations, etc.). It is also possible to capture the full amount with multiple captures ("partial capture").

See:

When should I use "Direct Capture"?​

You should probably use "reserve capture", and just do the capture right after the reserve. This has some benefits, see the first link below.

See:

How can I check if I have "reserve capture" or "direct capture"?​

We can no longer manually check this for merchant or partners.

All merchants can log in on portal.vippsmobilepay.com, as described on merchant portal, and check the capture type for all their sales units in the Developer section.

You can also find information on how to change capture type there. We require BankID, FTN, or MitID login for this, as "direct capture" requires additional compliance checks.

If you are a partner and want to check a merchant, see the Management API.

If you are a partner and do not yet use the Management API, you can ask the merchant to create a user for you on portal.vippsmobilepay.com, so you can check on behalf of the merchant as described in detail with screenshots.

If you are not able to log in on portal.vippsmobilepay.com you can make a small payment (2 NOK), check the payment with GET:/ecomm/v2/payments/{orderId}/details, and cancel (if it was RESERVE and reserve capture) or refund (if it was SALE and direct capture).

How do I turn direct capture on or off?​

You can't turn direct capture on or off as a merchant. A sales unit can only have one capture type, and we must configure that.

note

We only offer direct capture to merchants that use Vipps MobilePay through a partner, and for merchants that have a Key Account Manager. Direct capture must be requested by the partner from the partner manager, or by KAM merchants from the Key Account Manager.

See:

This is applicable to:

Help us improve our documentation

Did you find what you were looking for?