5.1 Authorization

The authorization request is used to confirm the availability of funds in the cardholder's account. This type of transaction places a temporary hold or a pending authorization on the cardholder's account and does not guarantee payment. For this type of transaction, merchants must send the Service Request, "CCAUTHORIZE", in the transaction request.

The Authorization Request is the first of two parts in the "authorization" and "capture" funds process. This two-step process is commonly used by merchants who need to perform partial order processing. To capture the Authorization Request, use the Service Request, "CCCAPTURE".

5.1.1 Authorization Parameters

The table below only includes parameters typically sent in a Simple Authorization Request. Note that merchants may send additional parameters listed in section 4 of this specification.

Field Name	Description	Data Type	Requirement
request_action	Service request action (Send "CCAUTHORIZE").	Service Request Types	Required
req_username	Service request username	Alphanumeric	Required
req_password	Service request password	Alphanumeric and special characters	Required
request_response_format	Service response format	Accepted values: "XML", "PIPES" and "JSON"	Optional (default: XML)
request_api_version	API version	Numeric	Required
site_id	Merchant website ID	Numeric	Required
cust_fname	Cardholder first name(s)	Alphanumeric and special characters	Optional
cust_lname	Cardholder last name(s)	Alphanumeric and special characters	Optional
cust_email	Cardholder email	Alphanumeric	Optional
li_count_1	Line item counter. Maximum value "99".	Numeric	Required
li_prod_id_1	Line item 1 product ID	Numeric	Required
li_value_1	Line item 1 transaction amount	Numeric	Required
xtl_order_id	Merchant order ID	Alphanumeric	Optional
bill_addr	Cardholder billing address street	Alphanumeric	Optional (address fields may be required by the bank)
bill_addr_city	Cardholder billing address city	Alphanumeric	Optional (address fields may be required by the bank)
bill_addr_state	Cardholder billing address state	2-letter state code	Optional (address fields may be required by the bank)
bill_addr_zip	Cardholder billing address zip code	Alphanumeric	Optional (address fields may be required by the bank)
bill_addr_country	Cardholder billing address country	ISO 3166-1 alpha-2 2-letter country code	Optional (address fields may be required by the bank)
pmt_numb	Credit card number	Numeric	Required
token_guid	Token ID	Alphanumeric	Token ID used instead of pmt_numb. See Tokenization.
pmt_key	Card CVV2 or CVC2 code	Numeric (4)	Required
pmt_expiry	Card expiration date	Numeric MMYYYY. Example: "122014"	Required
cust_login	Cardholder username	Alphanumeric and special characters	Optional
cust_password	Cardholder password (must contain one uppercase, one lowercase and one number) of at least 10 characters.	Alphanumeric	Optional
merch_acct_id	Merchant account ID	Numeric	Required
request_currency	3-letter currency code	Example: USD	Required
pmt_descriptor	Dynamic descriptor	Alphanumeric	Optional
pmt_descriptor_phone	Bank's dynamic customer support phone number	Numeric	Optional
cust_phone	Cardholder phone number	Numeric	Optional
request_aff_id	External affiliate ID	Alphanumeric	Optional
request_aff_id_sub	External sub-affiliate ID	Alphanumeric	Optional
unique_xtl_order_id	Forces uniqueness of order ID.	Possible values: "0" – disables the flag "1" – Decline request "2" – Returns approval response	Optional
pmt_id_xtl	External unique payment identifier	Alphanumeric (maximum length: 64)	Optional
mbshp_id_xtl	External membership ID	Alphanumeric	Optional (This will be required if TRANS_REBILL_TYPE is not NONE)
trans_rebill_type	Recurring charge type	One of the following values: NONE, TRIAL, INITIAL, REBILL	Required
card_on_file_flag	Flag to indicate if COF (card on file) or new card	Possible values are 0 or 1	Required

5.1.2 Authorization Request Example

POST /payment/pmt_service.cfm HTTP/1.0

User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)

Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, application/vnd.ms-powerpoint, application/vnd.ms-excel, application/msword, */*

Accept-Encoding: identity Accept-Language: en-us,en

Host: API.PLGW.com

Accept-Charset: iso-8859-1,*,utf-8

Content-Type: application/x-www-form-urlencoded Content-Length: 531

req_password=Test1234567&site_id=0&cust_fname=Daenarys&bill_addr_city=Los%20Angeles&bill_addr_state=CA&pmt_expiry=10%2F2020&xtl_cust_id=testcust11&pmt_key=123&request_response_format=XML&pmt_numb=4111111111111111&cust_lname=Targaryen&request_api_version=4.4&cust_email=useremail%40tests.com&li_value_1=1.25&req_username=merchant100%40example.com&li_prod_id_1=1001&request_currency=USD&xtl_order_id=testorder117&bill_addr_zip=90401&request_action=CCAUTHORIZE&merch_acct_id=100&bill_addr=1%20Main%20St&bill_addr_country=US&pmt_id_xtl=ABCD12345&mbship_id_xtl=888920&card_on-file_bandera=0&trans_rebill_type=rebill

5.1.3 Authorization Response Example

<RESPONSE>
    <REQUEST_ACTION>CCAUTHCAP</REQUEST_ACTION> 
    <TRANS_STATUS_NAME>APPROVED</TRANS_STATUS_NAME> 
    <TRANS_VALUE>1.25</TRANS_VALUE> 
    <TRANS_VALUE_SETTLED>1.25</TRANS_VALUE_SETTLED> 
    <CURR_CODE_ALPHA_SETTLED>USD</CURR_CODE_ALPHA_SETTLED> 
    <TRANS_EXCH_RATE/>
    <TRANS_ID>989898</TRANS_ID>
    <CUST_ID>212121</CUST_ID>
    <XTL_CUST_ID/>
    <PO_ID>17171717</PO_ID>
    <XTL_ORDER_ID/>
    <BATCH_ID>3114</BATCH_ID>
    <PROC_NAME>Test Processor</PROC_NAME> 
    <MERCH_ACCT_ID>100</MERCH_ACCT_ID> 
    <CARD_BRAND_NAME>Visa</CARD_BRAND_NAME> 
    <CARD_TYPE>VISA CREDIT CARD</CARD_TYPE>
    <PMT_AAU_UPDATE_DT>16-NOV-2018</PMT_AAU_UPDATE_DT> 
    <CARD_PREPAID>1</CARD_PREPAID>
    <CARD_BANK>BANK OF EUROPE</CARD_BANK> 
    <CARD_BALANCE/>
    <PMT_L4>1111</PMT_L4> 
    <PMT_ID>101011</PMT_ID> 
    <PMT_ID_XTL/>
    <PROC_UDF01/>
    <PROC_UDF02/>
    <PROC_AUTH_RESPONSE>72682</PROC_AUTH_RESPONSE> 
    <PROC_RETRIEVAL_NUM>74C8C7C8-5652-48BB-A68BGRACE46A2D1</PROC_RETRIEVAL_NUM> 
    <PROC_REFERENCE_NUM/>
    <PROC_REDIRECT_URL/>
    <AVS_RESPONSE>M</AVS_RESPONSE>
    <CVV_RESPONSE>M</CVV_RESPONSE>
    <REQUEST_API_VERSION>4.4</REQUEST_API_VERSION>
    <PO_LI_ID_1>8509920</PO_LI_ID_1>
    <PO_LI_COUNT_1>1</PO_LI_COUNT_1>
    <PO_LI_AMOUNT_1>1.25</PO_LI_AMOUNT_1> 
    <PO_LI_PROD_ID_1>1001</PO_LI_PROD_ID_1>
    <MBSHP_ID_1/>
</RESPONSE>

5.1.4 Failed Authorization Attempt Response Example

<RESPONSE>
    <REQUEST_ACTION>CCAUTHORIZE</REQUEST_ACTION> 
    <TRANS_STATUS_NAME>DECLINED</TRANS_STATUS_NAME> 
    <TRANS_VALUE>5.01</TRANS_VALUE>
    <TRANS_ID>20005</TRANS_ID>
    <CUST_ID>2</CUST_ID>
    <XTL_CUST_ID>c777777777</XTL_CUST_ID>
    <MERCH_ACCT_ID>100</MERCH_ACCT_ID>
    <CARD_BRAND_NAME>Mastercard</CARD_BRAND_NAME>
    <PMT_L4>5100</PMT_L4>
    <PMT_ID/>
    <PMT_ID_XTL/>
    <API_RESPONSE>0</API_RESPONSE>
    <API_ADVICE> </API_ADVICE> 
    <SERVICE_RESPONSE>640</SERVICE_RESPONSE> 
    <SERVICE_ADVICE>Retry</SERVICE_ADVICE> 
    <PROCESSOR_RESPONSE>501</PROCESSOR_RESPONSE> 
    <PROCESSOR_ADVICE>Retry</PROCESSOR_ADVICE> 
    <INDUSTRY_RESPONSE>0</INDUSTRY_RESPONSE> 
    <INDUSTRY_ADVICE> </INDUSTRY_ADVICE> 
    <REF_FIELD/>
    <PROC_NAME>Test Processor</PROC_NAME> 
    <AVS_RESPONSE/>
    <CVV_RESPONSE/> 
    <REQUEST_API_VERSION>4.4</REQUEST_API_VERSION> 
</RESPONSE>

5.1.5 Declined Service Response Example

<RESPONSE>
    <REQUEST_ACTION>CCAUTHORIZE</REQUEST_ACTION> 
    <TRANS_STATUS_NAME/>
    <CUST_ID/>
    <XTL_CUST_ID>c777777777</XTL_CUST_ID> 
    <MERCH_ACCT_ID>100</MERCH_ACCT_ID> 
    <CARD_BRAND_NAME/>
    <PMT_L4/>
    <PMT_ID/>
    <PMT_ID_XTL/>
    <API_RESPONSE>113</API_RESPONSE> 
    <API_ADVICE>Invalid Data</API_ADVICE> 
    <SERVICE_RESPONSE>0</SERVICE_RESPONSE> 
    <SERVICE_ADVICE>Declined</SERVICE_ADVICE> 
    <PROCESSOR_RESPONSE>0</PROCESSOR_RESPONSE> 
    <PROCESSOR_ADVICE> </PROCESSOR_ADVICE> 
    <INDUSTRY_RESPONSE>0</INDUSTRY_RESPONSE> 
    <INDUSTRY_ADVICE> </INDUSTRY_ADVICE> 
    <REF_FIELD>cust_password</REF_FIELD> 
    <PROC_NAME/>
    <AVS_RESPONSE/>
    <CVV_RESPONSE/> 
    <REQUEST_API_VERSION>4.4</REQUEST_API_VERSION> 
</RESPONSE>

The example above was declined by the API due to invalid data in the CUST_PASSWORD field

(see the API_ADVICE and REF_FIELD parameters). Requests declined by the service will also have the "Declined" message in the SERVICE_ADVICE field.