Financial operations support the purchase process:
- Purchase;
- Return;
- Purchase;
- Authorisation;
- Purchase after Authorisation;
- Cancellation of Authorisation;
- Cancellation.
The Merchant can also consult the status of a financial operation whenever it is not possible to obtain the result of the operation, which makes it possible to avoid cancelling the transaction.
Merchant Financial Operation WS
The webservice MerchantFinancialOperationWS allow the merchant to register a financial operation for a specific User, identified by an Alias.
The financial operation consists of:
- Type – Determines whether confirmation is required from the User via the MB WAY app for the financial transaction to proceed. Purchase and Purchase Authorisation type operations require confirmation from the User;
- Monetary value;
- Currency;
- Unique transaction ID – Created by the Merchant application in the “ReferencedFinancialOperation” data block.
The result of the confirmation is communicated to the Merchant application through the FinancialOperationAsyncResult web service.
Here are the elements to consider within the input of the merchant financial operation WS request:
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
messageType | [1 -1] | String | 5 | Message code with a value of ‘N0003’ |
aditionalData | [0 -1] | String | 100 | Information that is sent to the User and that helps to identify characteristics of their purchase. |
Alias | [1 -1] | Alias | Entity Service Alias | Alias identifying the service, which can be any Alias already registered and confirmed. |
financialOperation | [1 -1] | FinancialOperation | Entity Financial Operation | Details of the financial operation requested. |
referencedFinancialOperation | [0 -1] | FinancialOperation | Entity Financial Operation | Details of the previous financial operation for which you are carrying out a new action. |
Merchant | [1 -1] | Merchant | Merchant Entity | Merchant Identifier. |
messageProperties | [1 -1] | MessageProperties | Message Properties Entity | General properties common to all messages. |
financialOperationProperties | [0 -1] | FinancialOperationProperties | Financial Operation Propertities entrity | General properties of financial operations, mandatory for operations initiated with the MB WAY In-App operative. |
The several entities are defined as follows:
Service Alias entity
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
aliasName | [1 -1] | String | 150 | Alias |
aliasTypeCode | [1 -1] | String | 3 | ‘001’ – Mobile phone (must follow the formatting: <indicative>#<mobile phone number>) ‘002’ – E-mail ‘010’ – User token |
Merchant Entity
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
iPAddress | [1 -1] | String | 15 | Merchant’s IP address. |
posID | [1 -1] | String | 9 | Merchant POS identifier. |
MerchantProperties Entity
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
channel | [1 -1] | String | 2 | ’01’ – Mobile (When the purchase is made on a mobile app) ’02’ – TV (When the purchase is made on TV, e.g. tv-commerce) ’03’ – Web (When the purchase is made on a website) ’04’ – Vending (When the purchase is made in a vending machine) ’05’ – Point of Sale (When the purchase is made in a physical shop) This attribute must be filled in according to the channel where the transaction is being made. Ex. 1: A Merchant/Integrator who is integrating to make MB WAY available in their mobile app and on their website can only do one integration. However, they must fill in this field differently depending on whether the transaction originates from the mobile app ’01’ or the website ’03’. Ex. 2: A Merchant/Integrator who has a physical shop and makes MB WAY available on a tablet should fill in this attribute with the possible value ’05’ – Point of Sale. |
apiVersion | [1 -1] | String | 5 | ‘1’ |
channelTypeCode | [1 -1] | String | 10 | ‘VPOS’ |
networkCode | [1 -1] | String | 10 | ‘MULTIB’ |
serviceType | [1 -1] | 2 | 2 | ‘01’ |
timestamp | [1 -1] | DateTime | N.A. | Date and time the operation was registered, according to the Merchant’s system. |
FinancialOperation entity
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
operationTypeCode | [1 -1] | String | 3 | ‘022’ – Purchase ‘023’ – Return ‘024’ – Purchase authorisation ‘025’ – Purchase after authorisation ‘026’ – Cancellation of authorisation ‘048’ – Cancellation |
merchantOprId | [1-1] | String | 20 | Unique identifier for each operation. |
amount | [1-1] | Integer | N.A. | Amount of the purchase or authorisation. Filled in with at least 3 digits, the last two corresponding to decimal places. Filling in this attribute is based on the rule defined in currencyCode. It must follow the formatting: no comma or full stop and always include centimes, even if they are zeros. Example: To refer to 3 euros, put 300. |
currencyCode | [1-1] | String | 4 | Currency code with the value ‘9782’. (the first 3 digits indicate the currency, the last indicates the number of decimal places, at this stage only the value for EUR is supported). |
FinancialOperationProperties entity(*)
Attribute | Status | Type | Size | Rules / Observations |
---|---|---|---|---|
appFinOpProperties | [0-1] | AppFinOpProperties | AppFinOpProperties entity | Mandatory general properties for operations initiated with the MB WAY In-App Operative. |
AppFinOpProperties entity
In the case of some Merchant apps, which although they don’t allow you to purchase products, do allow you to initiate payment at the point of sale with a QR Code, it is possible to have in-app operation integrated.
Attribute | Status | Type | Size | Rules / Observations |
---|---|---|---|---|
purchaseToken | [1-1] | String | 128 | Operation Token Value. |
initialTimestamp | [1-1] | DateTime | N.A. | Start time of the financial transaction according to the Merchant’s system. In the case of using the In-App operative, it must be filled in with the same value that was passed by parameter to the MB WAY app. |
Below, we provide you an example of input body example:
<arg0>
<messageType>N0003</messageType>
<aditionalData>Bola de Futebol</aditionalData>
<alias>
<aliasName>351#960000000</aliasName>
<aliasTypeCde>001</aliasTypeCde>
</alias>
<financialOperation>
<amount>2550</amount>
<currencyCode>9782</currencyCode>
<operationTypeCode>022</operationTypeCode>
<merchantOprId>1001</merchantOprId>
</financialOperation>
<referencedFinancialOperation>
<amount></amount>
<currencyCode></currencyCode>
<operationTypeCode></operationTypeCode>
<merchantOprId></merchantOprId>
</referencedFinancialOperation>
<merchant>
<iPAddress>255.255.255.255</iPAddress>
<posId>9999</posId>
</merchant>
<messageProperties>
<channel>01</channel>
<apiVersion>1</apiVersion>
<channelTypeCode>VPOS</channelTypeCode>
<networkCode>MULTIB</networkCode>
<serviceType>01</serviceType>
<timestamp>2001-12-17T09:30:47Z</timestamp>
</messageProperties>
</arg0>
If a request for a financial transaction is made as part of the in-app operation, the example input body must have the following additional XML code:
<arg0>
<financialOperationProperties>
<appFinOpProperties> <purchaseToken>12345678oabcdef</purchaseToken>
<initialTimestamp>2001-12-17T09:29:21Z</initialTimestamp>
</appFinOpProperties>
</financialOperationProperties>
</arg0>
Below, we describre the elements of the response to the request performed within a financial operation:
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
amount | [0-1] | Integer | N.A. | Amount of the purchase or authorisation. Filled in with at least 3 digits, the last two corresponding to decimal places. Filling in this attribute is based on the rule defined in currencyCode. It must follow the formatting: no comma or full stop and always include centimes, even if they are zeros. Example: To refer to 3 euros, put 300. |
currencyCode | [0-1] | String | 4 | Currency code with the value ‘9782’ (the first 3 digits indicate the currency, the last indicates the number of decimal places), at this stage only the value for EUR is supported). |
merchantOperationID | [0-1] | String | 20 | Unique operation code sent by the Merchant. |
statusCode | [1-1] | String | 3 | Return code |
timestamp | [1-1] | DateTime | N.A. | Date and time the operation was registered, according to the Merchant’s system. |
token | [0-1] | String | 32 | Security token to validate the confirmation response. |
Here’s a body example of the output of a financial operation request:
<return>
<amount>2250</amount>
<currencyCode>9782</currencyCode>
<merchantOperationID>1001</merchantOperationID>
<statusCode>000</statusCode>
<timestamp>2001-12-17T09:30:47Z</timestamp>
<token>123456789dfghjklcvbnm6789ertyui4</token>
</return>v
Financial Operation Async Result
As mentioned above, this webservice allows the Merchant receive the result of a requested financial operation, after having been accepted or rejected by the User through the MB WAY app (asynchronous).
Its delivery is validated through the http response to correctly finalize the operation.
This service is supplied by the Merchant application and must comply with the following naming:
@WebService(name="FinancialOperationAsyncResult", targetNamespace="http://webservices.sibsmerchant.com/")
public class FinancialOperationAsyncResult
@WebMethod
public void financialOperationResult (requestFinancialOperationResult arg0)
Below, we provide you the elements to consider within the input of the financial operation request result:
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
amount | [0-1] | Integer | N.A. | Amount of the purchase or authorisation. Filled in with at least 3 digits, the last two corresponding to decimal places. Filling in this attribute is based on the rule defined in currencyCode. It must follow the formatting: no comma or full stop and always include centimes, even if they are zeros. Example: To refer to 3 euros, put 300. |
currencyCode | [0-1] | String | 4 | Currency code with the value ‘9782’ (the first 3 digits indicate the currency, the last indicates the number of decimal places), at this stage only the value for EUR is supported). |
merchantOperationID | [0-1] | String | 20 | Unique operation code sent by the Merchant. |
statusCode | [1-1] | String | 3 | Return code |
timestamp | [1-1] | DateTime | N.A. | Date and time the operation was registered, according to the Merchant’s system. |
token | [0-1] | String | 32 | Security token to validate the confirmation response. |
Merchant Financial Operation Inquiry WS
This web service allows the Merchant to inquire the financial operation status, basing the search on the operation identifiers (Merchant Operation Ids).
A financial operation status inquiry may comprise a list of operations performed in several POS terminals of that Merchant, including the operations of an inactive POS terminal that can also be inquired by the Merchant.
This web service was implemented so that the operation status can be inquired, whenever an asynchronous communication is not possible, thus avoiding that successfully completed operations might be cancelled.
Below, we provide you the elements to consider within the input of the financial operation request result:
Attribute | Status | Type | Length | Rules / observations |
---|---|---|---|---|
messageType | [1 – 1] | String | 5 | Message code with the value ‘N0004’. |
operationInformation | [1 – 1] | OperationInformation | 20 | Operation identifier. |
financialOperationInquiry | [1 -∞] | FinancialOperationInquiry | 20 | Operation identifiers list for search. |
merchant | [1 – 1] | Merchant | Merchant Entity | Merchant identifier. |
messageProperties | [1 – 1] | MessageProperties | Message Properties | Set of general properties, present in all messages. |
Below, we provide you with a description of the entities:
Attribute | Status | Type | Length | Rules / observations |
---|---|---|---|---|
merchantOprId | [1 – 1] | String | 20 | Operation unique identifier. |
Attribute | Status | Type | Length | Rules / observations |
---|---|---|---|---|
merchantOprId | [1 – 1] | String | 20 | Operation unique identifier. |
<arg0>
<messageType>N0004</messageType>
<operationInformation>
<merchantOprId>111110003543</merchantOprId>
</operationInformation>
<financialOperationInquiry>
<merchantOprId>111110003519</merchantOprId>
</financialOperationInquiry>
<financialOperationInquiry>
<merchantOprId>111110003539</merchantOprId>
</financialOperationInquiry>
<merchant>
<iPAddress>255.255.255.255</iPAddress>
<posId>9999</posId>
</merchant>
<messageProperties>
<channel>02</channel>
<apiVersion>1</apiVersion>
<channelTypeCode>VPOS</channelTypeCode>
<networkCode>MULTIB</networkCode>
<serviceType>01</serviceType>
<timestamp>2001-12-17T09:30:47+01:00</timestamp>
</messageProperties>
</arg0>
Consider the following elements regarding the response to a financial operation status inquiry:
Attribute | Status | Type | Size | Rules / observations |
---|---|---|---|---|
operationInformation | [1-1] | OperationInformation | Operation information entity. | Operation identifier |
referencedFinancialOperation | [0-∞] | FinancialOperationInquiryRes | FinancialOperationInquiryResEntity | Details of the previous financial operation, which is now being subject to a new action. |
statusCode | [1-1] | String | 3 | Return code |
timestamp | [1-1] | DateTime | N.A. | Date and time the operation was registered, according to the Merchant’s system. |
Please find a description of the entities below:
Attribute | Status | Type | Length | Rules / observations |
---|---|---|---|---|
merchantOprId | [1 – 1] | String | 20 | Operation unique identifier. |
merchantOprTimestamp | [1 – 1] | DateTime | N.A. | Operation date and time at the Merchant system. |
merchantOprSttCde | [0 – 1] | Integer | N.A. | 1 – Recorded: Financial operation recorded at SIBS to start the authorisation process 2 – Authorised: Financial operation authorised by the client 3 – Executed: Financial operation authorisation completed at the Issuer 4 – Successful: Asynchronous response with successful operation code, after completion 5 – Cancelled: Financial operation cancelled by the user 6 – Rejected: Financial operation rejected by SIBS 7 – Cancelled: Financial operation cancelled by the Merchant 8 – Timeout: Operation cancelled for timeout -1 – Error: Operation ID not found |
merchantOprSttCdeTimestamp | [1 – 1] | DateTime | N.A. | Date and time when the operation was updated to the current status. |
Below, we provide you an example of output body:
<return>
<operationInformation>
<merchantOprId>111110003543</merchantOprId>
</operationInformation>
<referencedFinancialOperation>
<merchantOprId>111110003519</merchantOprId>
<merchantOprTimestamp>2016-06-02T16:56:25.760Z</merchantOprTimestamp>
<merchantOprSttCde>8</merchantOprSttCde>
<merchantOprSttCdeTimestamp>2016-06-02T16:56:45.895Z</merchantOprSttCdeTimestamp>
</referencedFinancialOperation>
<referencedFinancialOperation>
<merchantOprId>111110003539</merchantOprId>
<merchantOprSttCde>-1</merchantOprSttCde>
</referencedFinancialOperation>
<statusCode>000</statusCode>
<timestamp>2016-06-09T11:26:32.036+01:00</timestamp>
</return>
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.