Payment Account Reference and Hosted data

Use this guide to request and distinguish the Payment Account Reference (PAR) and an Hosted Data identifier (token) in a nexo authorisation flow.

PAR and Hosted Data serve different purposes:

Important: Do not use the PAR as an IPG Hosted Data identifier. When both values are returned, store them separately and use each value only for its intended purpose.

Prerequisites

Before using this flow:

• IPG Hosted Data must be enabled for the store.
• The transaction must be eligible for Hosted Data creation.
• PAR availability depends on the card scheme and processing route. Requesting PAR does not guarantee that a value will be returned.
• Use the nexo message version enabled for your integration. The examples below use caaa.001.001.06 and caaa.002.001.06.

Request Hosted Data and PAR

Hosted Data creation and PAR return are requested independently.

Request Hosted Data creation

Add the following value as a Tx/AddtlTxData entry in the AcceptorAuthorisationRequest:

<AddtlTxData>/request/token</AddtlTxData>

This requests Hosted Data creation while the authorisation transaction is processed.

The separate /request/tokenOnly option is intended for specifically enabled token-only integrations. Do not use it as a substitute for /request/token unless it is part of your agreed integration.

Request PAR in the response

Add a merchant-reference component to Envt/POI/Cmpnt:

<Cmpnt>
  <Tp>MRPR</Tp>
  <Id>
    <Id>paymentAccountReferenceInResponse</Id>
  </Id>
</Cmpnt>

The value paymentAccountReferenceInResponse is case-sensitive and must be sent exactly as shown.

Combined request fragment

The following fragment requests both Hosted Data creation and PAR return:

<AuthstnReq>
  <Envt>
    ...
    <POI>
      ...
      <Cmpnt>
        <Tp>MRPR</Tp>
        <Id>
          <Id>paymentAccountReferenceInResponse</Id>
        </Id>
      </Cmpnt>
    </POI>
    <Card>
      ...
    </Card>
  </Envt>
  <Cntxt>
    ...
  </Cntxt>
  <Tx>
    ...
    <AddtlTxData>/request/token</AddtlTxData>
  </Tx>
</AuthstnReq>

Continue to include all other fields required for the selected authorisation transaction.

Read PAR and Hosted Data from the response

When PAR was requested and both values are available, the AcceptorAuthorisationResponse returns them in separate fields:

Example response fragment:

<AuthstnRspn>
  <Envt>
    ...
    <Card>
      <PlainCardData>
        <PAN>{store-id}.{hosted-data-id}</PAN>
        <XpryDt>2028-12</XpryDt>
      </PlainCardData>
      <PmtAcctRef>{payment-account-reference}</PmtAcctRef>
    </Card>
    <PmtTkn>
      <TknChrtc>tokenProvider=ipgHosteddata</TknChrtc>
    </PmtTkn>
  </Envt>
  ...
</AuthstnRspn>

Treat the Hosted Data identifier as an opaque value. Store and resend it exactly as returned.

PmtTkn/TknChrtc can occur more than once. If token-provider metadata is required, select the entry beginning with tokenProvider= instead of relying on element position.

Response scenarios

Important: The meaning of Card/PmtAcctRef depends on whether the request included the paymentAccountReferenceInResponse component:

• When the component was included, Card/PmtAcctRef contains PAR.
• When the component was not included, Card/PmtAcctRef can contain the Hosted Data identifier.

Use Hosted Data in a later transaction

For a later token-based transaction, take the Hosted Data identifier returned by the original response and send it in the new request at:

Document/AccptrAuthstnReq/AuthstnReq/Envt/Card/PmtAcctRef

Example:

<Card>
  <PmtAcctRef>{store-id}.{hosted-data-id}</PmtAcctRef>
</Card>

When both PAR and Hosted Data were returned, use the value from the original response's Card/PlainCardData/PAN. Do not use the PAR from Card/PmtAcctRef as the token for the later transaction.

Continue to include all other mandatory fields for the new transaction.

Integration rules

• Request Hosted Data with the exact Tx/AddtlTxData value /request/token.
• Request PAR with Cmpnt/Tp=MRPR and Cmpnt/Id/Id=paymentAccountReferenceInResponse.
• Do not assume that Card/PmtAcctRef always contains PAR.
• When PAR was requested, read Hosted Data from Card/PlainCardData/PAN.
• When PAR was not requested, Hosted Data can be returned in Card/PmtAcctRef.
• Treat both identifiers as opaque, case-sensitive values.
• Do not derive one identifier from the other.
• Handle optional fields by path and meaning rather than by element position.
• Do not expect PmtTkn/TknRqstr in the authorisation response.