Sale Context (Using Nexo ACQ)

Based on your protocol, acquirer, or your transaction context, some of the following values could be mandatory as well as required.

This document applies to the Nexo version of the sale Context.

If you need specific values in your sale context structures, an example will be provided below.

public static void createSalesContext(PaymentParams params){
        TlvTree saleData = params.paramTree.AddChild(ArkosTags.RetailSaleData);
        TlvTree saleContext = saleData.AddChild(ArkosTags.SaleContext);

        saleContext.AddAscii(SaleContextID.SaleContextSaleIdentification,"Identification");
        saleContext.AddAscii(SaleContextID.SaleContextSaleReferenceNumber,"Reference Number");
        saleContext.AddAscii(SaleContextID.SaleContextSaleReconciliationIdentification,"Reconciliation Identification");
        saleContext.AddAscii(SaleContextID.SaleContextCashierIdentification,"Cashier Identification");
        saleContext.AddAscii(SaleContextID.SaleContextShiftNumber,"01");
        saleContext.AddAscii(SaleContextID.SaleContextPurchaseOrderNumber,"Purchase Order Number");
        saleContext.AddAscii(SaleContextID.SaleContextInvoiceNumber,"Invoice Number");
        saleContext.AddAscii(SaleContextID.SaleContextDeliveryNoteNumber,"Delivery Note Number");

        TlvTree sponsoredMerchant = saleContext.AddChild(SaleContextID.SaleContextSponsoredMerchant);
        sponsoredMerchant.AddAscii(SaleContextSponsoredMerchantID.SaleContextCommonName,"Common");
        sponsoredMerchant.AddAscii(SaleContextSponsoredMerchantID.SaleContextAddress,"Address");
        sponsoredMerchant.AddAscii(SaleContextSponsoredMerchantID.SaleContextCountryCode,"123");
        sponsoredMerchant.AddAscii(SaleContextSponsoredMerchantID.SaleContextMerchantCategoryCode,"1234");
        sponsoredMerchant.AddAscii(SaleContextSponsoredMerchantID.SaleContextRegisteredIdentifier,"Identifier");

        TlvTree sponsoredMerchant2 = saleContext.AddChild(SaleContextID.SaleContextSponsoredMerchant);
        sponsoredMerchant2.AddAscii(SaleContextSponsoredMerchantID.SaleContextCommonName,"Common1");
        sponsoredMerchant2.AddAscii(SaleContextSponsoredMerchantID.SaleContextAddress,"Address1");
        sponsoredMerchant2.AddAscii(SaleContextSponsoredMerchantID.SaleContextCountryCode,"123");
        sponsoredMerchant2.AddAscii(SaleContextSponsoredMerchantID.SaleContextMerchantCategoryCode,"1234");
        sponsoredMerchant2.AddAscii(SaleContextSponsoredMerchantID.SaleContextRegisteredIdentifier,"Identifier1");

        saleContext.AddBin(SaleContextID.SaleContextSplitPayment, new byte[] {0x01});
        saleContext.AddBin(SaleContextID.SaleContextRemainingAmount,new byte[] { 0x00, 0x00, 0x00, 0x00, 0x10, 0x00 });
        saleContext.AddAscii(SaleContextID.SaleContextAdditionalSaleData,"Data");

    }

NOTE: In the provided example, two sponsored merchants have been created to demonstrate the ability to add multiple of them as they are dynamic arrays.

How to use this with Cancellation, Update-pre auth, and Payment Completion?

    public static PaymentParams createPaymentCompletion(String transactionReference, int amount) {
        PaymentParams params = new PaymentParams();
        setTerminalInfo(params);

        //service
        params.paramTree.AddEnum(ArkosTags.SelectedService, PaymentServiceID.PaymentCompletion);
        createOriginalTransaction(params,transactionReference,PaymentServiceID.Preauth);
        createSalesContext(params);
        
        //Amount
        byte[] bcdAmount = IntToBCD(amount);
        if (bcdAmount == null) {
            return null;
        }
        params.paramTree.AddBin(TransactionAmount, bcdAmount);
        params.paramTree.AddBin(AmountAuthorised, bcdAmount);
        params.paramTree.AddBin(TransactionAmountBeforeAdjustment, bcdAmount);

        return params;
    }

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:caaa.001.001.06">
  <AccptrAuthstnReq>
    <Hdr>
      <MsgFctn>AUTQ</MsgFctn>
      <PrtcolVrsn>6.0</PrtcolVrsn>
      <XchgId>57</XchgId>
      <CreDtTm>2022-02-23T09:09:16.000+00:00</CreDtTm>
      <InitgPty>
        <Id>Amadis</Id>
      </InitgPty>
      <RcptPty>
        <Id>Amadis</Id>
      </RcptPty>
    </Hdr>
    <AuthstnReq>
      <Envt>
        <Acqrr>
          <Id>
            <Id>10009287351</Id>
          </Id>
          <ParamsVrsn>2022-02-22 18:25:09</ParamsVrsn>
        </Acqrr>
        <Mrchnt>
          <Id>
            <Id>00000NEXOMER001</Id>
          </Id>
          <CmonNm>AMADIS 1111 Saint-Urbain Montréal</CmonNm>
        </Mrchnt>
        <POI>
          <Id>
            <Id>ASA00002</Id>
          </Id>
          <Cpblties>
            <CardRdngCpblties>PHYS</CardRdngCpblties>
            <CardRdngCpblties>MGST</CardRdngCpblties>
            <CardRdngCpblties>CICC</CardRdngCpblties>
            <CardRdngCpblties>ECTL</CardRdngCpblties>
            <CrdhldrVrfctnCpblties>FCPN</CrdhldrVrfctnCpblties>
            <CrdhldrVrfctnCpblties>MNSG</CrdhldrVrfctnCpblties>
            <CrdhldrVrfctnCpblties>FEPN</CrdhldrVrfctnCpblties>
            <ApprvlCdLngth>6</ApprvlCdLngth>
            <OnLineCpblties>SMON</OnLineCpblties>
            <MsgCpblties>
              <Dstn>CRCP</Dstn>
              <Dstn>MDSP</Dstn>
              <Dstn>MRCP</Dstn>
              <AvlblLang>en</AvlblLang>
              <AvlblLang>fr</AvlblLang>
              <AvlblLang>it</AvlblLang>
            </MsgCpblties>
          </Cpblties>
          <Cmpnt>
            <Tp>TERM</Tp>
            <Id>
              <PrvdrId>Google</PrvdrId>
              <Id>sdk_gphone_x86_arm</Id>
              <SrlNb>ArkosPay DEMOSN00</SrlNb>
            </Id>
            <Sts />
          </Cmpnt>
          <Cmpnt>
            <Tp>APLI</Tp>
            <Id>
              <PrvdrId>AMADIS</PrvdrId>
              <Id>ARKOS</Id>
            </Id>
            <Sts>
              <VrsnNb>3.0.8-dev-stub</VrsnNb>
            </Sts>
          </Cmpnt>
        </POI>
        <Card>
          <CardPdctPrfl>90</CardPdctPrfl>
          <CardBrnd>STANDARD</CardBrnd>
          <IntrnlCard>false</IntrnlCard>
        </Card>
        <Crdhldr>
          <Lang>fr</Lang>
        </Crdhldr>
      </Envt>
      <Cntxt>
        <PmtCntxt>
          <CardPres>false</CardPres>
          <CrdhldrPres>false</CrdhldrPres>
          <AttndncCntxt>ATTD</AttndncCntxt>
          <CardDataNtryMd>DFLE</CardDataNtryMd>
        </PmtCntxt>
        <SaleCntxt>
          <SaleId>Identification</SaleId>
          <SaleRcncltnId>Reconciliation Identification</SaleRcncltnId>
          <CshrId>Cashier Identification</CshrId>
          <ShftNb>01</ShftNb>
          <PurchsOrdrNb>Purchase Order Number</PurchsOrdrNb>
          <InvcNb>Purchase Order Number</InvcNb>
          <DlvryNoteNb>Delivery Note Number</DlvryNoteNb>
          <SpnsrdMrchnt>
            <CmonNm>Common</CmonNm>
            <Adr>Address</Adr>
            <CtryCd>123</CtryCd>
            <MrchntCtgyCd>1234</MrchntCtgyCd>
            <RegdIdr>Identifier</RegdIdr>
          </SpnsrdMrchnt>
          <SpnsrdMrchnt>
            <CmonNm>Common1</CmonNm>
            <Adr>Address1</Adr>
            <CtryCd>123</CtryCd>
            <MrchntCtgyCd>1234</MrchntCtgyCd>
            <RegdIdr>Identifier1</RegdIdr>
          </SpnsrdMrchnt>
          <SpltPmt>false</SpltPmt>
          <RmngAmt>10.00</RmngAmt>
          <AddtlSaleData>Data</AddtlSaleData>
        </SaleCntxt>
      </Cntxt>
      <Tx>
        <TxCaptr>false</TxCaptr>
        <TxTp>RESA</TxTp>
        <SvcAttr>PRES</SvcAttr>
        <MrchntCtgyCd>5555</MrchntCtgyCd>
        <TxId>
          <TxDtTm>2022-02-23T09:09:16.000+00:00</TxDtTm>
          <TxRef>00000025</TxRef>
        </TxId>
        <OrgnlTx>
          <SaleRefId>saleReferenceIdentification</SaleRefId>
          <TxId>
            <TxDtTm>2022-02-23T09:09:16.000-05:00</TxDtTm>
            <TxRef>0000000033</TxRef>
          </TxId>
          <POIId>
            <Id>Terminal1</Id>
            <Tp>ACCP</Tp>
            <Issr>ACCP</Issr>
            <ShrtNm>Term</ShrtNm>
          </POIId>
          <InitrTxId>InitiatorTransactionIdentification</InitrTxId>
          <RcptTxId>RecipientTransactionIdentification</RcptTxId>
          <TxTp>RESA</TxTp>
          <SvcAttr>IRES</SvcAttr>
          <CardDataNtryMd>MGST</CardDataNtryMd>
          <TxRslt>
            <AuthstnNtty>
              <Id>Identification</Id>
              <Tp>ACCP</Tp>
              <Issr>ACCP</Issr>
              <Ctry>Cou</Ctry>
              <ShrtNm>ShortName</ShrtNm>
            </AuthstnNtty>
            <RspnToAuthstn>
              <Rspn>APPR</Rspn>
              <RspnRsn>Reason</RspnRsn>
              <AddtlRspnInf>AdditionalInformation</AddtlRspnInf>
            </RspnToAuthstn>
            <AuthstnCd>000001</AuthstnCd>
          </TxRslt>
        </OrgnlTx>
        <RcncltnId>11</RcncltnId>
        <TxDtls>
          <Ccy>EUR</Ccy>
          <TtlAmt>5.00</TtlAmt>
          <AmtQlfr>ACTL</AmtQlfr>
          <OnLineRsn>TRMF</OnLineRsn>
        </TxDtls>
      </Tx>
    </AuthstnReq>
  </AccptrAuthstnReq>
</Document>