CredReq

NAME: CredReq - SET CredReq message data structures and routines

SYNOPSIS

#include <set_msg.h>

/*
 *    CredReq is defined using CapRevOrCredReq
 */
#define    CredReq_          CapRevOrCredReq_
#define    CredReq           CapRevOrCredReq

/*
 *
 *    CapRevOrCredReq is used by CapRevReq, CredReq, and CredRevReq
 *
 */
typedef struct CapRevOrCredReq_ {
    asn1set__MessageWrapper          messageWrapper;
    asn1set__CapRevOrCredReqData     capRevOrCredReqData;
    asn1set__PANToken                panToken;

    cert_identity                    merchantSignatureCID;
    cert_identity                    gatewayKeyExchangeCID;

    /* only the Gateway uses */
    struct CapTokenSeq_             *capTokenSeq;

#define                              CapRevOrCredReq__panToken       0
    UCHAR                            _present[1];
} *CapRevOrCredReq;

CredReq safe_cast_CredReq(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: CredReq contains the data from a SET CredReq 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.
CredReq message objects of type set_msg can be cast to type CredReq using the safe_cast_CredReq() routine.

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
 *    capRevOrCredReqData.capRevOrCredRRTags.rrpid
 *    capRevOrCredReqData.mthumbs
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.transIDs
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.authRRPID
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.capPayload.capReqAmt
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.capPayload.capDate
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.capPayload.authReqItem
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.capPayload.authResPayload
 *    capTokenSeq
 *    panToken (optional)

If a PANToken was received during authorization and this CredReq message contains only a single CapItem, SETREF will insert this panToken into CredReq and will set CapRevOrCredReq__panToken present.

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

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

 *    capRevOrCredReqData.capRevOrCredRRTags.merTermIDs.merchantID
 *    capRevOrCredReqData.capRevOrCredRRTags.currentDate
 *    capRevOrCredReqData.capRevOrCredReqItemSeq->capRevOrCredReqItem.capRevOrCredReqAmt
 *    merchantSignatureCID 
 *    gatewayKeyExchangeCID

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

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().

CapRevOrCredReq__panToken: Merchant software indicates to SETREF that the data contained in the panToken field should be included in the CredReq message by setting CapRevOrCredReq__panToken to present.
SETREF indicates to gateway software that the panToken field is present by setting CapRevOrCredReq__panToken to present.

CACHING

Payment Gateway

      STATE_CAPAMT                   put
      STATE_CAPREVREQ_RRPID;         put
      STATE_CREDREQ_RRPID            put
      STATE_CREDREVREQ_RRPID         put
      STATE_GATEWAY_SIGID            put
      STATE_MERCHANT_KEYID           put
      STATE_RRTAGS                   put

Merchant

      STATE_AUTHREQITEM              get
      STATE_AUTHREQ_RRPID            get
      STATE_AUTHRESPAYLOAD           get
      STATE_CAPAMT                   get
      STATE_CAPDATE                  get
      STATE_CAPREQ_RRPID             get
      STATE_CAPREVREQ_RRPID          put
      STATE_CAPTOKEN                 get
      STATE_CREDREQ_RRPID            put
      STATE_CREDREVREQ_RRPID         put
      STATE_PANTOKEN                 get
      STATE_TRANSIDS                 get

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

SEE ALSO: set_msg, AuthReq, AuthRes, CapRes, PInitReq, PInitRes, PReq, 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 still 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.

    credReq = safe_cast_CredReq(request);
    assert(credReq != 0);
   
    credReq->messageWrapper.messageHeader.swIdent._choice = asn1set__SWIdent__visibleString;
    credReq->messageWrapper.messageHeader.swIdent.u.visibleString = "MerchantCode v1.0";

    /* ... */

    credReq->capRevOrCredReqData.capRevOrCredRRTags.
        merTermIDs.merchantID.u.visibleString = MERCHANT_ID_STRING;
    credReq->capRevOrCredReqData.capRevOrCredRRTags.
        merTermIDs.merchantID._choice = asn1set__MerchantID__visibleString;

    /* ... */

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