Skip to main content

Capture payment

View as Markdown (opens in a new tab)
Install AI tools

Our plugin gives your assistant up-to-date guidance for payments and login. Full instructions

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps@agent-toolkit

See Capture for what capture is and when you're allowed to do it. This page covers how to capture a payment using the ePayment API.

You can capture:

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

Authorization​

All ePayment API requests must include a valid Bearer token in the Authorization header. See Authorization for how to obtain one.

Creating a capture request​

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 the 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.

Check capture success

Verify that capturedAmount in the response matches the amount you intended to capture — the HTTP status code alone is not sufficient. Do not send goods to the customer until you've confirmed the capture succeeded.

See Errors below for the ways a capture can fail.

Handling partial captures​

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.

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.

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 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
      }
   }
}

Related pages:

Errors​

If a capture fails, do not send goods to the customer. The response body's extraDetails field contains an ErrorCode identifying the reason — see Payment errors for the full list of codes and details.

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.

captureGuaranteedUntil​

You can check exactly how long a successful capture is guaranteed for a given payment by reading the captureGuaranteedUntil field from the Get Payment Info response and the epayments.payment.authorized.v1 webhook payload.

Capture attempt deadlines​

The capture attempt deadlines are between 14 - 180 days, but can be shorter under certain circumstances. See General info: Capture attempt deadlines for details.

Last updated on