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 until it is captured or canceled. The funds stay in the customer's account, but are not available to them.

Payment reserved

The payment details will show the authorized amount in faint gray (e.g., 500 kr).

Capture​

After you receive a notification that payment was reserved, or you retrieve payment, and it has a state reserved, you must capture payment in order to end the flow and receive the money with a nightly transfer.

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.

CAPTURE CONSIDERATIONS

Do not capture before the product or service is provided to the customer, as per the capture regulations.

If it's not captured within the payment time limits, it will be automatically cancelled.

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.

The payment transactions are shown in reverse order, where the oldest transaction is at the bottom of the list. So, here you see the authorized amount at the bottom of the Transactions list in faint gray (e.g., 500 kr).

The payment transfer (i.e., capture) is reflected as a negative transaction in red (e.g., -500 kr), so the user can see that you have transferred 500 kr from their account.

If you later refund an amount (perhaps there was a mistake), the refunded amount will be shown in green (e.g., 250 kr) at the top of the list. The total amount paid will be updated to show the new amount.

Payment captured and partially refunded

In cases where the final amount owed is not known at the time of the payment request (e.g., for vending machines, charging stations, and taxis), it's common to reserve a larger (but reasonable) amount, so they have authorization to cover the cost of the service. Once the true amount is known, they capture this amount and cancel the remaining.

In this case, you see that the captured amount (e.g., -250 kr) is less than the original authorized amount (e.g., 500 kr). The actual amount paid is also updated.

Payment partially captured and cancelled

info

You can capture a payment within 90 days (MobilePay) or 180 days (Vipps). If it is not captured or cancelled within this time, it will be automatically cancelled.

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​

note

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

PAYMENT TIME LIMITS

If it's not captured or cancelled within the payment time limits, it will be automatically cancelled.

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.

note

For MobilePay, partial capture availability is limited. At this point you have 2 options:

You can capture the whole reserved amount. You can do a partial capture and only capture the amount you need. The remaining amount will be returned to the user.

The partial capture is normally confirmed in the bank after 3-10 days, but it sometimes takes even longer. When this is done, the bank will make the remaining (250 NOK) available in the customer's account again. This process depends entirely on the customer's bank, and we can't speed it up.

Banks keep reservations for the same number of days regardless of whether there has been one or more captures. Banks do not extend the reservation if a partial capture has been made.

If a partial capture has been made, the bank cancels the reservation for the remaining amount. If no capture has been made, the entire reserved amount is cancelled. Banks "count the days" from when the reservation was made, so the merchant must make the capture, or all captures, before the reservation expires.

See: Settlements

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 the 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?​

Please see payment time limits.

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 was automatically cancelled. See payment time limits.

A payment is reserved for a limited number of days before 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.
note

It's recommended to use reserve capture which is 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").

When should I use "Direct Capture"?​

Only the eCom API and Recurring API support 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:

Further reading​

The following APIs have capture methods:

If you have used Checkout API to create the payment, use either the ePayment or Recurring API to reserve or capture payments.

Help us improve our documentation

Did you find what you were looking for?