MBWAY supports recurring payments, and we streamline this process for you with our payment agreements API.

Create the payment agreement

To create an MBWAY payment agreement, provide the following information when calling our payment agreements API:

Data Field	Required	Description
Authentication Method		`APP_NOTIFICATION`
paymentMethod	M	`MBWAY`
consumer.country	M	The country from which the consumer is shopping.
authenticationSettings.type	M	Supply settings for the support authentication flows:`APP_NOTIFICATION`
frequency.type	C	The type of frequency between consecutive payment charges. Permissible Value are DAILY,WEEKLY,MONTHLY,YEARLY. Mandatory for Subscription Payments and Optional for Stored Credential payments (One Click). We support both Subscription and One Click Payments.

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

The exact amount.value and amount.currency of the first payment

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement\_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
    "paymentMethod": "MBWAY",
    "consumer": {
        "country": "PT"
    },
    "frequency": { "type": "MONTHLY"},
    "authenticationSettings": [
        {
            "settings": {
                "instrumentProviderIdentity": "+351999999999"
            },
            "type": "APP_NOTIFICATION"
        }
    ]
}

{
    "paymentMethod": "MBWAY",
    "consumer": {
        "country": "PT"
    },
    "frequency": { "type": "MONTHLY"},
     "authenticationSettings": [
        {
            "settings": {
                "instrumentProviderIdentity": "+351999999999"
            },
            "type": "APP_NOTIFICATION"
        }
    ],
    "initialPaymentCharge": {
        "autoCapture": true,
        "amount": {
            "value": 2,
            "currency": "EUR"
        }
    }
}

Response

You'll receive our standard payment agreement response:

{
  "id": "agr_gFCDp991mUCjWVypLEvfZ",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "MBWAY",
  "frequency": {
        "type": "MONTHLY",
        "interval": 1
  },
  "startDate": "2026-03-10T13:31:39.222Z",
  "instrumentId": "instr_hLOqf7bZvyo98kqT4Spio",
  "consumer": {
    "country": "PT"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "APP_NOTIFICATION"
    }
  ],
  "history": [
    {
      "id": "ahist_8WvsAUIuUR9lYCajdkPsv",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2026-03-10T13:31:39.222Z"
    }
  ],
  "createdAt": "2026-03-10T13:31:39.222Z",
  "updatedAt": "2026-03-10T13:31:39.222Z"
}

{
  "id": "agr_gFCDp991mUCjWVypLEvfZ",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "MBWAY",
  "frequency": {
        "type": "MONTHLY",
        "interval": 1
  },
  "startDate": "2026-03-10T13:31:39.222Z",
  "instrumentId": "instr_hLOqf7bZvyo98kqT4Spio",
  "consumer": {
    "country": "PT"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "APP_NOTIFICATION"
    }
  ],
  "history": [
    {
      "id": "ahist_8WvsAUIuUR9lYCajdkPsv",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2026-03-10T13:31:39.222Z"
    }
  ],
  "createdAt": "2026-03-10T13:31:39.222Z",
  "updatedAt": "2026-03-10T13:31:39.222Z"
}

Pick the desired authentication method

REDIRECT

Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl For example, with the value of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.

Handling the result

REDIRECT

After the consumer completes the authentication, they are redirected to the returnUrl specified in the payment charge creation request.
Upon redirect back to your site, retrieve the latest agreement status by performing a GET /v1/payment-agreements/{agreementId}. Use the returned status field to determine and display the final payment outcome to the consumer.
Additionally, webhooks are triggered to notify you of the payment result. This ensures you receive the outcome even if the consumer closes their browser or fails to return to your website.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement using our payment agreements API.

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

{
  "amount": {
    "value": 1000,
    "currency": "EUR"
  }
}

Response

{
    "id": "charge_WLnk5R2RKwzAinkEoAMm0",
    "paymentMethod": "MBWAY",
    "currency": "EUR",
    "country": "PT",
    "instrumentId": "instr_86xMmxSjrVafelQgtAXxr",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "country": "PT"
    },
    "authorizations": [
        {
            "id": "authz_nx4VgDiibOTPoYgXxQbrL",
            "amount": 1000,
            "status": "AUTHORIZED",
            "createdAt": "2026-02-10T16:28:40.150Z",
            "updatedAt": "2026-02-10T16:28:40.150Z"
        }
    ],
    "captures": [
        {
            "id": "capture_aJh1kGwLdwK8S3aFCeWFV",
            "amount": 1000,
            "status": "CAPTURED",
            "createdAt": "2026-02-10T16:28:40.150Z",
            "updatedAt": "2026-02-10T16:28:40.150Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2026-02-10T16:28:38.716Z",
    "updatedAt": "2026-02-10T16:28:40.150Z"
}

Sandbox testing

MB WAY Recurring uses PPRO's mock authenticator in sandbox. Learn more.