Payments with Multibanco

Lemonway offers its partners the ability to accept payments through Multibanco, one of the most widely used payment methods in Portugal. Multibanco allows customers to pay for their purchases using a generated payment reference, which can be settled through online banking or at a participating ATM. Through Lemonway's integration, partners can easily offer Multibanco as an additional payment option on their platforms. Once the customer selects Multibanco at checkout, Lemonway generates the payment details and provides a reference that the customer can use to complete the payment through their preferred banking channel. Unlike real-time payment methods, Multibanco payments are processed asynchronously. The transaction remains pending until the customer completes the payment, with confirmation sent to the partner once the funds have been received. This gives partners another familiar and accessible payment option for customers in Portugal.

Multibanco Payment Flow 🇵🇹

Multibanco is a Portuguese post-pay (offline/deferred) solution. Unlike real-time apps, it generates a standard billing reference.

Payment Method	Technical Code	Required countryCode	Payer Phone Format	Real-Time Settlement?	Refund Window Length
Multibanco	`multibanco`	`PT` (Portugal)	Optional	No (Deferred up to 7 days)	Up to 12 months

The browser session ends immediately, while the transaction stays open, waiting for manual funding.

Your platform calls /apm/init with PaymentMethod set to multibanco.
Lemonway creates the transaction in Pending status and returns a redirectUrl.
Your platform redirects the payer to the redirectUrl.
The payer is shown the Multibanco payment details and completes the payment through online banking or at an ATM.
Once the payment result is known, Lemonway updates the transaction and redirects the payer to your returnUrl, cancelUrl, or errorUrl.

The standard flow for Multibanco:

sequenceDiagram
    actor Payer
    participant Partner as Partner Platform
    participant Lemonway
    participant MB as Multibanco Network

    Payer->>Partner: Choose Multibanco at Checkout
    Partner->>Lemonway: POST /v2/moneyins/apm/init ("multibanco")
    Lemonway-->>Partner: Return {"id": 378956, "redirectUrl": "..."}
    Partner-->>Payer: Redirect browser to redirectUrl
    Payer->>Lemonway: View generated Entity Code & Payment Reference
    Lemonway-->>Payer: Redirect browser back to Partner's returnUrl
    
    Note over Payer, Partner: Note: Client transaction is still actively PENDING.<br/>Valid for 7 days or custom timeoutInMinutes.

    alt Path A: Payer settles before expiry
        Payer->>MB: Pay reference via local ATM or Homebanking App
        MB->>Lemonway: Push clearing confirmation
        Lemonway->>Lemonway: Update state to Success
        Lemonway->>Partner: POST Webhook Notification (ID 55 - Success)
    else Path B: Expiry window lapses
        Lemonway->>Lemonway: Update state to Cancelled
        Lemonway->>Partner: POST Webhook Notification (Transaction Cancelled)
    end

Example: Multibanco (countryCode must be PT)

{
  "transaction": {
    "reference": "ORDER-1004",
    "accountId": "2f6f3dfb-4a1e-43c1-9d6c-5f9b531c7f2b",
    "totalAmount": 15000,
    "PaymentMethod": "multibanco",
    "commissionAmount": 1650,
    "comment": "Online purchase",
    "autoCommission": false
  },
  "paymentUrls": {
    "redirections": {
      "returnUrl": "https://example.com/success",
      "errorUrl": "https://example.com/error",
      "cancelUrl": "https://example.com/cancel"
    }
  },
  "customer": {
    "firstName": "mikel",
    "lastName": "baston",
    "email": "[email protected]",
    "countryCode": "PT"
  },
  "preferredLanguage": "pt",
  "timeoutInMinutes": 15
}

{
  "id": 362521,
  "redirectUrl": "https://webkit.lemonway.com/.../apm/form/{token}"
}