Payment Account Reference and Hosted data

Your account must be enabled for this feature.

Use this guide to request and distinguish the Payment Account Reference (PAR) and a Hosted Data identifier (token) in a nexo authorisation flow. PAR availability depends on the card scheme and processing route. Requesting PAR does not guarantee that a value will be returned.

PAR and Hosted Data serve different purposes:

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

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:

Hosted Data identifier format

The token format depends on the token provider. Identify the provider from the PmtTkn/TknChrtc entry that begins with tokenProvider=. Do not rely on the element position because TknChrtc can occur more than once.

For IPG Hosted Data, IPG persists the values separately: STORE_ID contains the store ID and HOSTED_DATA_ID contains the Hosted Data ID. The dot-separated value is the nexo transport representation of this pair. When IPG receives {store-id}.{hosted-data-id} in a later nexo request, it separates the value and uses the two parts to find the Hosted Data record.

The dot-separated representation is not a requirement for an Endpoint Remote token.

Important: Treat every Hosted Data identifier as opaque and case-sensitive. Do not derive, construct, or convert a token from another provider.

IPG Hosted Data response example

For tokenProvider=ipgHosteddata, the response token includes the store-ID prefix:

<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>

Endpoint Remote response example

For tokenProvider=Endpoint_Remote, the response token is the Endpoint Remote provider token. IPG does not add a {store-id}. prefix:

<AuthstnRspn>
  <Envt>
    ...
    <Card>
      <PlainCardData>
        <PAN>{remote-provider-token}</PAN>
        <XpryDt>2028-12</XpryDt>
      </PlainCardData>
      <PmtAcctRef>{payment-account-reference}</PmtAcctRef>
    </Card>
    <PmtTkn>
      <TknChrtc>tokenProvider=Endpoint_Remote</TknChrtc>
    </PmtTkn>
  </Envt>
  ...
</AuthstnRspn>

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

For IPG Hosted Data, send the complete dot-separated nexo value. Although IPG stores STORE_ID and HOSTED_DATA_ID in separate columns, it separates the submitted nexo value before the lookup. Do not send only {hosted-data-id} if the original nexo response contained {store-id}.{hosted-data-id}.

For Endpoint Remote, send the provider token exactly as returned. Do not add an IPG store-ID prefix.

For example:

<!-- IPG Hosted Data -->
<Card>
  <PmtAcctRef>{store-id}.{hosted-data-id}</PmtAcctRef>
</Card>

<!-- Endpoint Remote -->
<Card>
  <PmtAcctRef>{remote-provider-token}</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.
• Use tokenProvider= metadata to determine the returned Hosted Data token format.
• Use {store-id}.{hosted-data-id} only when the provider is IPG Hosted Data (ipgHosteddata).
• Do not prepend a store ID to an Endpoint Remote token.
• Treat PAR and Hosted Data identifiers as separate, opaque, case-sensitive values.
• Do not derive one identifier from another.
• Handle optional fields by path and meaning rather than by element position.
• Do not expect PmtTkn/TknRqstr in the authorisation response.