Advice messages (webhooks) Archives - Cardlink for Developers

Advice messages (webhooks)

Advice messages is a new value-added service that merchants can optionally configure if their backend system benefits from such notifications (XML requests).

Those XML messages refer to manual actions that can be performed upon a transaction through Back Office tool.

The manual actions through Back Office tool for which a respective message can be sent to the merchant are Capture of preauth, Void, Refund and Cancel recurring.

Moreover, advice message can also be sent for initial payment transaction and recurring child.

Primarily, it is mandatory to choose the XML version that e-commerce platform shall use for the XML message sent.
If merchant’s implementation for VPOS requests is based on digest calculation, then 2.1 should be chosen.
If merchant’s implementation for VPOS requests is based on signature calculation, then 4.1 could be chosen. If version 4.1 has been chosen, then the processor certificate should be used for the message validation.
Depending on the events a merchant needs to receive advice messages for, the respective value is filled in with the URL(s) that shall receive that message. Multiple URLs (up to 5) can be configured for each advice, separated with new line ‘\n’.
If one advice is left blank, then no message will be sent for that action.
It is also possible to configure retry options. If first sending fails (network error, not http 200), then after selected seconds, service will re-post the original advice message.

Description of message elements and fields and their usage

Field/request	Type	Description
Advice	element	A optional transaction advice message weebhook posted by service to merchant system urls. Advice has attribute type that can have following values Sale – advice of sale transaction has happened Authorisation – advice of pre authorization has happened Capture – advice of capture has happened Cancel – advice of cancel (void/reversal) has happened Refund – advice of refund has happened Recurring .- advice of recurring child has happened
Authentication	element	Authentication element of request Message
Mid	xsi:string (N1..8)	Merchant number/identification in VPOS
Fields of original payment
OrderId	element, xsi:string	Original payment order id
OrderAmount	element, xsi:decimal	Original payment order amount
Currency	element, xsi:string	Original payment currency
OrderTxId	element, xsi:string	Original payment tx id
OrderTxStatus	element, xsi:string	Original payment payment status
PaymentTotal	element, xsi:decimal	Original payment payment total (if no fees or adjustments it equals order amount, but depending casr may be different)
Fields of secondary transaction
TxId	element, xsi:string	The secondary advice transaction id (eg capture, cancel, refund, recurring child)
TxStatus	element, xsi:string	The secondary advice transaction status
TxCurrency	element, xsi:string	The secondary advice transaction currncy
TxSequence	element, xsi:integer	Secondary recurring child transaction sequence number
TxPaymentRef	element, xsi:string	Secondary transaction paymenr refrence if available
Description	element, xsi:string	If secondary transaction then secondary transaction status description, if primary transaction then primary transaction status description

Table of field requirements depending on messages:
R – required, O-optional, C-conditional

Field element/requests	Advice	Description
Authentication
Mid	R	Merchant id number
Responses/Notification/Advice
OderId	R	Order Id supplied by merchant originally
OrderAmount	R
PaymentTotal	R
Currency	R
OrderTxStatus	R
TxId	C	Present if secondary transaction advice
TxStatus	C	Present if secondary transaction advice
TxCurrency	C	Present if secondary transaction advice
TxStatus	C	Present if secondary transaction advice
TxTotal	C	Present if secondary transaction advice
TxSequence	C	Present if recurring child advice
TxPaymentref	O	Present if secondary transaction advice and payment ref is available
Description	O	Primary or if secondary advice transaction status description
Digest	R	for version 2.1
Signature	R	for version 4.1

Examples of advice messages (version 2.1)

Recurring

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><VPOS xmlns=”http://www.modirum.com/schemas/vposxmlapi41″ xmlns:ns2=”http://www.w3.org/2000/09/xmldsig#”><Message version=”2.1″ messageId=”ADV92639546395243″ timeStamp=”2023-05-15T07:00:13.475+03:00″><Advice type=”Recurring”><Authentication><Mid>00000011</Mid></Authentication><OrderId>1683921187970</OrderId><OrderAmount>1.25</OrderAmount><Currency>EUR</Currency><OrderTxId>92639546395033</OrderTxId><OrderTxStatus>CAPTURED</OrderTxStatus><PaymentTotal>1.25</PaymentTotal><TxId>92639546395243</TxId><TxStatus>CAPTURED</TxStatus><TxTotal>1.25</TxTotal><TxCurrency>EUR</TxCurrency><TxSequence>4</TxSequence><TxPaymentRef>106064</TxPaymentRef></Advice></Message><Digest>bhVT41Y9P5M0N1N1fYc6z/GzKoDE4b1F7It/VNERQ7U=</Digest></VPOS>

Sale

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><VPOS xmlns=”http://www.modirum.com/schemas/vposxmlapi41″ xmlns:ns2=”XML-Signature Syntax and Processing <Message> version=”2.1″ messageId=”ADV92639551130871″ timeStamp=”2023-09-11T09:22:39.593+03:00″><Advice type=”Sale”><Authentication><Mid>9000002377</Mid></Authentication><OrderId>245T1694413345</OrderId><OrderAmount>49.0</OrderAmount><Currency>EUR</Currency><OrderTxId>92639551130871</OrderTxId><OrderTxStatus>CAPTURED</OrderTxStatus><PaymentTotal>49.0</PaymentTotal><TxId>92639551130871</TxId><TxStatus>CAPTURED</TxStatus><TxTotal>49.0</TxTotal><TxCurrency>EUR</TxCurrency><TxPaymentRef>106484</TxPaymentRef></Advice></Message><Digest>ZoqBF+KPKzTllMYm11pLm7QQxE7d9mMc6HWQJib6H30=</Digest></VPOS>

Cancel

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><VPOS xmlns=”http://www.modirum.com/schemas/vposxmlapi41″ xmlns:ns2=”http://www.w3.org/2000/09/xmldsig#”><Message version=”2.1″ messageId=”ADV92639546395293″ timeStamp=”2023-05-15T11:56:39.961+03:00″><Advice type=”Cancel”><Authentication><Mid>00000011</Mid></Authentication><OrderId>1684140779809</OrderId><OrderAmount>1.25</OrderAmount><Currency>EUR</Currency><OrderTxId>92639546395283</OrderTxId><OrderTxStatus>VOID</OrderTxStatus><PaymentTotal>1.25</PaymentTotal><TxId>92639546395293</TxId><TxStatus>AUTHORIZED</TxStatus><TxTotal>1.25</TxTotal><TxCurrency>EUR</TxCurrency><TxPaymentRef>106140</TxPaymentRef></Advice></Message><Digest>VCDJH6bV5l6g0BncJnXzSuFqkt90p6y9NTjqWfPo+qo=</Digest></VPOS>

Capture

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><VPOS xmlns=”http://www.modirum.com/schemas/vposxmlapi41″ xmlns:ns2=”http://www.w3.org/2000/09/xmldsig#”><Message version=”2.1″ messageId=”ADV92639546395313″ timeStamp=”2023-05-15T11:57:32.621+03:00″><Advice type=”Capture”><Authentication><Mid>00000011</Mid></Authentication><OrderId>1684141004711</OrderId><OrderAmount>1.25</OrderAmount><Currency>EUR</Currency><OrderTxId>92639546395303</OrderTxId><OrderTxStatus>CAPTURED</OrderTxStatus><PaymentTotal>1.25</PaymentTotal><TxId>92639546395313</TxId><TxStatus>CAPTURED</TxStatus><TxTotal>1.25</TxTotal><TxCurrency>EUR</TxCurrency><TxPaymentRef>106143</TxPaymentRef></Advice></Message><Digest>AUjGoZ5iPNcaAdFt+65/cBr+iACetMYPnON3MkTUFAQ=</Digest></VPOS>

Refund

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><VPOS xmlns=”http://www.modirum.com/schemas/vposxmlapi41″ xmlns:ns2=”http://www.w3.org/2000/09/xmldsig#”><Message version=”2.1″ messageId=”ADV92639546395323″ timeStamp=”2023-05-15T12:19:27.925+03:00″><Advice type=”Refund”><Authentication><Mid>00000011</Mid></Authentication><OrderId>1683885240634</OrderId><OrderAmount>55.0</OrderAmount><Currency>EUR</Currency><OrderTxId>92639546393423</OrderTxId><OrderTxStatus>REFUNDED</OrderTxStatus><PaymentTotal>55.0</PaymentTotal><TxId>92639546395323</TxId><TxStatus>CAPTURED</TxStatus><TxTotal>55.0</TxTotal><TxCurrency>EUR</TxCurrency><TxPaymentRef>105087</TxPaymentRef></Advice></Message><Digest>r114HENsu6FMUbldS2HLwjB8U6gt4qaBP4Am7AetIHA=</Digest></VPOS>

Example of advice messages (version 4.1)

Payment

<OrderTxStatus>CAPTURED</OrderTxStatus>

<ds:Signature xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>

<ds:SignedInfo>

<ds:CanonicalizationMethod Algorithm=”http://www.w3.org/TR/2001/REC-xml-c14n-20010315″/>

<ds:SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig-more#rsa-sha256″/>

<ds:Reference URI=”#ADV9263957539012″>

<ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256″/>

<ds:DigestValue>7dsQK6oP4Nt8ID2hjx8Bndz6zvjH2jsceXAkrGgtK4k=</ds:DigestValue>

</ds:Reference>

</ds:SignedInfo>

<ds:SignatureValue>

DVUwOzyb………………………………………………………..2jHJq

</ds:SignatureValue>

<ds:KeyInfo>

<ds:X509Data>

<ds:X509Certificate>

MIIEbTCCAtWgAwIBAgIGAWq1Rs+nMA0GCSqGSIb3DQEBCwUAMG8xHzAdBgNVBAMTFkNhcmRsaW5r

…………………………….

bOu+/oza5EYKMpA1Mu3QWtb3hwiwogdlZnNxfpFhugqLNKmyWs/vHH/DGJAG1eKNwqTVb+MY

</ds:X509Certificate>

</ds:X509Data>

</ds:KeyInfo>

</ds:Signature>

</VPOS>

Refund

<OrderId>O221109112656</OrderId><

OrderAmount>0.12</OrderAmount>

<OrderTxStatus>REFUNDED</OrderTxStatus>

<TxStatus>CAPTURED</TxStatus>

</Advice>

</Message>