Payment Gateway Portugal

April 12 2024

vTerminal

vTerminal is a web-based virtual terminal which allows you to accept financial transactions via MB WAY and also generate MULTIBANCO References.

This solution lets you send payment notifications for your clients (via MB WAY) or MULTIBANCO References (via SMS).

The benefits of using vTerminal are:

Convenience

vTerminal works on any device that has internet access.

Flexibility

vTerminal can be used in person, over the phone or by e-mail.

Agility

vTerminal has an easy and fast onboarding integration.

If you want to learn more about vTerminal, click here.

April 3 2024

Implementation

Eduardo Bica PGpage

MB WAY is an asynchronous payment that requests the MB WAY enabled app, associated with the mobile phone number sent within the request, to accept the payment.

Front office operations

The SIBS Gateway supports two types of operations, purchases and authorisations, where the purchase triggers the payment immediately and the authorisation keeps the amount captive until a capture is performed.

Purchase: This transaction allows a Cardholder to pay for a good or service via an electronic operation that debits his account and will credit the Acceptors banking account. Consists in an immediate debit in the Client account and it is an effective payment on the moment of the transaction.

Authorisation: Consists in an authorisation for a future payment. It allows the Merchant to get an authorisation from the Issuer keeping the amount captive in the Cardholders banking account; the transaction is authorised and the purchase will be triggered in a second moment, when the merchant needs to trigger a “Capture” on the Backoffice.

Backoffice operations

At a back-office level, MB WAY supports the following types of operations:

Capture

Used when the Cardholder has provided an authorisation for the payment on a 1st stage and the amount is captured. Used on a 2nd stage to execute the payment, which can happen in different ways (always triggered over an authorisation):

Full: capture the full amount authorised and finish the purchase;
Partial: split the capture and do several payments up to the total amount authorised.

Refund

The purpose of this operation is to refund the amount of a previous payment, crediting the Cardholder account and debiting the Merchant account. A refund can be:

Full: when the total amount of the purchase is refunded to the Cardholder;
Partial: when a subtotal of the total purchase is refunded to the Cardholder.

Cancellation

Requests the cancellation of the amount (full or partial) of a previous authorisation.

It is possible to establish the relationship below among the Front office & Backoffice operations, having in mind that Backoffice operations will act on the Front office operations:

	Purchase	Authorisation	Capture
Capture		1
Refund	4		3
Cancellation		2

April 3 2024

Alias Webservices

Eduardo Bica PGpage

April 1 2024

Financial Webservices

Eduardo Bica PGpage

In-App Operative

The in-app operative aims at providing an integrated payment experience for the user who chooses the MB WAY service as the payment method in a Merchant app. This operative allows the communication between the Merchant mobile apps and the user’s MB WAY app, if installed in the same device, and supports the Purchase and Purchase Authorisation operations.

The integrity and security of the relationship between the Merchant app and the MB WAY app is ensured by tokens. This operative is based on a web service (MerchantAliasWSCreate) that allows to request a user
token creation at SIBS FPS. This token is used to invoke the MB WAY app.

The user token (aliasTypeCde ‘010’) may be reused for several purchases and, for this reason, the Merchant shall store the token assigned to the his client. If the Merchant chooses not to store the token, then he must submit a new user token creation request.

This token is not visible to the MB WAY clients and it can only be removed through the MerchantAliasWSRemove web service.

Similarly to the other MB WAY integrations, this operative also includes all validations that ensure the Merchant compliance with the security requirements while submitting user token creation requests.

March 19 2024

Examples

Eduardo Bica PGpage

In this section, it is possible to find some webhook notifications examples sent by SIBS Gateway and the answer that the Merchant should give (more information in section Webhook Notification Response). The answer to this message is crucial to avoid more unnecessary notifications sent by SIBS Gateway through the Webhook Retry System (more information in section Merchant Notification (Webhook) Retry System).

Webhook Notification Response

Webhook Notification – MB WAY Purchase with Alias

Webhook Notification – MB WAY Purchase with Alias – Declined

Webhook Notification – MB WAY Authorised Payment Creation

Webhook Notification – MB WAY Authorised Payment Purchase after Creation

Webhook Notification – Cancel MB WAY Authorised Payment

Webhook Notification – Cancel MB WAY Authorised Payment – Decline

Webhook Notification – Static QR Code Purchase

Webhook Notification – MULTIBANCO Reference Generation

Webhook Notification – MULTIBANCO Reference “Paid”

Webhook Notification – Card Purchase

Webhook Notification – Token Generation

Webhook Notification – Token Purchase

Webhook Notification – Merchant Initiated Transaction (MIT) with Type UCOF

Webhook Notification – Merchant Initiated Transaction (MIT) with Type Recurring

Webhook Notification – Cardholder Initiated Transaction (CIT) with Type UCOF

Webhook Notification – Cardholder Initiated Transaction (CIT) with Type Recurring

Webhook Notification Response

{
 "statusCode": "200",
 "statusMsg": "Success",
 "notificationID": "93b9b3a6-602f-4769-8158-48ae9c380ed5"
}

Webhook Notification – MB WAY Purchase with Alias

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "MBWAY",
"transactionID": "s2efgrtgn456477",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": "16.20"
},
"merchant": {
"transactionId": "863b730df285443ca404e0085fw234",
"terminalId": "99978",
"merchantName": "Teste MBWAY Sucesso",
"inApp": "false"
},
"paymentType": "PURS",
"token": {
"tokenType": "MobilePhone",
"value": "351#912345678"
},
"internalTransactionId": "S14073500001359S",
"notificationID": "839ca363-8581-4b9f-8041-a6dfgrtyu643"
}

Webhook Notification – MB WAY Purchase with Alias – Declined

{
"returnStatus": {
"statusMsg": "Declined",
"statusCode": "01.106.0004"
},
"paymentStatus": "Declined",
"paymentMethod": "MBWAY",
"transactionID": "s2nvtgbntiuybn88485t",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": "16.20"
},
"merchant": {
"transactionId": "863b730df285443ca404e00853de45",
"terminalId": "99978",
"merchantName": "Teste MBWAY Erro",
"inApp": "false"
},
"paymentType": "PURS",
"token": {
"tokenType": "MobilePhone",
"value": "351#912345500"
},
"internalTransactionId": "S14073500001351S",
"notificationID": "839ca363-8581-4b9f-8041-a6d456jkh678"
}

Webhook Notification – MB WAY Authorised Payment Creation

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "MBWAY",
"transactionID": "UpxBSsjySqaR80aEzWxa",
"transactionDateTime": "2022-11-11T16:18:53.127Z",
"amount": {
"currency": "EUR",
"value": 1.96
},
"merchant": {
"transactionId": "1009854",
"terminalId": 45546,
ification: Restricted Version 2024.11 of 2024-11-11
Reference: Page 125 of 151
SIBS Gateway V2 Integration Manual
“merchantName”: “Test Authorised Payment Creation”,
“inApp”: “false”
},
"paymentType": "AUTH",
"mbwayMandate": {
"mandateIdentification": "12345690656800744652",
"mandateAction": "CRTN",
"mandateActionStatus": "SCCS",
"mandateType": "SBSC",
"clientName": "Andresa COS",
"aliasMBWAY": "351#914341580"
},
"notificationID": "6e96b74f-ec33-4ca9-8cd3-1d00c5d82a0d"
}

Webhook Notification – MB WAY Authorised Payment Purchase after Creation

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "MBWAY",
"transactionID": "s2jrfvnriuv8tgt554tg",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": 15.2
},
"merchant": {
"transactionId": "863b730df285443ca404e0085dref45",
"terminalId": 99978,
"merchantName": "Teste Pagamentos Autorizados Sucesso"
},
"paymentType": "PURS",
"token": {
"tokenType": "MobilePhone",
"value": "351#919992314"
},
"internalTransactionId": "S13074000497973S",
"notificationID": "839ca363-8581-4b9f-8041-a45tgbh67u"
}

Webhook Notification – Cancel MB WAY Authorised Payment

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "MANDATE",
"transactionID": "s2t44gh56y67jAsftgt",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": 15.2
},
"merchant": {
"transactionId": "863b730df285443ca404e0085fd6789",
"terminalId": 96546,
"merchantName": "Canc Pagamento Autorizado"
},
"paymentType": "CAUT",
"internalTransactionId": "S14072900000002S",
"notificationID": "0d93a5ef-13e0-4a6b-9e40-652342321451"
}

Webhook Notification – Cancel MB WAY Authorised Payment – Decline

{
"returnStatus": {
"statusMsg": "Declined",
"statusCode": "10.106.2662"
},
"paymentStatus": "Declined",
"paymentMethod": "MANDATE",
"transactionID": "s2SFFe3445gjn5hjas",
"transactionDateTime": "2022-11-11T16:18:53.127Z",
"amount": {
"currency": "EUR",
"value": 15.2
},
"merchant": {
"transactionId": "863b730df285443ca404e0085fd6ssd",
"terminalId": 96546,
"merchantName": "Canc Pagamento Autorizado"
},
"paymentType": "CAUT",
"internalTransactionId": "S14072900000007S",
"notificationID": "0d93a5ef-13e0-4a6b-9e40-h589085hnA "
}

Webhook Notification – Static QR Code Purchase

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "STATIC_QRCODE",
"transactionID": "3W005000159764",
"transactionDateTime": "2022-11-12T16:17:53.127Z",
"amount": {
"currency": "EUR",
"value": 1.6
},
"merchant": {
"terminalId": 46431
},
"paymentType": "PURS",
"financialOperation": {
"product": {
"staticQRCodeId": "7ecf9d4e23334f7da6cb",
"twoStepPurchase": false,
"aliasName": "351#934885128",
"merchantContactType": "NA",
"productName": "Nome info",
"productQuantity": 1,
"productAmount": 1.5,
"expeditionAmount": 0.1,
"contactClientIndicator": 1,
"customerSupportContact": "teste@info.com"
},
"billingInfo": {
"billingTIN": "123456789",
"billingAddressCity": "Lisboa ",
"billingAddressLine1": "Rua D João ",
"billingAddressLine2": "8 2drt",
"billingAddressPostalCode": "4646-846",
Classification: Restricted Version 2024.11 of 2024-11-11
Reference: Page 124 of 151
SIBS Gateway V2 Integration Manual
"billingMobilePhone": "+ 351 987654321"
},
"expeditionInfo": {
"expeditionName": "Olga Rodrigues",
"expeditionAddressCity": "Lisboa ",
"expeditionAddressLine1": "Rua D João ",
"expeditionAddressLine2": "8 2drt",
"expeditionAddressPostalCode": "4646-846",
"expeditionMobilePhone": "+ 351 987654321"
}
},
"notificationID": "5544b042-8b9a-451e-8421-53fcfe9538f8"
}

Webhook Notification – MULTIBANCO Reference Generation

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "REFERENCE",
"transactionID": "s24587y857mtjgnbt",
"transactionDateTime": "2022-12-23T10:48:39.153Z ",
"amount": {
"currency": "EUR",
"value": "20.0"
},
"merchant": {
"transactionId": "863b730df285443ca404e008sde23",
"terminalId": "88845",
"merchantName": "Teste Referências, Lda"
},
"paymentReference": {
"reference": "256309828",
"entity": "40200",
"paymentEntity": "40200",
"amount": {
"value": "20.0",
"currency": "EUR"
},
"status": "UNPAID",
"expiryDate": "2022-01-23T10:48:39.153Z "
},
"paymentType": "PREF",
"notificationID": "20273954-0540-4bd3-8e01-234eds234cds"
}

Webhook Notification – MULTIBANCO Reference “Paid”

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "REFERENCE",
"transactionID": "s2jfvbiurbg8956vng",
"transactionDateTime": "2022-12-23T10:48:39.153Z",
"amount": {
"currency": "EUR",
"value": 20
},
"merchant": {
"transactionId": "863b730df285443ca404e00823sh76",
"terminalId": 88845,
"merchantName": "Teste Referências, Lda"
},
"paymentType": "PREF",
"internalTransactionId": "S14073000000341S",
"notificationID": "20273954-0540-4bd3-8e0-asd2w4jo0mmt"
}

Webhook Notification – Card Purchase

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "s2shdvbevr76756er",
"transactionDateTime": "2022-11-11T16:18:53.127Z",
"amount": {
"currency": "EUR",
"value": 19.2
},
"merchant": {
"transactionId": "863b730df285443ca404e008456sw2",
"terminalId": 66645,
"merchantName": "Teste Cartões, Lda"
},
"paymentType": "PURS",
"internalTransactionId": "S14073000000711S",
"notificationID": "8ec13f91-0129-44ff-980c-79e456fds21s"
}

Webhook Notification – Token Generation

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "sandboxfghwTKNGEN000",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": 19.2
},
"merchant": {
"transactionId": "863b730df285443ca404e008dsw212",
"terminalId": 77745,
"merchantName": "GOMERCIANTE DO LEGACY LD"
},
"paymentType": "AUTH",
"token": {
"tokenType": "Card",
"value": "fjklvnrtinrt435356jv"
},
"internalTransactionId": "S13074000501340S",
"notificationID": "462ec85b-5e1a-4a00-a4d7-97ddfe321567"
}

Webhook Notification – Token Purchase

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "TOKEN",
"transactionID": "s2grnvtruigbitu845hhtn",
"transactionDateTime": "2022-11-11T16:18:53.127Z ",
"amount": {
"currency": "EUR",
"value": 19.2
},
"merchant": {
"transactionId": "863b730df285443ca404e008mvn432kop",
"terminalId": 77745,
"merchantName": "PETROLEOS DE PORTUGAL - PETROGAL, SA"
},
"paymentType": "PURS",
"token": {
"tokenType": "Card",
"value": "gbtyhyujyuikuier45646ger4"
},
"notificationID": "462ec85b-5e1a-4a00-a4d7-97d345fds234"
}

Webhook Notification – Merchant Initiated Transaction (MIT) with Type UCOF

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "s2nYaNUC3hFpqd0HGq4Z",
"transactionDateTime": "2022-12-23T10:48:39.153Z",
"amount": {
"currency": "EUR",
"value": 5.16
},
"merchant": {
"transactionId": "6540474",
"terminalId": 45546,
"merchantName": "GOMERCIANTE DO LEGACY"
},
"paymentType": "MITR",
"notificationID": "c9786e7e-dc2a-4611-8a31-4b8197f41138",
"merchantInitiatedTransaction": {
"type": "UCOF",
"amountQualifier": "ESTIMATED"
}
}

Webhook Notification – Merchant Initiated Transaction (MIT) with Type Recurring

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "s2K9YuqPQuC9NkdCvDA4",
"transactionDateTime": "2023-01-06T00:00:03.378Z",
"amount": {
"currency": "EUR",
"value": 11.2
},
"merchant": {
"terminalId": 45546,
"merchantName": "GOMERCIANTE DO LEGACY"
},
"paymentType": "MITR",
"notificationID": "3a9d8777-292d-48fb-971c-6e6558de0fd5",
"merchantInitiatedTransaction": {
"type": "RCRR",
"amountQualifier": "ACTUAL"
}
}

Webhook Notification – Cardholder Initiated Transaction (CIT) with Type UCOF

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "s2bDX8mjiFZU5ZwfvSvR",
"transactionDateTime": "2023-01-06T16:57:11.2Z",
"amount": {
"currency": "EUR",
"value": 102.38
},
"merchant": {
"transactionId": "3064371",
"terminalId": 45546,
"merchantName": "GOMERCIANTE DO LEGACY"
},
"paymentType": "AUTH",
"notificationID": "45d108d3-2cef-41a6-90af-a3bdb4af244a",
"merchantInitiatedTransaction": {
"type": "UCOF",
"validityDate": "2023-01-31T00:00:00Z",
"amountQualifier": "ESTIMATED"
}
}

Webhook Notification – Cardholder Initiated Transaction (CIT) with Type Recurring

{
"returnStatus": {
"statusMsg": "Success",
"statusCode": "000"
},
"paymentStatus": "Success",
"paymentMethod": "CARD",
"transactionID": "s24nZiFtu15SCiW9vpDm",
"transactionDateTime": "2022-12-27T16:05:27.585Z",
"amount": {
"currency": "EUR",
"value": 11.2
},
"merchant": {
"transactionId": "6637262",
"terminalId": 45546,
"merchantName": "GOMERCIANTE DO LEGACY"
},
"paymentType": "PURS",
"notificationID": "a433453e-6e40-4f53-a80d-4985cffa36f6",
"merchantInitiatedTransaction": {
"type": "RCRR",
"validityDate": "2023-06-30T01:00:00+01:00",
"amountQualifier": "ACTUAL",
"schedule": {
"initialDate": "2022-12-27T00:00:00Z",
"finalDate": "2023-01-06T00:00:00Z",
"interval": "DAILY"
}
}
}

March 19 2024

Webhook Retry System

Eduardo Bica PGpage

In the event of an error in the merchant notification system, SIBS Gateway is ready to act and send notification retries to the merchant until the merchant confirms receipt of the notification.
When SIBS Gateway sends the Merchant Notification to the Merchant, the internal status of the notification remains “Requested” until the Merchant sends an acknowledgement to SIBS Gateway. If the merchant sends the acknowledgement, the notification status becomes “Processed” and the process ends, otherwise the Webhook Retry System is triggered at the end of a parameterised time.

The Webhook Retry System is a batch system that classifies merchant notifications with the status ‘Requested’ according to a minimum and maximum number of retries. This batch categorises merchant notifications into seven tiers, from Tier 0 (zero) to Tier 6 (six). Each tier has a specific retries count, a specific number of webhooks to retry and a retry period. Tier 0 represents the highest retry rate on the Webhook Retry System and Tier 6 represents the lowest retry rate in terms of periodicity.

The table below shows the seven categories of the Webhook Retry System, as well as the difference between them in terms of: Retries count, Number of webhooks retried and Retry period time. This batch process for a specific attempt will end after two months since the first attempt was started.

Tiers	Retries’ Count	Number of Webhooks Retried	Retry Period Time
Tier 0	0 to 4	400 (max)	Every 5 minutes
Tier 1	5 to 8	600 (max)	Every 1 hour
Tier 2	9 to 13	800 (max)	Every 2 hours
Tier 3	14 to 19	1000 (max)	Every 4 hours
Tier 4	20 to 26	1200 (max)	Every 6 hours
Tier 5	27 to 34	1400 (max)	Every 12 hours
Tier 6	35 to 43	1600 (max)	Every 24 hours

March 19 2024

Inputs and Outputs (Cards)

ines PGpage

Checkout

Inputs & Outputs, CheckOut

Input		Ouput
merchant		returnStatus
–	terminalId	–	statusCode
–	channel	–	statusMsg
–	merchantTransactionId	–	statusDescription
customer		paymentStatus
–	customerInfo	transactionID
–	customerName	amount
–	shippingAddress	–	value
–	billingAddress	–	currency
–	extendedInfo	merchant	terminalId
Transaction		merchant	channel
–	transactionTimestamp	merchant	merchantTransactionId
–	description	PaymentType
–	paymentType	paymentMethod
–	paymentMethod	amount
–	amount	–	value
–	value	–	currency
–	currency	Status
deviceInfo* (see dedicated table – Table – Synchronous & asynchronous notifications)		tokenList
customerInfo		–	tokenType
–	key	–	value
–	value	–	maskedPAN
originalTransaction		–	expireDate
–	id	formContext
–	datetime	expiry	string (date-time)
–	recipientId	execution
tokenisation		–	startTime
–	tokenisationRequest	–	endTime
–	tokeniseCard
–	paymentTokens
–	tokenType
–	value
mandate
–	mandateId
–	mandateType
–	mandateCreationOnly

Payment method card: Card

Inputs & Outputs, CARD

Input		Output
cardInfo		actionProcessed
–	PAN	–	id
–	secureCode	–	ty
–	validationDate	–	executed
–	cardholderName	tokenResponse
–	createToken	–	tokenType
		–	Value
		–	tokenName
		–	maskedPAN
		–	expireDate
instalmentPlan
–	id

Transaction status

It is possible to receive the transaction statuses below:

IN PROCESSING – meaning that the transaction initiated is now in processing.
PARTIAL – it is pending to receive information.
SUCCESS – informing transaction OK, the transaction was executed with success.
DECLINED – indicating that the transaction was declined by an operation intervenient.
TIMEOUT – informing a potential communication error.
ERROR – indicating that the transaction was declined by external system.

After the transaction is in processing, it will only retrieve the “partial” status if some action is pending to be taken. After that it will send the transaction status.

Notifications (Merchant notifications)

The Merchant can receive notifications by email or endpoint (notification assembling to the status inquiry – Checkout Status), however, only a notification will be sent for each transaction.
Notifications are sent by endpoint straight to the URL provided by the Merchant. The parameterization of this endpoint needs to be done on the SIBS Gateway Backoffice.
For email notifications, only one notification will be sent per transaction.
For URL notifications not accomplished, retries will be attempted. Each time SIBS Gateway receives a transaction, a notification will be sent with the transaction status in real time.
Every day SIBS Gateway sends a summarized email with the newest failed notifications (email needs to be registered on the Backoffice).
There is no guarantee on message order, especially if the time difference between the notifications is smaller than the time it takes to process them or by any communication or systems issues. Once the issues are sort out, new notifications will arrive in real time and old notifications will be resent. In case no notification is received, the option “Checkout Status” should be used before rejecting any transaction.

There are two types of notifications, the Synchronous and the Asynchronous:

Asynchronous

Make request – Need action – Get response;

Synchronous

Make request – Get response→CARD

Complex types

MerchantNotificationRequest

MerchantNotificationResponse

statusCode

string (Maximum 11 Text) (ex: 000)

Mandatory

statusMsg

String (Maximum 256 Text) (ex: Success)

Mandatory

Possible values are {“Success”, “Partial”, “Declined”, “InProcessing“, “Pending”, “Timeout”, “Error”}.

notificationID

PaymentNotificationId (UUID – Exact36Text)

Mandatory

Examples

On this subchapter, it is possible to find examples of webhook notifications sent by SIBS Gateway and the answer that the customer application should give. Answering this message is very important to avoid more unnecessary notifications sent by SIBS Gateway.

Request example

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000" 
    },

    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "DaBzrs8ayhQpi1EeenHe",
    "transactionDateTime": "2022-11-12T16:18:53.127Z",

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

    "merchant": {
        "terminalId": 49180 
    },

    "paymentType": "AUTH",
    "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e"
}

Response example

{
    "statusCode": "200",
    "statusMsg": "Success",
    "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" 
}

Cardholder Initiated Transaction with Type Recurring Example:

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
},

    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s24nZiFtu15SCiW9vpDm",
    "transactionDateTime": "2022-12-27T16:05:27.585Z",

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

    "merchant": {
        "transactionId": "6637262",
        "terminalId": 45546,
        "merchantName": "COMERCIANTE DO LEGACY"
    },

    "paymentType": "PURS",
    "notificationID": "a433453e-6e40-4f53-a80d-4985cffa36f6",

    "merchantInitiatedTransaction": {
        "type": "RCRR",
        "validityDate": "2023-06-30T01:00:00+01:00",
        "amountQualifier": "ACTUAL",
        "schedule": {
            "initialDate": "2022-12-27T00:00:00Z",
            "finalDate": "2023-01-06T00:00:00Z",
            "interval": "DAILY"
        }
    }
}

Merchant Initiated Transaction with Type Recurring Example:

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000" 
    },

    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2K9YuqPQuC9NkdCvDA4",
    "transactionDateTime": "2023-01-06T00:00:03.378Z",

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

    "merchant": {
        "terminalId": 45546,
        "merchantName": "COMERCIANTE DO LEGACY" 
    },

    "paymentType": "MITR",
    "notificationID": "3a9d8777-292d-48fb-971c-6e6558de0fd5",

    "merchantInitiatedTransaction": {
        "type": "RCRR",
        "amountQualifier": "ACTUAL"
    }
}

Cardholder Initiated Transaction with Type UCOF Example:

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },

    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2bDX8mjiFZU5ZwfvSvR",
    "transactionDateTime": "2023-01-06T16:57:11.2Z",

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

    "merchant": {
        "transactionId": "3064371",
        "terminalId": 45546,
        "merchantName": "GOMERCIANTE DO LEGACY"
    },

    "paymentType": "AUTH",
    "notificationID": "45d108d3-2cef-41a6-90af-a3bdb4af244a",

    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "validityDate": "2023-01-31T00:00:00Z",
        "amountQualifier": "ESTIMATED"
    }

}

Merchant Initiated Transaction with Type UCOF Example:

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },

    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2nYaNUC3hFpqd0HGq4Z",
    "transactionDateTime": "2022-12-23T10:48:39.153Z",

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

    "merchant": {
        "transactionId": "6540474",
        "terminalId": 45546,
        "merchantName": "GOMERCIANTE DO LEGACY"
    },

    "paymentType": "MITR",
    "notificationID": "c9786e7e-dc2a-4611-8a31-4b8197f41138",

    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "amountQualifier": "ESTIMATED"
    }

}

Response example

{
    "statusCode": "200",
    "statusMsg": "Success",
    "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" 
}

Error message

Checkout Request

Error code	Message to the Merchant	Message to the Client	Owner	What to do?
12.110.1201	Wrong parameterization in the amount, expiration date, token, Merchant code or terminal code.	Please try again later.	Merchant	Checkout and payment received data for reference generation is incomplete, has to send (Amount and Expiration date).
12.110.1202	Wrong parameterization. Missing data.	Please try again later.	Merchant	Evaluate if the message is correctly formatted (Check if it is parameterizing correctly) according to the SLA.
12.110.1203	SIBS internal error. Please try again later.	Service not available. Please try later.	SIBS	Try again later.
12.110.1204	SIBS internal error. Please try again later.	Service not available. Please try later.	SIBS	Try again later.
12.110.1205	SIBS internal error. Please try again later.	Service not available. Please try later.	SIBS	Try again later.
12.110.1206	SIBS internal error. Please try again later.	Service not available. Please try later.	SIBS	Try again later.

Card

Error code	Message to the Merchant	Message to the client	Owner	What to do?
10.105.0001	Invalid payment entity	Entity not valid, please try again later.	Merchant	Please verify that the correct Merchant entity is being used.
10.103.0003	No card record	Card not valid please try again later.	SIBS	Please verify log.
10.103.0004	Not sufficient funds	Not sufficient funds, try again	Client	Please assure that the account has enough funds
10.103.0005	Invalid card number	Card number not valid try again.	Client	Please insert the correct card number
10.103.0006	Expired card	Expired card, please verify with your bank.	Client	Please note that your card has expired
10.103.0007	Card Cancelled	Your card has been Cancelled please verify with your bank.	Client	Please verify with your bank
10.103.0008	Inactive card	Inactive card, please verify with your bank.	Client	Please verify with your bank
10.103.0009	This card has been reported as stolen	Pick-up card, please verify with your bank.	Client	Please verify with your bank
10.103.0010	Blocked card	Blocked Card, please verify with your bank.	Client	Plese verify with your bank
10.103.0011	Invalid CVV	Invalid please check CVV double	Client	Please insert the correct CVV number
10.103.0012	Card limit exceeded	Card limit exceeded, please verify with your bank.	Client	Please verify with your bank
10.103.0013	Wrong expiry date	Wrong expiry date, please double check	Client	Please insert the correct card expiration date
10.105.0014	Invalid refund amount	N/A	Merchant	Please assure that the Refund is equal to the total amount or less
10.103.0015	Invalid card (Cannot process operation – fraud)	Invalid card, please verify with your bank.	Client	Please verify with your bank
10.105.0016	Invalid expiry date	Invalid expiry date, please double check	Client	Please verify with your bank or insert a valid Expiration date
10.103.0017	Wrong code	Wrong Code, please double check	Client	Please try again
10.103.0018	Wrong Code, 3 tentative exceed	Wrong Code, 3 tentative exceed, please verify with your bank.	Client	Please contact your bank
10.105.0017	Cancellation amount exceeds authorized amount	Cancellation amount exceeds authorized amount	Merchant	Please assure that the Authorisation is not finalised
10.105.0018	Authorisation is cancelled	The Authorisation was cancelled	Merchant	Please assure that the Authorisation is not finalized
10.105.0019	Authorisation is already used	N/A	Merchant	Please assure that this Authorisation belongs to this transaction.
10.105.0020	Purchase amount exceeds authorized amount	N/A	Merchant	Please assure that the purchase is Equal to the total amount or less
10.105.0021	Purchase already refunded	Purchase already refunded	Merchant	Please assure that this operation belongs to this transaction.
10.105.0022	Amount is below commission	Amount is below commission	Merchant	Please assure the minimum amount to allow the fee charge
90.000.0001	Exception	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS
90.000.0003	Error in message format	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS

Payment request

Error code	Message to the Merchant	Message to the Client	Owner	What to do?
12.110.1301	Wrong parameterization. Missing data.	Service not available. Please try again later.	Merchant	Please check parameterization on the checkout, its needed to invoke the form script to send the signature (Form context). Please verify if the amount, expiration date, token, Merchant code or terminal code are being sent correctly.
12.110.1302	Wrong parameterization. Missing data.	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1303	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1304	Wrong parameterization in payment type (Authorisation, Purchase, Capture, or Refund)	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1305	Wrong parameterization in payment method (Card, MB WAY, or Reference)	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1306	Wrong parameterization in payment method (Card, MB WAY, or Reference)	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1307	Wrong parameterization in amount, expiration date, token, Merchant code or terminal code.	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1308	Wrong amount.	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1309	Wrong currency.	Service not available. Please try again later.	Merchant	Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA.
12.110.1310	Transaction already finalized.	Service not available. Please try again later.	Merchant	Need to input a valid transaction Id that it is not finalized.
12.110.1 311	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1312	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1313	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Payment does not fail, only tokenisation fails. No Action.
12.110.1314	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1315	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1316	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1 317	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1318	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1319	Declined.	Declined.	SIBS	Try again later.
12.110.1320	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1321	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1322	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1323	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.
12.110.1324	SIBS internal error. Please try again later.	Service not available. Please try again later.	SIBS	Try again later.

March 18 2024

Merchant notifications

ines PGpage

The Merchant can receive notifications by email or endpoint (notification assembling to the status inquiry – Checkout Status), however, only a notification will be sent for each transaction.
Notifications are sent by endpoint straight to the URL provided by the Merchant. The parameterization of this endpoint needs to be done on the SIBS Gateway Backoffice.
For email notifications, only one notification will be sent per transaction.
For URL notifications not accomplished, retries will be attempted. Each time SIBS Gateway receives a transaction, a notification will be sent with the transaction status in real time.
Every day SIBS Gateway sends a summarized email with the newest failed notifications (email needs to be registered on the Backoffice).
There is no guarantee on message order, especially if the time difference between the notifications is smaller than the time it takes to process them or by any communication or systems issues. Once the issues are sort out, new notifications will arrive in real time and old notifications will be resent. In case no notification is received, the option “Checkout Status” should be used before rejecting any transaction.

Notification MULTIBANCO – Asynchronous: Make request – Need action – Get response

Complex Types

MerchantNotificationRequest

Body

MerchantNotificationResponse

Body

statusCode

string (Maximum 11 Text) (ex: 000)

Optional

statusMsg

String (Maximum 256 Text) (ex: Success)

Optional

Possible values are {“Success”, “Partial”, “Declined”, “InProcessing”, “Pending”, “Timeout”, “Error”}.

notificationID

PaymentNotificationId (UUID – Exact36Text)

Optional

Error message

Multibanco

Error code	Message to the Merchant	Message to the Client	Owner	What to do?
10.107.0001	Invalid payment entity	Entity not valid, Try again later.	Merchant	Please verify that the correct Merchant entity is being used.
10.107.0002	Invalid reference minimum amount	Invalid reference minimum, amount please try again.	Merchant	Please verify the parameterization in the amount
10.107.0003	Invalid reference maximum amount	Invalid reference maximum amount please try again.	Merchant	Please verify the parameterization in the amount
10.107.0004	Invalid currency	Invalid currency try again.	Merchant	Please verify the parameterization in the currency accepted
10.107.0005	Invalid NIB	Invalid NIB please try again.	Client	Please verify you are using the correct NIB
10.107.0006	Invalid reference initial date time	Invalid reference initial date time try again.	Merchant	Please verify the parameterization in time accepted
10.107.0007	Invalid reference limit date time	Invalid reference limit date time try again.	Merchant	Please verify the parameterization in time accepted
10.107.0008	Invalid Email	Invalid Email try again.	Client	Please insert the email used on the registration
10.107.0009	Payment entity is not active	Payment entity is not active, try later	Merchant	Please verify your entity, if it is the one in the SLA
10.107.0010	Reference generation not allowed for the payment entity	Reference generation not allowed try later.	Merchant	Please verify your entity, if it is the one in the SLA
10.107.0011	Payment reference not found	SIBS Internal error, Please try again later.	SIBS	SIBS Internal error, Please try again later.
10.107.0012	Payment reference is cancelled	Payment reference is cancelled.	Merchant	Please verify your reference was cancelled.
10.107.0013	Payment reference already paid	Payment reference already paid.	Merchant	Please verify your reference is already paid.
10.107.0014	Invalid operation	Invalid operation, try later.	SIBS	SIBS Internal error, Please try again later.
90.000.0001	Exception	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS
90.000.0003	Error in message format	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS

March 18 2024

1

Eduardo Bica PGpage

Payment Gateway Portugal

The payments partner that helps your business grow

Receive MB WAY, MULTIBANCO and bank card payments on your website or store.

SIBS Payment solution for your online store

Offer convenience and security to your clients with our solutions.

Accept payments in a practical and secure way

Front office operations

Backoffice operations

Capture

Refund

Cancellation

In-App Operative

Checkout

Inputs & Outputs, CheckOut

Transaction status

Notifications (Merchant notifications)

Complex types

MerchantNotificationRequest

MerchantNotificationResponse

Examples

Request example

Response example

Cardholder Initiated Transaction with Type Recurring Example:

Merchant Initiated Transaction with Type Recurring Example:

Cardholder Initiated Transaction with Type UCOF Example:

Merchant Initiated Transaction with Type UCOF Example:

Response example

Error message

Checkout Request

Card

Payment request

Complex Types

Error message

Multibanco