SEPA & Instant Payments workflow
The flow for SEPA Payments and Instant Payments follows the generic guidelines shown in the Payment Workflow page.
In addition, SEPA Payments and Instant Payments have some more API to call:
- an additional /verify2 API to call after the /verify, which accepts as input a flag to confirm that the user has viewed and accepted the Verification Of Payee
- (only for Instant Payments) an additional /execution/status API to get the actual execution status of the payment (i.e. the verification that the funds have reached the creditor account). This API should be called in polling mode.
Instant Payment flow diagram
Here's a complete schema of a login + Instant Payment flow:
Complete example - instant payment
Here you will find a complete workflow for the bank transfer operation, with all the requests and responses that a TPP should manage. The authorization phase (what happens between the /private/auth/security/sca/{resourceId}/approach and the TPP_CALLBACK_AFTER_SCA) is a blackbox for the TPP, since it's managed completely by Mediobanca Premier systems. This example refers to the Instant Payment case, which has one additional step at the end of the flow (in respect to other payment operations) to obtain the actual execution status for the operation.
Prepare data (optional)
This API is used to obtain some generic information about the payment operation (e.g. the allowed dates, holidays, the available currencies, etc.)
Response:
{
"data": {
"abi": "03058",
"sepa": true,
"swift": true,
"swiftcontractSigned": true,
"initialData": {
},
"executionDateMinimumWireTransferAtBank": "03/09/2019",
"executionDateMinimumWireTransferInternal": "03/09/2019",
"flagUrgency": false,
"ABI": "03058",
"addBeneficiary": true,
"editBeneficiary": true,
"today": "03/09/2019",
"executionDateLimit": "03/09/2020",
"holidays": ["01/01/2020",
"25/12/2019",
"01/05/2020",
"13/04/2020",
"26/12/2019"],
"currency": {
"currencyList": [{
"label": "Euro - EUR",
"value": "EUR",
"rate": ""
},
{
"label": "Dollaro americano - USD",
"value": "USD",
"rate": ""
},
...
{
"label": "Zloty polacco - PLN",
"value": "PLN",
"rate": ""
}],
"updated": {
"date": "03/09/2019",
"hour": "17:56"
},
"selected": "EUR"
},
"SEPA": true,
"SWIFT": true,
"SWIFTContractSigned": true,
"countries": [{
"label": "ABU DHABI",
"value": "0238"
},
{
"label": "AFGHANISTAN",
"value": "0002"
}
...
]
},
"result": {
"requestId": "XW6NIgrZ5gsAAG@Cr04AAABV",
"outcome": "SUCCESS",
"flushMessages": false,
"messages": []
},
"_links": {
"next": {
"href": "verify",
"method": "POST"
},
"self": {
"href": "prepare",
"method": "GET"
},
"curies": [{
"href": "https://external-api.mediobancapremier.io/private/customers/1134596/products/0001486570/moneyTransfer/{rel}",
"name": "moneyTransfer"
}]
},
"_embedded": {
}
}Insert and validate data
With this API, you can insert the data for the payment; note that this API does not actually execute the payment, which still has to be authorized.
To conform to the Instant Payment directive, you have to show the "vop" additional check results to the customers, informing them if the recipient name inserted matches completely, partially or not the creditor account owner name. The possible values for the outcome of the verification are described in the Swagger documentation of the /verify API.
Request:
{
"data": {
"moneyTransferAmount": {
"currency": "EUR",
"amount": "1.00"
},
"flagUrgency": false,
"type": "INSTANT",
"moneyTransferExecutionDate": "03/09/2019",
"ibanBeneficiary": "IT78Q0347551609CC0099237243",
"beneficiaryName": "Mario Rossi",
"description": "payment to Mario Rossi"
}
}Response:
{
"data": {
"totalAmount": {
"amount": "1.00",
"currency": "EUR"
},
"commissions": {
"commissions": "0.00",
"currency": "EUR"
},
"equivalentAmount": {
"amount": "",
"currency": ""
},
"bankName": "UNICREDIT BANCA DI ROMA SPA",
"branchName": "ROMA 80 - PIAZZA MONTE",
"address": "PIAZZA MONTE DI PIETA, 3 - 00186 ROMA (RM)",
"moneyTransferOffline": false,
"holdersEnabled": false,
"additionalChecks":[
{"vop":
{
"status":"CMTC",
"description":"close-match",
"beneficiaryName":"Giovanni Bianchi",
"info":"Corrispondenza parziale"
}
}
]
},
"result": {
"requestId": "XW6O4grZ5gsAAG@Css4AAABd",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": []
},
"_links": {
"next": {
"href": "5c99d862-6917-4006-b9a6-e5677e8a867b/verify2",
"method": "POST"
},
"self": {
"href": "verify",
"method": "POST"
},
"curies": [{
"href": "https://external-api.mediobancapremier.io/private/customers/1134596/products/0001486570/moneyTransfer/{rel}",
"name": "moneyTransfer"
}]
},
"_embedded": {},
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
}
}Acceptance of Verification of Payee
With this API, the customer acknowledges the Verification of Payee and confirms explicitly the operation.
Request:
{
{
"data":
{
"acknowledgmentVop":true
}
}
}Response:
{
"data": {},
"result": {
"requestId": "XW6O4grZ5gsAAG@Css4AAABd",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": []
},
"_links": {
"next": {
"href": "5c99d862-6917-4006-b9a6-e5677e8a867b/execute",
"method": "PUT"
},
"self": {
"href": "5c99d862-6917-4006-b9a6-e5677e8a867b/verify2",
"method": "POST"
},
"curies": [{
"href": "https://external-api.mediobancapremier.io/private/customers/1134596/products/0001486570/moneyTransfer/{rel}",
"name": "moneyTransfer"
}]
},
"_embedded": {},
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
}
}Start authorization flow
Response
{
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
},
"result": {
"result": {
"requestId": "XW6O4grZ5gqXAG@Css4AAACZ",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": []
},
"_links": {},
"_embedded": {},
"data": {
"scaRedirectURL": "https://clienti.mediobancapremier.com/sca-authorize/?resourceId=5c99d862-6917-4006-b9a6-e5677e8a867b",
"chosenScaApproach": "REDIRECT"
}
}Check authorization status
Response
{
"data": {
"creationTimestamp": "2019-09-03T18:14:25",
"authorizationStatus": "AUTHORIZED",
"executionStatus": "PENDING"
},
"result": {
"requestId": "XW6RYgra5AsAAO6Nv94AAABY",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": []
},
"_embedded": { },
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
}
}Execute operation
This API actually executes the payment, with the data the customer already inserted before. The operation with those data has been authorized with a SCA (if not, the /execute API will fail).
Response:
{
"data": {
"cro": "1909031807313004480160433140IT12470",
"moneyTransferOffline": false,
"sendEmailEnabled": true
},
"result": {
"requestId": "XW6PwgrZ5gsAAG@CtFYAAABY",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": [{
"code": "BONIFICO24",
"message": "Hai effettuato un bonifico a Mario Rossi!",
"type": "SUCCESS"
},
{
"code": "BONIFICO23",
"message": "Una volta prodotta, troverai la contabile delle tue operazioni nell'Archivio presente nel menù di destra. Seleziona il conto e le date di riferimento. La troverai in un click!",
"type": "INFO"
}]
},
"_links": {
"self": {
"href": "5c99d862-6917-4006-b9a6-e5677e8a867b/execute",
"method": "PUT"
},
"curies": [{
"href": "https://external-api.mediobancapremier.io/private/customers/1134596/products/0001486570/moneyTransfer/{rel}",
"name": "moneyTransfer"
}]
},
"_embedded": {
"polling": {
"href": "https://api.mediobancapremier.com/private/customers/1134596/products/0001486570/moneyTransfer/5c99d862-6917-4006-b9a6-e5677e8a867b/execution/status",
"method": "GET"
}
},
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
}
}Retrieve execution status
The instant payment operation should finish in maximum 10 seconds; so you can invoke the following endpoint, in polling mode, to get the actual execution status (i.e. to know if the funds have been delivered to the creditor account). This API should be called only if the previous /execute API finished with a success status (200).
Our advice is to call this endpoint every 3/5 seconds, with a delay of at least one second since the end of the /execute API call. The final status of the payment should be available after a maximum of 10 seconds; to have a margin, in case of any problem, we suggest to schedule the last call in polling mode after 15 seconds.
Response:
{
"data": {
"executionStatus": "OK|KO|PENDING",
"executionStatusDescription": "Description in case of error occurred"
},
"result": {
"requestId": "XW6PwgrZ5gsAAG@CtFYAAABY",
"outcome": "SUCCESS",
"flushMessages": true,
"messages": [{
"code": "BONIFICO24",
"message": "Hai effettuato un bonifico a Mario Rossi!",
"type": "SUCCESS"
},
{
"code": "BONIFICO23",
"message": "Una volta prodotta, troverai la contabile delle tue operazioni nell'Archivio presente nel menù di destra. Seleziona il conto e le date di riferimento. La troverai in un click!",
"type": "INFO"
}]
},
"_links": {
"self": {
"href": "5c99d862-6917-4006-b9a6-e5677e8a867b/execution/status",
"method": "PUT"
},
"curies": [{
"href": "https://external-api.mediobancapremier.io/private/customers/1134596/products/0001486570/moneyTransfer/{rel}",
"name": "moneyTransfer"
}]
},
"_embedded": {},
"resources": {
"resourceId": "5c99d862-6917-4006-b9a6-e5677e8a867b"
}
}