> **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 an overview of the entire site, 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
[Integration quick start guide](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

#### API client

Download the following files. They are in the
[Postman collection format](https://developer.vippsmobilepay.com/docs/knowledge-base/api-collections.md), so you can use them in Postman or import them
into another API client.

Update the environment with your own values for the API keys and international mobile number. *Don't store production keys in the cloud.*

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

**TIP**

If you are using Bruno with multiple environments together, you may see conflicts and strange behavior. To avoid this,
import your environment file into each collection, instead of using it as a global environment.

#### curl

No setup is needed. Continue to [Step 2](#step-2---get-an-access-token).

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

#### API client

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

#### API client

```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 be redirected back at all. 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].

#### API client

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

#### API client

```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].

#### API client

```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].

#### API client

```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].

#### API client

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