☰

Navigation:

MB WAY and MB REF Native Integration

This document provides information about integrating MB WAY and MB REF native APIs, which are used to facilitate payments within the customer’s mobile applications. These APIs are available in the production environment only.

Before you start

The native API call credentials for MB WAY and MB REF are available to merchants on request. Please speak to your Viva sales representative to request access. To activate these payment methods from your dashboard, please see this link for more details.
  1. Use the API credentials provided to you by your sales representative.
  2. Complete our Request access token procedure.
  3. Make a note of your access token which will expire after 3600 seconds (one hour). Include a function in your code that repeats step 3 above programmatically before each expiry.
  4. Utilize the appropriate API calls below based on your specific requirements.

API calls

1. MB WAY Native API

The MB WAY Native API triggers the user’s native MB WAY application on their mobile device or any app that supports MB WAY. This allows users to complete their payment using the MB WAY app directly from their mobile device. The process is seamless, with the MB WAY app sending a notification to the user’s phone, which they can click to finalize the payment.

post    /nativecheckout/v2/sibspagamentos/mbwayid/sessions

The parameters amount, phone, and phonePrefix are required fields. Please ensure these values are provided to successfully execute the API call.

Request example

curl -X POST \
  https://api.vivapayments.com/nativecheckout/v2/sibspagamentos/mbwayid/sessions \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0,
    "sourceCode": "string",
    "customerTrns": "string",
    "currencyCode": "string",
    "customer": {
      "email": "string",
      "phone": "string",
      "fullName": "string",
      "requestLang": "string",
      "countryCode": "string",
      "phonePrefix": "string"
    }
}'

Response example

{
  "transactionId": "c2ea33e3-0d56-4d78-b721-8d8df86a9519"
}

2. MB REF Native API

The MB REF Native API provides the customer with an entity and reference number, which they can manually enter into their MB WAY application to complete the payment. Additionally, the response includes an expiration date, which indicates the deadline by which the payment must be made.

POST    /nativecheckout/v2/sibspagamentos/mbreference/sessions

The parameter amount is required field. Please ensure this value is provided to successfully execute the API call.

Request example

curl -X POST \
  https://api.vivapayments.com/nativecheckout/v2/sibspagamentos/mbreference/sessions \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0,
    "sourceCode": "string",
    "customerTrns": "string",
    "currencyCode": "string",
    "customer": {
      "email": "string",
      "phone": "string",
      "fullName": "string",
      "requestLang": "string",
      "countryCode": "string",
      "phonePrefix": "string"
    }
}'

Response example

{
  "transactionId": "c2ea33e3-0d56-4d78-b721-8d8df86a9519",
  "entity": "string",
  "reference": "string",
  "expirationDate": "2024-01-20T10:23:13.0579239+00:00"
}

Please note, in MB REF Native, customers can use the provided entity and reference to complete their payment. Please note that the payment must be made before the expirationDate.

3. Verify transaction and set webhook (optional)

You can make a call to Retrieve transactions in order to verify the status of a payment. To get automatic notifications you can make use of our webhooks functionality.

Further information

Check out the related tutorials below for more details about OAuth 2 authentication and setting webhooks: