Start gift card transactions

Prototype the callback

Prototype the create_new_tender_CB and pass this as a parameter of the function pointer to the create_special_tender call. 

Code example

The callback function declaration is:

void create_new_tender_CB(create_tender_response *response, void *echo_struct){
    app_context_t *sPOS = (app_context_t *)echo_struct;
if (response->tender_reference) {
        safe_strdup(&sPOS->tender_reference, response->tender_reference);
        sPOS->pending_callback = 0; //mark ok......
    } else {
        sPOS->pending_callback = -1;
}

Allocate request structure

Use create_special_tender_request to allocate memory for an special_tender_request structure. Populate the request by performing string duplication and filling heap allocated strings. If you want the data for later use, retain it, or it will be released automatically.

special_tender_request *request = create_special_tender_request();
    if (request) {
        request->reference = strdup("Simple transaction");
        request->merchant_account = strdup(sPOS->merchant_account);
        request->terminal_id = strdup(sPOS->terminal_id);

Entry modes

The gift card can be presented in three ways: 

1. Swipe: the gift card is read using a magnetic stripe reader.
2. MKE on terminal: the card number is manually entered on the payment terminal. The tender should specify that it expects keyed entry on the terminal, and a card mask should be provided.
3. MKE on POS app: scan a barcode on the back of the card from the POS app. In this scenario, the card number, card mask, and expiry should be provided in special options.

You can specify entry modes by passing special tender options. See Gift Cards. 

Add and remove special options

Special options are dictionary key value pairs. This information is passed directly to the PED, which interprets it.

Use special_tender_add_option to set  special options, passing the request along with key value pairs. Use special_tender_rm_option to remove the set options.

special_tender_add_option(request, "cardNumber", "60362821657200117610");
        special_tender_add_option(request, "cardNumber.expiryMonth", "12");
        special_tender_add_option(request, "cardNumber.expiryYear", "2049");

Populate the create_special_tender_request

Populate the request using string duplication.

special_tender_request *request = create_special_tender_request();
    if (request) {
        request->reference = strdup("Simple transaction");
        request->merchant_account = strdup(sPOS->merchant_account);
        request->terminal_id = strdup(sPOS->terminal_id);
        request->amount_currency = strdup(sPOS->currency);
        request->amount_value = sPOS->amount;
        request->transaction_type = strdup("balanceInquiry");
        request->payment_method_type = strdup("goldsmithscard");
        special_tender_add_option(request, "cardNumber", "60362821657200117610");
        special_tender_add_option(request, "cardNumber.expiryMonth", "12");
        special_tender_add_option(request, "cardNumber.expiryYear", "2049");
        /* additional data is accessible like below
            request->additional_data_obj
        */
        result = create_special_tender(request, create_new_tender_CB, sPOS);
    }

Call the create_special_tender Function

Call the create_special_tender function to Initiate the sale transaction, which triggers any relevant callbacks, and pass in the request that was previously allocated.

The POS waits for the final state and the  status_tender_final  callback to report the final result of the transaction, even if a cancel request has been issued. The reason for this is that the transaction might already be in a state in which a cancel is not possible.

The sale transaction includes the merchant account information, as this is used to register PEDs for multiple merchant accounts, and transactions can be performed on more than one of these merchant accounts.

result = create_special_tender(request, create_new_tender_CB, sPOS);

Parameters

Code example

The declaration of the call to start a transaction is as follows:

result = create_special_tender(request, create_new_tender_CB, sPOS);

Handle the callback

Handle the create_new_tender_CB to check if the transaction was accepted by the terminal by checking if tender_reference was populated by the library. 

 if (response->tender_reference) {
  safe_strdup(&sPOS->tender_reference, response->tender_reference);
  sPOS->pending_callback = 0; //mark ok......
 } else {
  sPOS->pending_callback = -1;
 }

Check the result by getting information from the create_tender_response.

The POS needs to wait for the create_new_tender_CB to happen, before it can continue with other functions.  After the create_new_tender_CB is returned, the system returns a number of other callbacks. Finally, the system returns the final callback that contains the final transaction result. Another transaction can only be started when the final transaction result is received.

Parameters