> **Description:** A step-by-step guide to quickly implement and test the PSP API integration, including authentication setup, basic API calls, and essential features for processing Vipps payments.

# Vipps PSP API quick start

As a Payment Service Provider, you can use the PSP API to initiate a PSP payment and get details or update the status of this payment.

## Prerequisites

**End of life**

This API doesn't have any set end of life yet, but is receiving critical maintenance only. Long term support for PSPs will be served by the [ePayment API](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/README.md). No new integrations to this API will be approved.

### Test sales unit

You must be a [Payment Service Provider (PSP) partner](https://developer.vippsmobilepay.com/docs/partner/README.md) with Vipps MobilePay.
You will receive an email with your test credentials from our partner team.

The PSP API is available for testing in the [Test environment](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md).

### Service endpoint

You must expose an endpoint where Vipps can post the network token.

Once the Vipps user has confirmed the payment in the Vipps app,
Vipps shares the network token with the PSP by posting to the
[`POST:makePaymentUrl`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml),
where `makePaymentUrl` is the service endpoint you have provided.

For details, see:

* [makePaymentUrl](https://developer.vippsmobilepay.com/docs/APIs/psp-api/vipps-psp-api.md#makepaymenturl)
* [`POST:makePaymentUrl`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml)

## Your first Payment

### Step 1 - Setup

The example values in this guide must be replaced with your own values.
This applies to API keys, HTTP headers, references, phone numbers, and similar values.
Note that any currency amount must be an Integer value minimum 100 in øre.

Get these API credentials for your PSP account:

* `client_id` - Client ID, required for getting the access token.
* `client_secret` - Client secret, required for getting the access token.
* `Ocp-Apim-Subscription-Key-PSP` - PSP subscription key, required for all requests.
* `PSP-ID` - Your PSP ID, provided by Vipps MobilePay. Required for all requests.

You will also need the following values per payment:

* `merchantSerialNumber` - The MSN of the merchant you are processing payments for. Each merchant you onboard via the [PSP Merchant API](https://developer.vippsmobilepay.com/docs/APIs/psp-merchant-api/README.md) gets their own MSN.
* `mobileNumber` - The customer's mobile number, needed only for `Initiate a PSP Payment`.
* `makePaymentUrl` - PSP-provided URL where Vipps sends the card token after the customer approves payment.
* `pspRedirectUrl` - URL the customer is redirected to after approving or rejecting the payment.

### Step 2 - Get an access token

Get an access token by sending the
[`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml) request.

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

Use the `access_token` value as the Bearer token in the `Authorization` header of all subsequent requests.

### Step 3 - Initiate the payment

Initiate a payment with:
[`POST:/psp/v3/psppayments/init/`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml). For example:

```bash
curl -X POST "https://apitest.vipps.no/psp/v3/psppayments/init" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-PSP-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-d '{
  "pspTransactionId": "abcABC12345",
  "merchantOrderId": "abcABC-12345",
  "customerMobileNumber": "12345678",
  "amount": "49900",
  "currency": "NOK",
  "pspRedirectUrl": "https://example.com/page-seen-after-payment",
  "makePaymentUrl": "https://example.com/your-endpoint-for-card-data",
  "makePaymentToken": "YOUR-AUTHORIZATION-HEADER-FOR-makePaymentUrl-optional",
  "paymentText": "OrderId abcABC-12345 from example.com."
}'
```

You should get a link in the response. Paste the link into the browser to open the
[Vipps 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*.

A push notification will be presented in the Vipps app on your phone.

When you approve the payment, Vipps automatically reserves the payment and provides confirmation of the successful payment.

### Step 4 - Show the order confirmation

You should be redirected back to the specified `pspRedirectUrl` URL under a "best effort" policy.
On that page, show the order confirmation.

### Step 5 - Receive the user's card token

When the payment is confirmed in the Vipps app,
Vipps will try to share the user's card token with you by posting to the
[`POST:makePaymentUrl`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml).

### Step 6 - Process the payment with the card token

After receiving the card data, you can use the card token to process the payment through the acquirer.

Vipps is not involved in the actual payment, Vipps only provides the PSP with the card token.

### Step 7 - Update the status of the payment in Vipps

Update the status of the payment by sending the
[`POST:/psp/v3/psppayments/updatestatus`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml) request.
For example:

```bash
curl -X POST https://apitest.vipps.no/psp/v3/psppayments/updateStatus \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-d '{
  "transactions": [
   {
      "pspTransactionId": "abcABC12345",
      "status": "CAPTURED",
      "amount": "49900",
      "currency": "NOK",
      "paymentText": "Transaction updated"
   }
  ]
}'
```

### Step 8 - Get the details of a payment

To see the details about a transaction, send the
[`GET:/psp/v3/psppayments/{pspTransactionId}/details`](https://developer.vippsmobilepay.com/redocusaurus/psp-swagger-id.yaml) request.

```bash
curl -X GET https://apitest.vipps.no/psp/v3/psppayments/{pspTransactionId}/details \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
```

Example response:

```json
{
"pspTransactionId": "abcABC12345",
"merchantOrderId": "abcABC-12345",
"transactionSummary": {
  "capturedAmount": 49900,
  "remainingAmountToCapture": 0,
  "refundedAmount": 0,
  "remainingAmountToRefund": 49900
},
"transactionLogHistory": [
   {}
  ]
}
```

## Next steps

See the [PSP API guide](https://developer.vippsmobilepay.com/docs/APIs/psp-api/vipps-psp-api.md) for concepts and details.

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