{"title":"Start gift card transactions","category":"default","creationDate":1776961627,"content":"

Prototype the callback<\/h2>\n

Prototype the\u00a0create_new_tender_CB<\/code>\u00a0and pass\u00a0this as a\u00a0parameter of the function pointer to the\u00a0create_special_tender<\/code>\u00a0call.\u00a0<\/p>\n

Code example<\/h3>\n

The callback function declaration is:<\/p>\n

void create_new_tender_CB(create_tender_response *response, void *echo_struct){\n    app_context_t *sPOS = (app_context_t *)echo_struct;\nif (response->tender_reference) {\n        safe_strdup(&sPOS->tender_reference, response->tender_reference);\n        sPOS->pending_callback = 0; \/\/mark ok......\n    } else {\n        sPOS->pending_callback = -1;\n}<\/code><\/pre>\n
Allocate request structure<\/h2>\n
Use\u00a0create_special_tender_request<\/code>\u00a0to allocate memory for an\u00a0special_tender_request<\/code>\u00a0structure.\u00a0Populate the request by performing\u00a0string duplication and filling heap allocated strings. If you want the data for later use, retain it, or it will be released automatically.<\/p>\n
special_tender_request *request = create_special_tender_request();\n    if (request) {\n        request->reference = strdup(\"Simple transaction\");\n        request->merchant_account = strdup(sPOS->merchant_account);\n        request->terminal_id = strdup(sPOS->terminal_id);<\/code><\/pre>\n
Entry modes<\/h2>\n
The gift card can be presented in three ways:\u00a0<\/p>\n
    \n
  1. Swipe: the gift card is read using a magnetic stripe reader.<\/li>\n
  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.<\/li>\n
  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.<\/li>\n<\/ol>\n
    You can specify entry modes by passing special tender options. See\u00a0Gift Cards<\/a>.\u00a0<\/p>\n
    Add and remove special options<\/h2>\n
    Special options are dictionary key value pairs. This information is passed directly to the PED, which interprets it.<\/p>\n
    Use\u00a0special_tender_add_option<\/code>\u00a0to set\u00a0 special options, passing the request along with key value pairs. Use\u00a0special_tender_rm_option<\/code>\u00a0to remove the set options.<\/p>\n
    special_tender_add_option(request, \"cardNumber\", \"60362821657200117610\");\n        special_tender_add_option(request, \"cardNumber.expiryMonth\", \"12\");\n        special_tender_add_option(request, \"cardNumber.expiryYear\", \"2049\");<\/code><\/pre>\n
    Populate the create_special_tender_request<\/h2>\n
    Populate the request using string duplication.<\/p>\n
    special_tender_request *request = create_special_tender_request();\n    if (request) {\n        request->reference = strdup(\"Simple transaction\");\n        request->merchant_account = strdup(sPOS->merchant_account);\n        request->terminal_id = strdup(sPOS->terminal_id);\n        request->amount_currency = strdup(sPOS->currency);\n        request->amount_value = sPOS->amount;\n        request->transaction_type = strdup(\"balanceInquiry\");\n        request->payment_method_type = strdup(\"goldsmithscard\");\n        special_tender_add_option(request, \"cardNumber\", \"60362821657200117610\");\n        special_tender_add_option(request, \"cardNumber.expiryMonth\", \"12\");\n        special_tender_add_option(request, \"cardNumber.expiryYear\", \"2049\");\n        \/* additional data is accessible like below\n            request->additional_data_obj\n        *\/\n        result = create_special_tender(request, create_new_tender_CB, sPOS);\n    }\n<\/code><\/pre>\n
    Call the create_special_tender Function<\/h2>\n
    Call the\u00a0create_special_tender<\/code>\u00a0function to\u00a0Initiate the sale transaction, which triggers any relevant callbacks,\u00a0and pass in the request that was previously allocated.<\/p>\n
    The POS waits for the final state and the\u00a0\u00a0status_tender_final<\/code>\u00a0\u00a0callback 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.<\/p>\n
    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.<\/p>\n
    result = create_special_tender(request, create_new_tender_CB, sPOS);<\/code><\/pre>\n
    Parameters<\/h2>\n\n\n\n\n\n\n\n
    Value<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    request<\/code><\/td>\nPointer to the special_tender_request<\/code> struct, this struct contains all the input parameters for this call.<\/td>\n<\/tr>\n
    create_new_tender_CB<\/code><\/td>\nPointer to the callback function in the POS that will be called with the results of the create special tender call<\/td>\n<\/tr>\n
    echo_struct<\/code><\/td>\nPointer to a POS defined struct. Returned in the callback. It can be used to share a POS data struct between the call to the library and the callback from the library.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Code example<\/h3>\n
    The declaration of the call to start a transaction is as follows:<\/p>\n
    result = create_special_tender(request, create_new_tender_CB, sPOS);<\/code><\/pre>\n
    Handle the callback<\/h2>\n
    Handle the\u00a0create_new_tender_CB<\/code>\u00a0to check if the transaction was accepted by the terminal\u00a0by checking if tender_reference was populated by the library.\u00a0<\/p>\n
     if (response->tender_reference) {\n  safe_strdup(&sPOS->tender_reference, response->tender_reference);\n  sPOS->pending_callback = 0; \/\/mark ok......\n } else {\n  sPOS->pending_callback = -1;\n }<\/code><\/pre>\n
    Check the result by getting information from the\u00a0create_tender_response<\/code>.<\/p>\n
    The POS needs to wait for the\u00a0create_new_tender_CB<\/code>\u00a0to happen, before it can continue with other\u00a0functions.\u00a0 After the\u00a0create_new_tender_CB<\/code>\u00a0is returned, the system returns a number of other callbacks. Finally, the system returns the\u00a0final\u00a0callback that contains the final transaction result. Another transaction can only be started when the final transaction result is received.<\/p>\n
    Parameters<\/h3>\n\n\n\n\n\n\n
    Data element<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    create_tender_response<\/code><\/td>\nA unique reference for the transaction that is generated by the PED device. This reference is used for subsequent actions on the transaction. For a list of parameters, see create_tender_response<\/a>.<\/td>\n<\/tr>\n
    echo_struct<\/code><\/td>\nPointer to a user-defined struct. Returned in the callback. It can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n
    The create_new_tender_CB<\/code> is a callback to the creation of a tender, but does not represent the status or result of the transaction. The result is returned in tender_finished_CB<\/code>.<\/p>\n<\/div><\/div>","url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations\/c-library-integration\/extras-c-library\/start-gift-card-transactions-c-library","articleFields":{"id":"31491822","type":"page","_expandable":{"operations":""},"status":"current"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations\/c-library-integration\/extras-c-library\/start-gift-card-transactions-c-library","title":"Start gift card transactions","content":"Prototype the callback\nPrototype the\u00a0create_new_tender_CB\u00a0and pass\u00a0this as a\u00a0parameter of the function pointer to the\u00a0create_special_tender\u00a0call.\u00a0\nCode example\nThe callback function declaration is:\nvoid create_new_tender_CB(create_tender_response *response, void *echo_struct){\n    app_context_t *sPOS = (app_context_t *)echo_struct;\nif (response->tender_reference) {\n        safe_strdup(&sPOS->tender_reference, response->tender_reference);\n        sPOS->pending_callback = 0; \/\/mark ok......\n    } else {\n        sPOS->pending_callback = -1;\n}\nAllocate request structure\nUse\u00a0create_special_tender_request\u00a0to allocate memory for an\u00a0special_tender_request\u00a0structure.\u00a0Populate the request by performing\u00a0string duplication and filling heap allocated strings. If you want the data for later use, retain it, or it will be released automatically.\nspecial_tender_request *request = create_special_tender_request();\n    if (request) {\n        request->reference = strdup(\"Simple transaction\");\n        request->merchant_account = strdup(sPOS->merchant_account);\n        request->terminal_id = strdup(sPOS->terminal_id);\nEntry modes\nThe gift card can be presented in three ways:\u00a0\n\nSwipe: the gift card is read using a magnetic stripe reader.\nMKE 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.\nMKE 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.\n\nYou can specify entry modes by passing special tender options. See\u00a0Gift Cards.\u00a0\nAdd and remove special options\nSpecial options are dictionary key value pairs. This information is passed directly to the PED, which interprets it.\nUse\u00a0special_tender_add_option\u00a0to set\u00a0 special options, passing the request along with key value pairs. Use\u00a0special_tender_rm_option\u00a0to remove the set options.\nspecial_tender_add_option(request, \"cardNumber\", \"60362821657200117610\");\n        special_tender_add_option(request, \"cardNumber.expiryMonth\", \"12\");\n        special_tender_add_option(request, \"cardNumber.expiryYear\", \"2049\");\nPopulate the create_special_tender_request\nPopulate the request using string duplication.\nspecial_tender_request *request = create_special_tender_request();\n    if (request) {\n        request->reference = strdup(\"Simple transaction\");\n        request->merchant_account = strdup(sPOS->merchant_account);\n        request->terminal_id = strdup(sPOS->terminal_id);\n        request->amount_currency = strdup(sPOS->currency);\n        request->amount_value = sPOS->amount;\n        request->transaction_type = strdup(\"balanceInquiry\");\n        request->payment_method_type = strdup(\"goldsmithscard\");\n        special_tender_add_option(request, \"cardNumber\", \"60362821657200117610\");\n        special_tender_add_option(request, \"cardNumber.expiryMonth\", \"12\");\n        special_tender_add_option(request, \"cardNumber.expiryYear\", \"2049\");\n        \/* additional data is accessible like below\n            request->additional_data_obj\n        *\/\n        result = create_special_tender(request, create_new_tender_CB, sPOS);\n    }\n\nCall the create_special_tender Function\nCall the\u00a0create_special_tender\u00a0function to\u00a0Initiate the sale transaction, which triggers any relevant callbacks,\u00a0and pass in the request that was previously allocated.\nThe POS waits for the final state and the\u00a0\u00a0status_tender_final\u00a0\u00a0callback 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.\nThe 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.\nresult = create_special_tender(request, create_new_tender_CB, sPOS);\nParameters\n\n\n\nValue\nDescription\n\n\n\n\nrequest\nPointer to the special_tender_request struct, this struct contains all the input parameters for this call.\n\n\ncreate_new_tender_CB\nPointer to the callback function in the POS that will be called with the results of the create special tender call\n\n\necho_struct\nPointer to a POS defined struct. Returned in the callback. It can be used to share a POS data struct between the call to the library and the callback from the library.\n\n\n\nCode example\nThe declaration of the call to start a transaction is as follows:\nresult = create_special_tender(request, create_new_tender_CB, sPOS);\nHandle the callback\nHandle the\u00a0create_new_tender_CB\u00a0to check if the transaction was accepted by the terminal\u00a0by checking if tender_reference was populated by the library.\u00a0\n if (response->tender_reference) {\n  safe_strdup(&sPOS->tender_reference, response->tender_reference);\n  sPOS->pending_callback = 0; \/\/mark ok......\n } else {\n  sPOS->pending_callback = -1;\n }\nCheck the result by getting information from the\u00a0create_tender_response.\nThe POS needs to wait for the\u00a0create_new_tender_CB\u00a0to happen, before it can continue with other\u00a0functions.\u00a0 After the\u00a0create_new_tender_CB\u00a0is returned, the system returns a number of other callbacks. Finally, the system returns the\u00a0final\u00a0callback that contains the final transaction result. Another transaction can only be started when the final transaction result is received.\nParameters\n\n\n\nData element\nDescription\n\n\n\n\ncreate_tender_response\nA unique reference for the transaction that is generated by the PED device. This reference is used for subsequent actions on the transaction. For a list of parameters, see create_tender_response.\n\n\necho_struct\nPointer to a user-defined struct. Returned in the callback. It can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.\n\n\n\n\nThe create_new_tender_CB is a callback to the creation of a tender, but does not represent the status or result of the transaction. The result is returned in tender_finished_CB.\n","type":"page","locale":"pt","boost":14,"hierarchy":{"lvl0":"Home","lvl1":"Terminais","lvl2":"Deprecation of classic libraries","lvl3":"Library integrations","lvl4":"C library integration","lvl5":"Extras","lvl6":"Start gift card transactions"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/point-of-sale","lvl2":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation","lvl3":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations","lvl4":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations\/c-library-integration","lvl5":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations\/c-library-integration\/extras-c-library","lvl6":"\/pt\/point-of-sale\/classic-library-deprecation\/classic-library-integrations\/c-library-integration\/extras-c-library\/start-gift-card-transactions-c-library"},"levels":7,"category":"In-person payments","category_color":"green","tags":["Start","transactions"]}}