AuthRes

NAME: AuthRes - SET AuthRes message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct AuthRes_ {
    asn1set__MessageWrapper      messageWrapper;
    asn1set__AuthResData         authResData;
    asn1set__PANToken            panToken;

    cert_identity                gatewaySignatureCID;
    cert_identity                merchantKeyExchangeCID;

    /* only Merchant uses */
    asn1set__AuthResBaggage      authResBaggage;

    /* only Gateway uses */
    struct AcqCardMsg_           acqCardMsg;
    struct AuthToken_            authToken;
    struct CapToken_             capToken;

#define                          AuthRes__panToken              0
#define                          AuthRes__acqCardMsg            1
#define                          AuthRes__authToken             2
#define                          AuthRes__capToken              3
    UCHAR                        _present[1];
} *AuthRes;

AuthRes safe_cast_AuthRes(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: AuthRes contains the data from a SET AuthRes 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.

FIELDS

See documentation on AcqCardMsg for information on the struct AcqCardMsg_ field, AuthToken for information on the struct AuthToken_ field, and CapToken for information on the struct CapToken_ field.

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
 *    authResData.authTags
 *    authResData.brandCRLIdentifier (optional)
 *    authResData.peThumb (optional)
 *    authToken (optional)
 *    gatewaySignatureCID
 *    merchantKeyExchangeCID
 *    panToken (optional)

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

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

 *    authResData.authResPayload.authHeader.authAmt
 *    authResData.authResPayload.authHeader.authCode

Non-required fields may be left empty at the discretion of the gateway 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().

AuthRes__acqCardMsg: The gateway software indicates to SETREF that the data contained in the acqCardCodeMsg field should be included in the AuthRes message by setting AuthRes__acqCardMsg to present.
Merchant software does not use this optional element.

AuthRes__authToken: If the subsequent authorization indicator (subsequentAuthInd) was set in AuthReq and the recurring authorizations have not expired, then SETREF will fill in the authTokenData field, and set AuthRes__authToken to present, in anticipation of sending an AuthToken to the merchant. Gateway software can prevent sending the AuthToken by setting AuthRes__authTokenData to absent before calling send_set_msg().
Merchant software does not use this optional element.

AuthRes__capToken: The gateway software indicates to SETREF that a CapToken, which includes the data contained in the capTokenData field, should be included with the AuthRes message by setting AuthRes__capToken to present.
Merchant software does not use this optional element.

AuthRes__panToken: The gateway software indicates to SETREF that the data contained in the panToken field should be included in the AuthRes message by setting AuthRes__panToken to present. In this case, the data contained in the panToken field will be available to the merchant.
SETREF indicates to merchant software that the panToken field is present by setting AuthRes__panToken to present.

CACHING

Payment Gateway

      STATE_AUTHREQ_RRPID            get
      STATE_BACKKEYDATA              get
      STATE_CARDEXPIRY               get
      STATE_GATEWAY_KEYID            get
      STATE_GATEWAY_SIGID            get
      STATE_MERCHANT_KEYID           get
      STATE_PAN                      get
      STATE_RRTAGS                   get
      STATE_SUBSEQUENTAUTHIND        get
      STATE_TRANSIDS                 get

Merchant

      STATE_ACQCARDMSG               put
      STATE_AUTHREQ_RRPID            get
      STATE_AUTHRESPAYLOAD           put
      STATE_AUTHRETNUM               put
      STATE_CAPAMT                   put
      STATE_CAPCODE                  put
      STATE_CAPDATE                  put
      STATE_CAPTOKEN                 put
      STATE_PANTOKEN                 put
      STATE_PI                       put
      STATE_TRANSIDS                 put

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

SEE ALSO: set_msg, AuthReq, 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(&response, app_ctx, heap);
    assert(status == NO_ERROR);

    msg_type = asn1set__Message__authRes;
    status = make_set_msg(response, app_ctx, msg_cache, msg_type);
    assert(status == NO_ERROR);

    authRes = safe_cast_AuthRes(response);
    assert(authRes != 0);
   
    authRes->messageWrapper.messageHeader.swIdent._choice = asn1set__SWIdent__visibleString;
    authRes->messageWrapper.messageHeader.swIdent.u.visibleString = "AcquirerServ v0.3b";

    /* ... */

    /* 840 is US dollars */
    authRes->authResData.authResPayload.authHeader.currConv.currConvRate = 1.0;
    authRes->authResData.authResPayload.authHeader.currConv.cardCurr = 840;
    /* currConv is optional */         
    SET_PRESENT(authRes->authResData.authResPayload.authHeader,
                asn1set__AuthHeader__currConv);
                
    /* ... */

    status = send_set_msg(reponse, 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.