MB WAY for API only

Add MB WAY to an existing API-only integration

Accept MB WAY payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

Before you begin

These instructions explain how to add MB WAY to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.

Before starting your MB WAY integration:

Make sure that you have set up your back end implementation.
Add MB WAY in your test Customer Area.

Build your payment form for MB WAY

Include MB WAY in the list of available payment methods. You don't need to collect any information from the shopper in your payment form.

We provide an MB WAY logo which you can use on your payment form. For more information, refer to Downloading logos.

You can also get the required fields from the /paymentMethods response as explained in our API-only integration guide. In your request, specify:

countryCode: PT
amount.currency: EUR
amount.value: The amount of the transaction, in minor units.
The maximum transaction amount for MB WAY is 750 EUR.

The required fields are included in the object with type mbway.

Make a payment

In your /payments request, specify the following parameters:

paymentMethod.type: Set to mbway.
telephoneNumber: The shopper's telephone which must be a Portugese phone number, for example +351234567890.

curl https://checkout-test.adyen.com/v68/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "paymentMethod": {
    "type": "mbway",
    "telephoneNumber": "+351213822199"
  },
  "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
  "reference": "YOUR_ORDER_NUMBER",
  "shopperStatement": "MBWay shopper statement"
}'

require 'adyen-ruby-api-library'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

response = adyen.checkout.payments({
    :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
    :paymentMethod => {
      :type: "mbway",
      :telephoneNumber: "+351213822199"
    }
    :amount => {
        :currency => 'EUR',
        :value => 1000
    },
    :reference => "YOUR_ORDER_NUMBER",
    :returnUrl => "https://your-company.com/checkout?shopperOrder=12xy.."
})

// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-API-KEY";
Client client = new Client(xApiKey,Environment.TEST);
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");

DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
paymentMethodDetails.setType("mbway");
paymentMethodDetails.setTelephoneNumber("+351213822199");
paymentsRequest.setPaymentMethod(paymentMethodDetails);

Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
    "merchantAccount" => "YOUR_MERCHANT_ACCOUNT",
    "paymentMethod" => array(
      "type": "mbway",
      "telephoneNumber": "+351213822199"
    ),
    "amount" => array(
        "currency" => "EUR",
        "value" => 1000
    ),
    "reference" => "YOUR_ORDER_NUMBER",
    "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy.."
);
$result = $service->payments($params);

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
    'merchantAccount': 'YOUR_MERCHANT_ACCOUNT',
    'paymentMethod': {
       'type': 'mbway'
       'telephoneNumber': '+351213822199'
    },
    'amount': {
        'value': 1000,
        'currency': 'EUR'
    },
    'reference': 'YOUR_ORDER_NUMBER',
    'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..'
})

// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-API-KEY";
var client = new Client (apiKey, Environment.Test);
var checkout = new Checkout(client);
var amount = new Adyen.Model.Checkout.Amount("EUR", 1000);
var details = new MbwayDetails{
    Type = "mbway",
    TelephoneNumber = "+351213822199"
};
var paymentsRequest = new Adyen.Model.Checkout.PaymentRequest
{
    PaymentMethod = details,
    Amount = amount,
    Reference = "YOUR_ORDER_NUMBER",
    ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy.."
};
var paymentResponse = checkout.Payments(paymentsRequest);

const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[YOUR_X-API-KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    merchantAccount: config.merchantAccount,
    paymentMethod: {
      type: 'mbway',
      telephoneNumber: '+351213822199'
    },
    amount: { currency: "EUR", value: 1000, },
    reference: "YOUR_ORDER_NUMBER",
    returnUrl: "https://your-company.com/checkout?shopperOrder=12xy.."
}).then(res => res);

import (
    "github.com/adyen/adyen-go-api-library/v2/src/checkout"
    "github.com/adyen/adyen-go-api-library/v2/src/common"
    "github.com/adyen/adyen-go-api-library/v2/src/adyen"
)
// Set your X-API-KEY with the API key from the Customer Area.
client := adyen.NewClient(&common.Config{
    Environment: common.TestEnv,
    ApiKey:      "[YOUR_X-API-KEY]",
})
res, httpRes, err := client.Checkout.Payments(&checkout.PaymentRequest{
    MerchantAccount: "[YOUR_MERCHANT_ACCOUNT]",
    PaymentMethod: checkout.MbwayDetails{
      Type: "mbway",
      TelephoneNumber: "+351213822199",
    },
    Amount: checkout.Amount{
        Value:    1000,
        Currency: "EUR",
    },
    Reference: "YOUR_ORDER_NUMBER",
    ReturnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
})

https://docs.adyen.com/payment-methods/mb-way/api-only#mb-way-payments

The /payments response contains:

resultCode: Pending, means the shopper needs to complete the payment in their MB WAY app.
action.type: await, means you need to wait for the webhook to know the payment outcome.

{
  "resultCode": "Pending",
  "action": {
    "paymentData": "Ab02b4c0!BQABAgCX79JLFTqePTGTb...",
    "paymentMethodType": "mbway",
    "type": "await"
  },
  "paymentData": "Ab02b4c0!BQABAgCX79JLFTqePTGTb..."
}

https://docs.adyen.com/payment-methods/mb-way/api-only#-payments-response

Show the waiting screen

Show a waiting screen to the shopper, telling them you're waiting for them to complete the payment.
Check your webhooks to see the payment result. We send you a webhook after the shopper completes the payment in their MB WAY app.
Once the shopper finalizes the payment, redirect them to your website, and present the payment result.

Present the payment result

Use the resultCode from the /payments response to show the payment outcome on your frontend.

The resultCode values you can receive for MB WAY are:

`resultCode`	Description	Action to take
Error	There was an error when the payment was being processed.	Inform the shopper that there was an error processing their payment. The response contains a `refusalReason`, indicating the cause of the error.
Pending or Received	The shopper has completed the payment but the final result is not yet known. It may take minutes or hours for the payments network to confirm this.	Inform the shopper that you've received their order, and are waiting for the payment to be completed. You will receive the final result of the payment in an AUTHORISATION webhook.
Refused	The payment was refused by the shopper's bank.	Ask the shopper to try the payment again using a different payment method.

You will receive the outcome of the payment asynchronously in a webhook:

`eventCode`	`success`	Description	Action to take
AUTHORISATION	true	The shopper successfully completed the payment.	Inform the shopper that the payment has been successful and proceed with the order.
AUTHORISATION	false	The transaction failed.	Cancel the order and inform the shopper that the payment failed.

Test and go live

To test your MB WAY integration, you can use any telephone number, for example +351234567890.

You can trigger a specific resultCode value by appending a code to the shopperStatement value in your /payments request:

`resultCode`	Code to append to `shopperStatement`
Authorised default test response	`-c1`
Pending	`-c3` and wait 15 minutes after making the /payments request
Refused	`-c5`

For example, to receive resultCode: Refused, include the following in your /payments request:

{
  // Produce a REFUSED payment result.
  "shopperStatement": "MBWay shopper statement-c5"
}

You can check the status of MB WAY test payments in your Customer Area > Transactions > Payments.

Before you can accept live MB WAY payments, you need to add MB WAY in your live Customer Area.