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.
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.
Once the payment is captured, returning the money requires a refund operation and this may also take a few days. For details about bank payouts and records, see the Settlements section.
You should capture as soon as is legally possible, because some banks will release the funds after some days, making it difficult to capture later. If it's not captured within the payment capture deadlines, it will be automatically cancelled.
However, be aware that it isn't legal to capture before the product or service is provided to the customer, as per the capture regulations.
If you do not plan to capture the entire amount, please make sure to cancel the remainder as soon as possible.
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.
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.
If it's not captured within the payment capture deadlines, it will be automatically cancelled.
Capture types include:
- Reserve capture
- Partial capture
- Direct capture (eCom API and Recurring API only)
Reserve capture
Reserve capture is the default way to capture payments, 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
Limited availability for MobilePay. You must inquire during onboarding or contact customer service.
If it's not captured or cancelled within the payment capture deadlines, 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.
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.
For more details about when payments are transferred, 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:
Capture regulations
According to regulations, you must not capture a payment until the product or service is provided to the customer.
We comply with local applicable laws as well as guidance from the Norwegian Data Protection Authority, Datatilsynet, and other relevant local authorities.
Payment capture deadlines
If payments are not captured within the below deadlines, they will be automatically cancelled.
In Norway, the time limit for capturing payments is 180 days. Be aware: Credit card payment deadlines may vary.
In Denmark and Finland, the time limit for capturing payments is 14 days.
If you require more time, contact your KAM or customer service. You may also consider using Checkout which can provide the possibility for later captures.
Attempting to handle an older payment will result in a HTTP 400 Bad Request.
Late capture for MobilePay sales units
This is feature must be approved for your sales unit on a case-by-case basis, and it requires a legitimate need for it to run your business. The typical scenario is for online retail, where goods are delivered later (for example, when the product is not in stock), and for this reason, capture must also be done later.
Contact your KAM or customer service.
We cannot guarantee successful captures from 15 to 180 days after reservation, so there is chance of a failed capture, for example in the case of insufficient funds, expired cards, etc. See: Card payment deadlines may vary.
Credit card payment deadlines may vary
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. We will try to clarify it more in the near future.
-
VISA reservations are usually only valid for 5-7 days (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.
Attempting to capture an older payment will result in a
HTTP 400 Bad Request.
Reserve and capture FAQ
For how long is a payment reserved?
Please see payment capture deadlines.
Why does capture fail?
The most common reasons are:
- 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.
- Attempt at capturing a payment that is not reserved: The user has not approved the payment.
- Attempt to capture a payment that was automatically cancelled. See payment capture deadlines.
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:
- The merchant initiates a payment of 1000 NOK
- The user confirms the 1000 NOK payment in the app
- 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.
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
/cancelcall 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
/refundcall, 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 don't yet use the Management API, you can ask the merchant to create a portal user for you. Then, you can check on behalf of the merchant.
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.
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:
- When should I use "Direct Capture"?
- What is the difference between "Reserve Capture" and "Direct Capture"?
API guides
The following APIs have capture methods:
- ePayment API: Capture a payment
- Recurring API: Capture a charge
- eCom API (Vipps only and deprecated): Capture a payment
If you have used Checkout API to create the payment, use either the ePayment or Recurring API to reserve or capture payments.