Sale Reference ID

The Sale Reference ID is a data that can be passed on and transferred from an incoming request. In order to display such data in the message response from Arkos, this one needs to be added to the Acquirer Proprietary Data directory.

To do so, the following block of code has been implemented and added to the Arkos Pay Application:

public static PaymentParams createFromRetail(NexoRequest req) {
        PaymentParams params = new PaymentParams();

        if (req instanceof PaymentRequest) {
            PaymentRequest paymentReq = (PaymentRequest) req;

            String saleReferenceID = paymentReq.SaleReferenceID;
            params.paramTree = TlvTree.FromRaw(paymentReq.preparedPaymentData);
            TlvTree acquirerProprietaryData = params.paramTree.AddChild(Params.ACQUIRER_PROPRIETARY_DATA);
            acquirerProprietaryData.SetAscii(Params.SALE_REFERENCE_ID,saleReferenceID);

            ...
            
        } else if (req instanceof ReversalRequest) {
            ...
            }
        } else {
            ...
        }
        ...
    }

The Retail Module (ASL) parses the payment request and sets paymentReq.SaleReferenceID with the saleReferenceID from the XML. This field can be then accessed through the merchant app side and is set into acquirer proprietary data.

The previously given script will provide you with details of the implementation made for the addition of the Sale Reference ID attribute in the ACQUIRER_PROPRIETARY_DATA directory. This one will then appear in the Message Request Response from Nexo Retail (i.e: Accepted Authorization Request response).

Example of Payment request with Sale Reference ID:

<?xml version="1.0"?>
<SaleToPOIRequest>
    <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="2" SaleID="ArkosSales" POIID="87654321"/>
    <PaymentRequest>
        <SaleData SaleReferenceID="ArkosSale42">
            <SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00"/>
        </SaleData>
        <PaymentTransaction>
            <AmountsReq Currency="EUR" RequestedAmount="5.00"/>
        </PaymentTransaction>
        <PaymentData/>
    </PaymentRequest>
</SaleToPOIRequest>

Example of response with the resulting Sale Reference ID:

<AccptrAuthstnReq>
	<Hdr>
		...
		<InitgPty>
			<Id>MONEY2020VEGA$</Id>
		</InitgPty>
		<RcptPty>
			<Id>Amadis</Id>
		</RcptPty>
	</Hdr>
	<AuthstnReq>
		...
		<Tx>
			...
			<SaleRefId>ArkosSale42</SaleRefId>
			...
		</Tx>
	</AuthstnReq>
	<SctyTrlr>
		...
	</SctyTrlr>
</AccptrAuthstnReq>

An example of the ACQUIRER_PROPRIETARY_DATA can be found in the following snip of the directory:

, 0xFFBF2F: 
        [ 0xDFCF01: 41726b6f7353616c653432
        , 0xFFDF02: 
                [ 0xFF01: 
                        [ 0xC1: 4864722f496e6974675074792f4964
                        , 0xC2: 4d4f4e4559323032305645474124
                        ]
                ]
        , 0xDFBF01: 303030303030303030323336
        , 0xFFBF05: 
                [ 0xFFFF6A: 
                        [ 0xDF01: 01
                        , 0xDFBF03: 44656661756c74206265686176696f72
                        , 0xDFBF04: 4e6f2074657374206361736520747269676765726564
                        ]
                ]
        ]