> **Description:** Get your first payment integration running with our guided setup and example code.

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# Quick start

This guide takes you through all the ePayment API requests.

## Before you begin

Sign up as an organization with Vipps MobilePay and get your API keys.

#### Merchants

You will need the [sales unit API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md) for a *test* sales unit:

* `client_id` - Client ID for the sales unit.
* `client_secret` - Client secret for the sales unit.
* `Ocp-Apim-Subscription-Key` - Subscription key for the sales unit.
* `merchantSerialNumber` - The unique ID (MSN) for the sales unit.

#### Partners

[Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#partner-keys) only work in the production environment.
To follow this guide in the test environment, use the test sales unit API keys provided in your welcome email.

In production, partner keys are used exactly like sales unit API keys, with one difference:
the `Merchant-Serial-Number` header is *required*, not just recommended.

If you're new to the platform, see
[Getting started](https://developer.vippsmobilepay.com/docs/getting-started.md)
for information about API keys, product activation, and the test environment.

The example values in this guide must be replaced with the values for your sales unit and user.
This applies to API keys, HTTP headers, references, phone numbers, and similar values.

## Your first payment

### Step 1 - Setup

If using Postman, download the following files and import them into Postman.
Select the global environment as your active environment and update with your own values for the API keys and international mobile number. *Don't store production keys in the cloud.*

* [Download ePayment API Postman collection](https://developer.vippsmobilepay.com/tools/epayment-api-postman-collection.json)
* [Download Global Postman environment](https://developer.vippsmobilepay.com/tools/global-postman-environment.json)

### Step 2 - Get an access token

For all the following, you will need an `access_token` from the
[Access Token API](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/README.md):
[`POST:/accesstoken/get`][access-token-endpoint].
This provides you with access to the API.

#### Postman

```text
Send request "Get Access Token"
```

#### curl

```bash
curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
--data ''
```

In production, include all `Vipps-System` headers to aid debugging.
See [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for details.

The property `access_token` should be used as the Bearer token in the `Authorization` header of all the following API requests.

### Step 3 - Initiate a payment

Initiate a payment with: [`POST:/epayment/v1/payments`][create-payment-endpoint].
In this example, we use the default user flow, `WEB_REDIRECT`.
This provides you with a link you can click to go to the
[landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md).
When your test mobile number (in MSISDN format)
is provided in `phoneNumber`, it will be prefilled in the form.

#### Postman

```text
Send request "Create Payment - Web redirect"
```

#### curl

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Idempotency-Key: YOU-CREATE-YOUR-IDEMPOTENCY-KEYS" \
-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" \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 1000
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "4712345678"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'
```

### Step 4 - Complete the payment

Open the `redirectUrl` link that is returned, and it will take you to the
[landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md).
The phone number of your test user should already be filled in, so you only have to click *Next*.

You will be presented with the payment in the app, where you can complete the payment and be directed to the specified `returnUrl` under a "best effort" policy.

**NOTE**

We cannot guarantee the user will be redirected back to the same browser or session, or that they will at all be redirected back. User interaction can be unpredictable, and the user may choose to fully close the app or browser.

### Step 5 - Get the payment details

To receive the result of the user action, you may poll the status of the payment via the
[`GET:/epayment/v1/payments/{reference}`][get-payment-endpoint].

#### Postman

```text
Send request "Get payment"
```

#### curl

```bash
curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE \
-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"
```

To verify that a payment has been authorized by the user, check that the `state`
property is marked `AUTHORIZED`. If the user has instead chosen to reject the
payment or chosen to click `cancel` on the landing page or in the app,
the `state` property will be marked `ABORTED`. If the user did not act within
the payment expiration time, the `state` property will be marked `EXPIRED`.

For more details of the lifecycle of the payment session, see the
[`GET:/epayment/v1/payments/{reference}/events`][get-payment-event-log-endpoint] endpoint.

#### Postman

```text
Send request "Get payment event log"
```

#### curl

```bash
curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/events \
-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"
```

### Step 6 - Capture the payment

You can capture the authorized amount with:
[`POST:/epayment/v1/payments/{reference}/capture`][capture-payment-endpoint].

#### Postman

```text
Send request "Capture payment"
```

#### curl

```bash
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": 1000
  }
}'
```

See
[General info: capture](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md)
for more details about the types of captures.

### Step 7 - Refund the payment

To refund the captured amount, either partially or fully:
[`POST:/epayment/v1/payments/{reference}/refund`][refund-payment-endpoint].

#### Postman

```text
Send request "Refund payment"
```

#### curl

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-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": 1000
  }
}'
```

See
[General info: refund](https://developer.vippsmobilepay.com/docs/knowledge-base/refund.md)
for more details about refunds.

### Step 8 - Cancel the payment

You can cancel a reserved amount. If the amount has been captured already,
then you need to use the refund endpoint instead (step 7).

To cancel a payment, send this request:
[`POST:/epayment/v1/payments/{reference}/cancel`][cancel-payment-endpoint].

#### Postman

```text
Send request "Cancel payment"
```

#### curl

```bash
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" \
```

See
[General info: Cancel](https://developer.vippsmobilepay.com/docs/knowledge-base/cancel.md)
for more details about cancellations.

## Next steps

Complete the required [ePayment checklist](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/checklist.md) to integrate the API into your software.

[access-token-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml
[create-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[get-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[get-payment-event-log-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[cancel-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[capture-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[refund-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml
[force-approve-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml