Skip to main content

Payment through company app

The customer pays the taxi company from their app when ordering the taxi and selects to pay with Vipps MobilePay. The amount is reserved until the final amount is known, at which time the payment is captured.

This flow combines multiple products to illustrate the recommended online payment flow.

Prerequisites​

Webhooks for ePayment events​

Register a webhook to alert you when your payment requests are approved.

What are webhooks?

When changes happen to your payment request, events are triggered (for example: Authorized, Terminated, Aborted, Cancelled, Expired, and many more).

You can register to receive these events, which is useful for programming an appropriate and quick response.

The webhook will send a message to your web server at the URL you specify.

Here is an example HTTP POST:

POST:/webhooks/v1/webhooks

{  
    "url": "https://example.com/mystore_website_backend",
    "events": ["epayments.payment.authorized.v1"]
}

Use the secret to authenticate the message with HMAC. For examples, see Webhooks API: Request authentication.

The payload from the ePayment webhooks will be in this form:

{
    "msn": "123456",
    "reference": "24ab7cd6ef658155992",
    "pspReference": "1234567891",
    "name": "AUTHORIZED",
    "amount":
    {
        "currency": "NOK",
        "value": 35000
    },
    "timestamp": "2023-08-14T12:48:46.260Z",
    "idempotencyKey": "49ca711a9487112e1def",
    "success": true
}

Note that the payload of the webhook depends on the originating service, in this case the ePayment API.

Details​

Step 1. Initiate a payment request​

When the customer is ready to pay, initiate a payment request.

The payment request amount should be large enough to cover the cost of the journey. Do not include the receipt yet, since a receipt is immutable and the true amount is not known yet.

This amount will be reserved on the customer's account, and the unused amount will be released when the journey is finished.

Detailed example

To create this payment, you first send a create payment request.

Since the customer is selecting this from an app on their phone, you don't need their phone number. This payment command can do an app-switch and open their app with the payment request. Specify "userFlow": "WEB_REDIRECT" to redirect user to the app.

Specify "customerInteraction": "CUSTOMER_PRESENT".

Here is an example HTTP POST:

POST:/epayment/v1/payments

{
  "amount": {
    "value": 31400,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customerInteraction": "CUSTOMER_PRESENT",
  "reference": 2486791679658155992,
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Travel from Oslo central station to Storo"
}

Step 2. The customer authorizes the payment​

The payment request will appear in the customer's Vipps MobilePay app, where they can select to pay or cancel.

To get confirmation that payment was approved, monitor your webhooks.

Once the payment is approved, update the status in your system.

Step 3. Confirm the order​

Upon authorization, the Vipps MobilePay app should automatically redirect the customer to your app. Confirm that the order has been successful in your app.

Step 4. Capture the amount due​

After the drive is complete, calculate how much the customer owes and do a partial capture.

Check the status of the captured payment.

Detailed example

POST:/epayment/v1/payments/{reference}/capture

With body:

{
  "modificationAmount": {
    "value": 29900,
    "currency": "NOK"
  }
}

Step 5. Cancel remaining amount​

Release the remaining amount from the reservation with a cancel.

POST:/epayment/v1/payments/{reference}/cancel

Step 6. Attach a receipt​

Attach a receipt with the amount paid.

Detailed example

Here is an example HTTP POST:

POST:/order-management/v2/{paymentType}/receipts/{orderId}

For paymentType, use eCom for eCom or ePayment payments. For orderId, use the chargeId of the charge.

Body:

{
  "orderLines": [
    {
        "name": "trip",
        "id": "line_item_1",
        "totalAmount": 29900,
        "totalAmountExcludingTax": 22425,
        "totalTaxAmount": 7475,
        "taxPercentage": 25,
        "productUrl": "https://www.example.com/taxiride",
      },
    },
  ],
  "bottomLine": {
    "currency": "NOK",
    "posId": "taxi_122",
  }
}

Sequence diagram​