Skip to content

Last Updated: 09 July 2025 | Change Log

Multibanco

Multibanco is an interbank network in Portugal. This network is run by SIBS (Sociedade Interbancária de Serviços S.A.) and enables many services, including payment services, to be hosted.

Note

Make yourself familiar with our API Principles to ensure a resilient integration.

Product overview

Feature summary

Payment typeCountryAcceptance CurrencyRecurringReversalsPartial Reversals
Post-pay voucherPortugalEUR
  • Minimum Transaction Value: 1.00 EUR
  • Maximum Transaction Value: 2.500 EUR

Get Started

Get started using our API Reference and set your headers.


Request

POST https://try.access.worldpay.com/apmPayments

Example request

application/json
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default" }, "instruction": { "method": "multibanco", "value": { "amount": 1600, "currency": "EUR" }, "narrative": { "line1": "Joe Plumbing Ltd" }, "paymentInstrument": { "type": "direct", "country": "PT" }, "resultUrls": { "pending": "https://worldpay.com/pending", "success": "https://worldpay.com/success", "cancel": "https://worldpay.com/cancel" }, "customer": { "email": "shopper@worldpay.com" } } }

Parameters

transactionReferencestring[ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$required
merchantobject(MerchantV2)required
merchant.​entitystring[ 3 .. 32 ] characters^([a-zA-Z0-9\- ]*)$required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
instructionobject(InstructionV2)required

Object that contains the payment type and details.

instruction.​methodstringrequired

Type of payment method

Value"alipay_cn"
Discriminator
instruction.​valueobject(Value)required

The value of the payment.

instruction.​value.​amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 12
instruction.​value.​currencystringrequired
Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"
instruction.​narrativeobject(NarrativeBase)required
instruction.​narrative.​line1string[ 1 .. 24 ] characters^[a-zA-Z0-9-., ]*$required

The description shown on your customer's bank statement for the payment.

Example: "MindPalace"
instruction.​paymentInstrumentobject(AlipayCnInstrumentV2)required
instruction.​paymentInstrument.​typestringrequired

Type of instruction

Value"direct"
instruction.​paymentInstrument.​languagestring

Your customer's language.

Enum"aa""ab""ae""af""ak""am""an""ar""as""av"
instruction.​resultUrlsobject(ResultUrlsAlipay)required
instruction.​resultUrls.​cancelstring

The URL your customer is redirected to, after a cancelled payment outcome.

Example: "https://worldpay.com/cancel"
instruction.​resultUrls.​failurestringrequired

The URL your customer is redirected to, after a failed payment outcome.

Example: "https://worldpay.com/failure"
instruction.​resultUrls.​pendingstringrequired

The URL your customer is redirected to, after a pending payment outcome.

Example: "https://worldpay.com/pending"
instruction.​resultUrls.​successstringrequired

The URL your customer is redirected to, after a successful payment outcome.

Example: "https://worldpay.com/success"
instruction.​deviceDataobject(DeviceData)
instruction.​customerobject(CustomerWithName)

Response

Successful request response

  • an HTTP code 201
  • a paymentId which is unique to the payment - we recommend storing the "id", as you can use it to manage the payment later
  • a url to redirect your customer. For Multibanco returns a Worldpay redirection URL. This redirects the shopper to the merchant-supplied pending URL that contains additional
  • a link to query the payment status
  • an object which will give flow information such as method (e.g. multibanco) and type (direct)
  • a commandId generated by us identifying a single merchant interaction (e.g. cmdYNdIHBPJwbkjLiykzTx0)
Additional information
ParameterExampleDescription
Multibanco reference679+115+881The payment reference that the shopper must use to complete the payment.
Multibanco entity11893The entity reference that the shopper must use to complete the payment.
Payment amount100The amount that the shopper should pay, expressed in minor currency units. For example, 100 = 100 Euro cents.
Payment currencyEURThe currency corresponding to the PaymentAmount.

In the above example, you must display a message of the following form to the shopper:

"To complete your payment, please make a deposit using the details below. To avoid delays in your payment being processed, please ensure that you use the exact details and payment amount shown below. You can pay through your Internet bank or at an ATM. Reference: 679115881 Entity: 11893 Amount: EUR 1"

Pending URL example: http://www.worldpay.com/pendingURL?orderKey=BIBIT^DEMO^Example_Multibanco_Order&status=OPEN&multibancoReference=679+115+881&multibanco_Entity=11893&multibancoPaymentAmount=100&multibancoPaymentCurrency=EUR

Example Response

{
  "paymentInstrument": {
    "method": "multibanco",
    "type": "direct"
  },
  "paymentId": "eyJrIjoiYXBtLXNlcnZpY2UtZGVmYXVsdCIsImxpbmtWZXJzaW9uIjoiNi4wLjAifQ==.BnnxxcMle38OazhwbF8J+4rtJi8CAq:Y3zUOn1dw6VWfvx:PHL5L0S+5ara5vz6ouV5yBmVUQCiSwQjs+1x5qJIJxAKWMWc2Mlb1doricEbSibICjg9oWBDkoVO2KwlcxPVS3no:Ih5XitYN0H06VJpX:bvbw7McvoP:E6S0L1+lDe8iZ9K6c9KAEix5K1S6AaFT9PiiV:KsP+z2Cdr9o:XFrnd4GNEHV7yDuZt9Jyqf5XZUPFYfD4fs2JzaCZKV3L7DQm7JfXl6rjXA0ubX6hJpY5kUX4Djm9+PFFKUS6+LdORYaAdburi8EX32V9tpYSSzNI+ETqS5RDlRGivjQxKM2Ks:rlczHJ2DGe1:xPRqjBWEQYSfjhGO0ig5hWkDZE8WUCW:tC4G::vVo3ySleCbEoL1DciLmD44Risvo6Qgyc2sVBwmk1yqyduyRKK6z:U2p2C6Bg4E5vMB+TefQQ==",
  "lastEvent": "pending",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/eyJrIjoiYXBtLXNlcnZpY2UtZGVmYXVsdCIsImxpbmtWZXJzaW9uIjoiNi4wLjAifQ==.BnnxxcMle38OazhwbF8J+4rtJi8CAq:Y3zUOn1dw6VWfvx:PHL5L0S+5ara5vz6ouV5yBmVUQCiSwQjs+1x5qJIJxAKWMWc2Mlb1doricEbSibICjg9oWBDkoVO2KwlcxPVS3no:Ih5XitYN0H06VJpX:bvbw7McvoP:E6S0L1+lDe8iZ9K6c9KAEix5K1S6AaFT9PiiV:KsP+z2Cdr9o:XFrnd4GNEHV7yDuZt9Jyqf5XZUPFYfD4fs2JzaCZKV3L7DQm7JfXl6rjXA0ubX6hJpY5kUX4Djm9+PFFKUS6+LdORYaAdburi8EX32V9tpYSSzNI+ETqS5RDlRGivjQxKM2Ks:rlczHJ2DGe1:xPRqjBWEQYSfjhGO0ig5hWkDZE8WUCW:tC4G::vVo3ySleCbEoL1DciLmD44Risvo6Qgyc2sVBwmk1yqyduyRKK6z:U2p2C6Bg4E5vMB+TefQQ=="
    }
  },
  "_actions": {},
  "redirect": "http://secure-test.worldpay.com/redirect?tokenId=607aa358-f5ef-4ac8-bd66-d7d5e92a5169",
  "commandId": "cmdQWhyosPRf9MP3x9LKqAvw0"
}

Errors

Check out our API reference for the full error code schema.

Manage your Multibanco payment