Capture payment

Capture is the process of moving funds from the customer's account to the merchant's account.
Depending on your bank, this can take a few days.

You can capture:

The full amount at once (full capture), or
Portions of the total in several steps (partial capture)

Full vs. partial capture

Full capture: Capture the entire authorized amount in a single operation.
Partial capture: Capture the total in multiple operations, until the full amount is captured.

For additional context, see Knowledge base: Capturing a payment.

Payment capture deadlines

Although you cannot capture before the product or service is provided, as per the capture regulations, you should capture funds as soon as legally possible.

If payments are not captured within the below time limits, 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.

For more details, see Knowledge base: Payment capture deadlines.

Create a capture request

After the goods or services have been delivered or shipped, capture the payment using
POST:/epayment/v1/payments/{reference}/capture. The Idempotency-Key header is required.

Specify the amount to capture in the modificationAmount parameter of request body. For example:

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 49900
  }
}'

If successful, the API returns a summary of payment status. For example:

{
   "aggregate":{
      "authorizedAmount":{
         "currency":"NOK",
         "value":49900
      },
      "cancelledAmount":{
         "currency":"NOK",
         "value":0
      },
      "capturedAmount":{
         "currency":"NOK",
         "value":49900
      },
      "refundedAmount":{
         "currency":"NOK",
         "value":0
      }
   }
}

This shows that the customer authorized 499 NOK and you have captured 499 NOK.

Webhooks Register for the webhook event epayments.payment.captured.v1 to be notified when the capture is complete. For setup and event details, see webhooks.

Partial capture

Finnish and Danish sales units

Partial capture through the ePayment API must be enabled for Finnish and Danish sales units. If you need partial capture for your Finnish or Danish sales unit, inquire during onboarding or contact customer service.

Alternatively, you can use the Checkout API which automatically enables you to carry out partial captures without the need for prior approval. In this scenario, create a checkout session to initiate your payment, and do multiple partial captures for this payment using the ePayment API capture endpoint.

Partial capture lets you capture part of the reserved amount instead of the full total. You can make multiple captures until the authorized amount is fully used, or you can cancel the remaining amount.

This is useful when products are delivered at different times, or if the final amount isn't known in advance.

You should cancel any unused reserved amount as soon as possible to release funds back to the customer.

Creating a partial capture request

This is exactly the same as the regular capture request example above, except that you specify a lower amount value. Specify the amount you want to capture in the POST:/epayment/v1/payments/{reference}/capture request.

An example of a partial capture request body (capturing 100 NOK of the 499 NOK reserved):

{
   "modificationAmount":{
      "currency":"NOK",
      "value":10000
   }
}

Once the capture is completed the aggregate will be updated to reflect this, for example:

{
   "aggregate":{
      "authorizedAmount":{
         "currency":"NOK",
         "value":49900
      },
      "cancelledAmount":{
         "currency":"NOK",
         "value":0
      },
      "capturedAmount":{
         "currency":"NOK",
         "value":10000
      },
      "refundedAmount":{
         "currency":"NOK",
         "value":0
      }
   }
}

Use the ePayment cancel endpoint: POST:/epayment/v1/payments/{reference}/cancel endpoint to release any remaining funds.

For example, this request cancels the entire payment.
Note: Once cancelled, the payment cannot be captured.

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

The response will summarize the payment's status. In this example, 499 NOK was authorized, 100 NOK was captured, and 399 NOK was cancelled:

{
   "aggregate":{
      "authorizedAmount":{
         "currency":"NOK",
         "value":49900
      },
      "cancelledAmount":{
         "currency":"NOK",
         "value":39900
      },
      "capturedAmount":{
         "currency":"NOK",
         "value":10000
      },
      "refundedAmount":{
         "currency":"NOK",
         "value":0
      }
   }
}

Payment capture deadlines​

Create a capture request​

Partial capture​

Creating a partial capture request​

Payment capture deadlines

Create a capture request

Partial capture

Creating a partial capture request