PReq

NAME: PReq - SET PReq message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct PReq_ {
    asn1set__MessageWrapper      messageWrapper;
    asn1set__OIData              oiData;
    cert_identity                cardholderSignatureCID;
    cert_identity                gatewayKeyExchangeCID;

    /* only cardholder uses */
    asn1set__PIData              piData;

    /* both the cardholder and merchant must set */
    asn__octet_string            order_description;

    /* only the merchant must set */
    asn1set__CurrencyAmount      purchAmt;
    asn1set__InstallRecurData    installRecurData;

#define                          PReq__installRecurData     0
    UCHAR                        _present[1];
} *PReq;

PReq safe_cast_PReq(msg)
    set_msg            msg;             /* IN */

DESCRIPTION

PReq contains the data from a SET PReq message in native C form. See the asn_types.h and asn1set.h header files for the declarations of the various types. See the SET specification for a description of individual fields.

PReq message objects of type set_msg can be cast to type PReq using the safe_cast_PReq() routine.

Merchant software should ignore piData.

FIELDS

A call to make_set_msg() results in the protocol layer filling in the following fields:

 *    messageWrapper.messageHeader.version
 *    messageWrapper.messageHeader.date
 *    messageWrapper.messageHeader.messageIDs
 *    messageWrapper.messageHeader.rrPID
 *    messageWrapper.messageHeader.swIdent
 *    messageWrapper.message._choice
 *    oiData.transIDs
 *    oiData.rrpid
 *    oiData.chall_C
 *    oiData.odSalt
 *    oiData.chall_M (optional)
 *    piData.piHead.swIdent
 *    piData.piHead.transIDs
 *    piData.panData.exNonce

If the PInit message pair was previously employed for this transaction, then the call to make_set_msg() results in the protocol layer also filling in the following fields. Otherwise, cardholder software must fill in these fields:

 *    piData.piHead.merchantID
 *    gatewayKeyExchangeCID

It is unwise for applications to change the contents of the fields filled in by the protocol layer.

After calling make_set_msg(), cardholder software must fill in the following required fields:

 *    oiData.bin
 *    oiData.brandID
 *    cardholderSignatureCID
 *    piData.piHead.inputs.purchAmt
 *    piData.panData.pan
 *    piData.panData.cardExpiry
 *    piData.panData.panSecret
 *    order_description

A call to send_set_msg() results in the protocol layer filling in the following fields:

 *    oiData.hod

Non-required fields may be left empty at the discretion of the cardholder application, subject to any business constraints placed on the application.

After calling receive_set_msg() and before calling verify_set_msg(), merchant software must fill in the following required field:

 *    order_description
 *    purchAmt
 *    installRecurData (optional)

OPTIONAL FIELDS

The _present element is used for specifying the presence or absence of optional elements. The macros SET_PRESENT(), IS_PRESENT(), SET_ABSENT(), and IS_ABSENT() are used to specify or query the status of optional elements. See documentation on ASN.1/DER runtime types for additional information.

When sending a message, the presence or absence must be set (using SET_PRESENT() or SET_ABSENT()) prior to calling send_set_msg(). It is usually unnecessary to invoke the SET_ABSENT() macro because absent is the default setting for blank messages.

When receiving a message, presence or absence can be determined (using the IS_PRESENT() or IS_ABSENT() macro) after calling decode_set_msg().

PReq__installRecurData: Merchant software indicates to SETREF that the contents of the installRecurData field are to be used by setting PReq__installRecurData to present.

CACHING

Cardholder

      STATE_BACKKEYDATA              put
      STATE_CHALL_C                  get
      STATE_CHALL_M                  get
      STATE_MERCHANTID               get
      STATE_PETHUMB                  get
      STATE_PREQ_RRPID               put
      STATE_TRANSIDS                 get
      STATE_TRANSIDS                 put

Merchant

      STATE_BRANDID                  put
      STATE_CHALL_C                  put
      STATE_CHALL_M                  get
      STATE_DD_OIDATA                put
      STATE_INSTALLRECURDATA         put
      STATE_ODSALT                   put
      STATE_PI                       put
      STATE_PREQ_RRPID               put
      STATE_TRANSIDS                 put

RETURN VALUES: On success, safe_cast_PReq() returns a pointer to a PReq data structure. Objects of type set_msg that were not created with message type asn1set__Message__pReq will cause safe_cast_PReq() to fail. On failure, safe_cast_PReq() returns a 0 pointer.

SEE ALSO: set_msg, AuthReq, AuthRes, CapReq, CapRes, PInitReq, PInitRes, PRes

NOTES: There is a difference between non-required and optional. Non-required fields may be omitted according to the SET protocol. Optional fields may be omitted according to ASN.1 encoding rules. In some messages, a field may be optional according to ASN.1, but required by the SET protocol. In these cases, it is incumbent on the application to fill in these fields.
Optional fields that are filled in require an application of the SET_PRESENT() macro. See documentation on ASN.1/DER runtime types for additional information.

EXAMPLE

A more complete, explicated example is provided in the Implementor's Guide.

    pReq = safe_cast_PReq(request);
    assert(pReq != 0);
   
    pReq->messageWrapper.messageHeader.swIdent._choice = asn1set__SWIdent__visibleString;
    pReq->messageWrapper.messageHeader.swIdent.u.visibleString = "WebTerm v7.2.3alpha";

    /* ... */

    pReq->oiData.brandID._choice = asn1set__BrandID__visibleString;
    pReq->oiData.brandID.u.visibleString = "Brand Name:Product Type";
    SET_PRESENT(pReq->oiData, asn1set__OIData__brandID);

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.