Skip to main content

Server-to-Server

Create the payment directly via the API and show the returned Multibanco entity and reference to the customer. There is no hosted page and no browser redirection.

Payment workflow

For the full sequence diagram and status table, see Payment workflow on the Multibanco overview.

Implementation flow​

  1. Make a Payment API request with payment_type: "multibanco". Optionally set how long the reference is valid with multibanco_reference_expires_at.
  2. The synchronous response returns the transaction in the pending status together with multibanco_entity, multibanco_reference and multibanco_reference_expires_at.
  3. Show the entity, reference, amount and expiry to the customer: on your confirmation page, in the order e-mail or on the invoice.
  4. When the customer pays, the transaction becomes completed and a postback is sent. If the reference expires unpaid, it becomes reversed and a postback is sent.

A postback is sent on each status change, so use it, not the synchronous response, as the source of truth for the final result.

For a general walkthrough of credentials, authentication, and postbacks, see Get Started — Server-to-Server Processing.

Create a payment​

POST/rest/payment
payment_typeStringrequired
multibanco
order_idStringrequired
Any alphanumeric string to identify the Merchant's order
amountFloatrequired
Amount of the transaction. The customer must pay exactly this amount
currencyStringrequired
3 letter currency code. Multibanco payments are processed in EUR
multibanco_reference_expires_atString
When the reference expires, as an ISO 8601 timestamp (for example 2026-10-02T12:00:00Z). Must be at least 5 minutes and at most 30 days in the future. Defaults to 72 hours from now. An invalid value is rejected with error code 167
postback_urlStringrequired
The URL where updates about transaction status are posted
This example includes only the parameters required to create a Multibanco payment. See the Create Payment API reference for the full list of supported parameters.
Example RequestHTTP
POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "multibanco",
"order_id": "MB-12345",
"amount": "1.23",
"currency": "EUR",
"first_name": "Maria",
"last_name": "Silva",
"multibanco_reference_expires_at": "2026-10-02T12:00:00Z",
"postback_url": "https://your-postback.url.com"
}

Payment API Response​

transaction_idString
ID of the created transaction
payment_typeString
Payment type of the transaction
status_codeInteger
Status code of the transaction. 2 (pending) until the reference is paid
statusString
Status of the transaction
order_idString
Order ID of the transaction
amountFloat
Amount the customer has to pay
multibanco_entityString
Payment entity (5 digits) the customer enters at the ATM or in home banking
multibanco_referenceString
Payment reference (9 digits) the customer enters together with the entity
multibanco_reference_expires_atString
When the reference expires (ISO 8601, UTC)
error_codeInteger
Error code for the response
Example ResponseJSON
{
"transaction_id": "3b9f1c2a-7d4e-4f60-8a1b-2c3d4e5f6a7b",
"payment_type": "multibanco",
"status_code": 2,
"status": "pending",
"order_id": "MB-12345",
"message": null,
"additional_transaction_data": null,
"amount": 1.23,
"recurring": 0,
"multibanco_entity": "53379",
"multibanco_reference": "251289715",
"multibanco_reference_expires_at": "2026-10-02T12:00:00Z",
"included_fees": "0.00",
"error_code": 0
}

Show the customer the three values they need to pay, for example:

Entity53379
Reference251 289 715
Amount€1.23
Pay by2 Oct 2026, 13:00 (Lisbon time)

The same values are included in the first postback (pending) and in the Transaction Details API response, so you can show them again later.

note

If SIBS cannot issue a reference, the transaction is error (4) and the response carries a non-zero error_code with the reason in error_message.

Cancel a reference​

To cancel a reference that has not been paid yet (for example, when the order is cancelled), send a Reversal API request (POST /rest/reverse) with the transaction_id. The reference is cancelled at SIBS, so the customer can no longer pay it. The transaction becomes canceled (5) and a postback is sent. A reference that is already paid cannot be cancelled; the request is rejected with error code 108.

Refunds​

A paid reference (completed) can be refunded in full or in part with the Refund API. SIBS confirms Multibanco refunds asynchronously: the refund starts in progress, and its result is sent to your postback_url once SIBS has processed it. After a successful refund the transaction is refunded (7). An unpaid reference cannot be refunded; cancel it instead (see above).

Postbacks​

A postback is sent to your postback_url on each status change: when the reference is issued (pending), when it is paid (completed) and when it expires unpaid (reversed). In addition to the standard Payment API postback fields, Multibanco postbacks include multibanco_entity, multibanco_reference and multibanco_reference_expires_at. For retry policy and signature verification, see Postbacks.

{
  "transaction_id": "3b9f1c2a-7d4e-4f60-8a1b-2c3d4e5f6a7b",
  "payment_type": "multibanco",
  "status_code": "3",
  "status": "completed",
  "order_id": "MB-12345",
  "amount": "1.23",
  "multibanco_entity": "53379",
  "multibanco_reference": "251289715",
  "multibanco_reference_expires_at": "2026-10-02T12:00:00Z"
}

Test Data​

In the test environment, references are issued by the SIBS test platform. They are never paid automatically: to test the completed flow, ask your onboarding manager to have the reference paid on the SIBS test platform. To test the reversed flow, create a reference with a short multibanco_reference_expires_at (for example 10 minutes from now) and let it expire.

Last updated on