AuthReq

NAME: AuthReq - SET AuthReq message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct AuthReq_ {
    asn1set__MessageWrapper      messageWrapper;
    asn1set__AuthReqData         authReqData;
    asn1set__PI                  pi;
    cert_identity                merchantSignatureCID;
    cert_identity                gatewayKeyExchangeCID;

    /* only Merchant uses hodInput */
    asn1set__HODInput            hodInput;

    /* only Gateway uses pi_content */
    struct PI_                   pi_content;
} *AuthReq;

AuthReq safe_cast_AuthReq(msg)
    set_msg            msg;             /* IN */

DESCRIPTION

AuthReq contains the data from a SET AuthReq 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.

AuthReq message objects of type set_msg can be cast to type AuthReq using the safe_cast_AuthReq() routine.

Merchant software must fill in the appropriate hodInput fields. Merchant software should ignore pi_content.

Gateway software should ignore hodInput.

FIELDS

See documentation on PI for information on the struct PI_ field.

If the PInitReq/PInitRes pair was not exchanged, then before calling make_set_msg(), merchant software must insert the following state into the cache_ctx:

*      STATE_GATEWAY_KEYID
*      STATE_MERCHANT_SIGID

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
 *    authReqData.authTags.authRRTags.rrpid
 *    authReqData.authTags.authRRTags.currentDate
 *    authReqData.authTags.TransIDs
 *    authReqData.authReqPayload.subsequentAuthInd
 *    authReqData.checkDigests
 *    authReqData.mThumbs
 *    pi
 *    merchantSignatureCID
 *    gatewayKeyExchangeCID

If the PI is not an AuthToken, make_set_msg() additionally fills in the following fields:

 *    hodInput.splitRecurInd
 *    hodInput.odsalt

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:

 *    authReqData.authTags.authRRTags.merTermIDs.merchantID
 *    authReqData.authTags.authRRTags.currentDate
 *    authReqData.authReqPayload.authReqAmt
 *    authReqData.authReqPayload.captureNow

If the PI is not an AuthToken, merchant software must fill in the following fields:

 *    hodInput.od
 *    hodInput.purchAmt

Non-required fields can be left empty, at the discretion of the merchant application.

CACHING

Payment Gateway

      STATE_AUTHREQ_RRPID            put
      STATE_AUTHTOKENDATA            put
      STATE_BACKKEYDATA              put
      STATE_CARDEXPIRY               put
      STATE_GATEWAY_KEYID            put
      STATE_GATEWAY_SIGID            put
      STATE_INSTALLRECURDATA         put
      STATE_MERCHANTID               put
      STATE_MERCHANT_KEYID           put
      STATE_PAN                      put
      STATE_PURCHAMT                 put
      STATE_RRTAGS                   put
      STATE_SUBSEQUENTAUTHIND        put
      STATE_TRANSIDS                 put

Merchant

      STATE_AUTHREQDATA              put
      STATE_AUTHREQITEM              put
      STATE_AUTHREQ_RRPID            put
      STATE_DD_OIDATA                get
      STATE_GATEWAY_KEYID            get
      STATE_INSTALLRECURDATA         get
      STATE_MERCHANT_SIGID           get
      STATE_ODSALT                   get
      STATE_PI                       get
      STATE_PREQ_RRPID               get
      STATE_TRANSIDS                 get
      STATE_TRANSIDS                 put

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

SEE ALSO: set_msg, AuthRes, CapReq, 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, the application must 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.

    status = create_set_msg(&request, app_ctx, heap);
    assert(status == NO_ERROR);

    msg_type = asn1set__Message__authReq;
    status = make_set_msg(request, app_ctx, msg_cache, msg_type);
    assert(status == NO_ERROR);

    authReq = safe_cast_AuthReq(request);
    assert(authReq != 0);

    authReq->authReqData.authReqItem.authTags.authRRTags.merTermIDs.merchantID.u.visibleString = "MerchantID";
    authReq->authReqData.authReqItem.authTags.authRRTags.merTermIDs.merchantID._choice =
                                         asn1set__MerchantID__visibleString;

    authReq->authReqData.authReqItem.authTags.authRRTags.currentDate = time(0);

    authReq->authReqData.authReqItem.authReqPayload.authReqAmt.currency  = US_DOLLAR;
    authReq->authReqData.authReqItem.authReqPayload.authReqAmt.amount    = AUTHAMT;
    authReq->authReqData.authReqItem.authReqPayload.authReqAmt.amtExp10  = EXPONENT;

    authReq->authReqData.captureNow = 0; /* FALSE */

    /* this information isn't used for AuthTokens */
    authReq->hodInput.purchAmt.currency  = US_DOLLAR;
    authReq->hodInput.purchAmt.amount    = PURCHAMT;
    authReq->hodInput.purchAmt.amtExp10  = EXPONENT;
    authReq->hodInput.od.length  = strlen(ORDER_DESC);
    authReq->hodInput.od.value   = (UCHAR*)ORDER_DESC;

    /* ... */
    
    status = send_set_msg(request, app_ctx, msg_cache, outstream)
    assert(status == NO_ERROR);

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