# MobilePay for Unified Payments API

To accept MobilePay payments, follow these steps:

1. Request a payment.
2. Redirect the customer. <br>
If you process a manual-capture payment, you must also capture the payment.

---

## Request a payment

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint:

**Live**

`POST` `https://{prefix}.api.checkout.com/payments/`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/`

### Request example

```json
{
  "source": {
    "type": "mobilepay"
  },
  "currency": "DKK",
  "amount": 1000,
  "reference": "ORD-5023-4E89",
  "customer": {
    "phone": {
      "country_code": "45",
      "number": "71555804"
    }
  },
  "processing_channel_id": "pc_67nslxo3zumulkoxl6p4c6paay",
  "success_url": "http://www.example.com/success.html",
  "failure_url": "http://www.example.com/failure.html",
  "capture": true
}
```

### Response example

```json
{
  "id": "pay_py2itltbdu3ebnvd7heh7u6i4e",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
    "phone": {
      "country_code": "45",
      "number": "71555804"
    }
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_py2itltbdu3ebnvd7heh7u6i4e"
    },
    "redirect": {
      "href": "https://apitest.vipps.no/dwo-api-application/v1/redirectURL"
    }
  }
}
```

If you receive a `202 Accepted` response, with the `status` field set to `Pending`, your request was successful.

---

## Redirect the customer

Redirect the customer to the `_links.redirect.href` URL provided in the payment response. The customer can authenticate with MobilePay and complete the payment.

---

## Manually capture the payment `Optional`

A successful authorization places a hold on the customer's funds. With the manual capture flow, you can capture the funds at a later point in time. For example, if you need to verify that the item the customer purchased is still in stock.

> **Note**
>
> Perform the manual capture when you ship the items.

Checkout.com can capture the full amount for the payment or perform multiple partial captures. For partial captures, include information about the items in the `items[]` object.

- If the capture amount is equal to the authorized amount, we consider the capture full and final.
- If the capture amount is less than the authorized amount and your capture request:
  - Includes `"capture_type": "Non-Final"`, we do not release the remaining authorized amount
  - Does not include `"capture_type"`, or includes `"capture_type": "Final"`, we release the remaining authorized amount

For more information on capturing payments, see [Capture a payment](https://www.checkout.com/docs/payments/manage-payments/capture-a-payment.md).

### Full capture

If you want to capture the full amount, call the [Capture a payment](https://api-reference.checkout.com/tag/Payments/#operation/captureAPayment) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter.

**Live**

`POST` `https://{prefix}.api.checkout.com/payments/{id}/captures`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/captures`

#### Response example

```json
{
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}
```

If your request is successful, you receive a `202 Success` response code.

---

## Get details about a payment

To retrieve details about the payment, call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter.

---

## Refund a payment

MobilePay supports both partial and full refunds.

You can only refund manually captured payments if:
- You performed a final capture.
- The payment was voided after a partial or non-final capture.

For more information, see [Refund a payment](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md).

Call the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter.

**Live**

`POST` `https://{prefix}.api.checkout.com/payments/{id}/refunds`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`

### Request example

```json
{
  "amount": 100
}
```

### Response example

```json
{
   "actionId": "act_cxpffngdvouvabegyy3asiuou",
   "_links": {
       "payment": {
           "href": "https://{prefix}.api.checkout.com/payments/pay_ok7yhvutuylevnatk3x3dxviq4"
       }
   }
}
```
---

## Void a payment

To void an authorized payment that you have not captured yet, call the [Void a payment](https://api-reference.checkout.com/tag/Payments/#operation/voidAPayment) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter:

**Live**

`POST` `https://{prefix}.api.checkout.com/payments/{id}/voids`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/voids`

If you receive a `202 Void accepted` response, your void request has been accepted for processing. To get the full void response, you must subscribe to the `payment_voided` webhook.

If there was a problem with your request, you receive an error response such as `422 Invalid data was sent`.

For more information, see [Void a payment](https://www.checkout.com/docs/payments/manage-payments/void-a-payment).

### Response example

```json
{
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "reference": "ORD-5023-4E89",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}
```

If there was a problem with your request, you receive an error response such as `422 Invalid data was sent`.

## Test your integration

To test your integration, you need the Vipps test app and a test phone number.

> **Information**
>
> To test MobilePay payments, you must use the Vipps test app. This is because both payment methods share the same payment flow and API.

To download and configure the Vipps test app:

1. Download the [test app](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment/#app-installation).
2. Install and launch the _Vipps MT_ app.
2. Choose _Norway_ in the country selection screen.
3. In the age check, select _Above 15_.
4. For the test user, use the following data:
    * Set _national identity number_ to _22054701318_.
    * Set _Test phone number_ to _+4799293473_.
Your normal Vipps or MobilePay user is not available in the test environment.
5. On the _Verify your number_ screen, use the PIN `1236`.
6. Select _Next_.
7. On the _Enter your code_ screen, use the code `1236`.
8. Enable Touch ID and confirm with PIN `1236`.
9. Accept push notifications.

After you've registered for the test app, send a payment to the Sandbox environment using the phone number `+4799293473`:

```json
{
  "source": {
    "type": "mobilepay"
  },
  "currency": "DKK",
  "amount": 1000,
  "reference": "ORD-5023-4E89",
  "customer": {
    "phone": {
      "country_code": "45",
      "number": "71555804"
    }
  },
  "processing_channel_id": "pc_67nslxo3zumulkoxl6p4c6paay",
  "success_url": "http://www.example.com/success.html",
  "failure_url": "http://www.example.com/failure.html",
  "capture": true
}
```

---

## Response codes

When integrating MobilePay payments, you can receive the following response codes:

| Response code | Response text | Additional information |
| --- | --- | --- |
| `20004` | Card should be captured |  |
| `20006` | Error / Invalid request parameters |  |
| `20013` | Invalid value/amount | The payment failed due to a technical issue. If the issue persists, contact us. |
| `20040` | Requested function not supported |  |
| `20068` | Response received too late / Timeout | The payment failed due to a technical issue. Try again with the same card, or use a different card. |
| `20068` | Internal error |  |
| `20106` | Unsupported currency |  |
| `20109` | Transaction already reversed (voided) |  |
| `20109` | The previous message for a repeat or reversal was located, but the repeat or<br>reversal data is inconsistent with the original message. |  |
| `20109` | Capture is larger than initial authorized value |  |
| `20110` | Authorization completed |  |
| `20111` | Transaction already reversed | The payment reversal has already been processed. |
| `20115` | Missing / Invalid lifetime |  |
| `20118` | Transaction pending | The payment failed due to a technical issue. If the issue persists, contact us. |
| `20120` | Invalid customer/user | The payment failed due to a technical issue. If the issue persists, contact us. |
| `20156` | Requested function not supported by the acquirer |  |
| `20157` | Invalid merchant configurations - Contact Support |  |
| `20158` | Refund validity period has expired |  |
| `30020` | Invalid amount | The payment failed due to a technical issue. If the issue persists, contact us. |