Markdown

Authorize (CCAUTHORIZE)

Place a temporary hold on a cardholder's account to confirm funds are available, without capturing them.

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

An authorization is the first part of a two-stage process of "authorizing" and "capturing" funds. This two-stage process is commonly used by merchants who fulfill partial orders or physical goods that have not yet shipped. In order to capture the Authorization request, use the CCCAPTURE action.

POSThttps://api.inoviopay.com/payment/pmt_service.cfm
WAIT TIME REQUIREMENT

Please allow a wait time of 120 seconds for CCAUTHORIZE, CCAUTHCAP, and other requests. Even though the gateway usually processes requests in less than a second, downstream processors can take much longer to get a response from issuing banks.

EARLY TIMEOUT WARNING

If a merchant chooses to time out their request earlier than 120 seconds: - The gateway is not responsible for lost transactions, transaction records, or other failed functions. - The merchant may use CCSTATUS at a later time to find the final outcome of the request (provided an XTL_ORDER_ID was included in the original request). See Order Status. - Webhooks/postbacks may or may not trigger when the request is finalized at the gateway and should not be strictly relied upon.

Request Parameters

The table below includes all required authentication, payment, and optional fields permitted during an authorization.

Parameter Description
REQUEST_ACTION Required Must be set to CCAUTHORIZE.
REQ_USERNAME Required Service Request Username.
REQ_PASSWORD Required Service Request Password.
REQUEST_RESPONSE_FORMAT Optional Accepted values: "XML", "PIPES" and "JSON" (default: XML).
REQUEST_API_VERSION Required API Version (Must be 4.14).
SITE_ID Required Merchant's Website ID.
CUST_FNAME Optional Cardholder's First Name.
CUST_LNAME Optional Cardholder's Last Name.
CUST_EMAIL Optional Cardholder's Email Address.
LI_COUNT_1 Required Line Item Count (Max value is "99").
LI_PROD_ID_1 Required Line Item Product ID 1.
LI_VALUE_1 Required Line Item Transaction Amount 1.
XTL_ORDER_ID Optional Merchant's Order ID.
BILL_ADDR Optional Cardholder Billing Street Address (may be required by the bank for AVS).
BILL_ADDR_CITY Optional Cardholder's Billing City.
BILL_ADDR_STATE Optional Cardholder's Billing State (2-letter State or Territory Code).
BILL_ADDR_ZIP Optional Cardholder's Billing Postal/ZIP code.
BILL_ADDR_COUNTRY Optional Cardholder's Billing Country (2-letter Country Code ISO 3166-1 alpha-2).
PMT_NUMB Required Credit Card Number.
TOKEN_GUID Optional Token ID used in place of pmt_numb. See Tokenization.
PMT_KEY Required Credit Card CVV2 or CVC2 Code.
PMT_EXPIRY Required Credit Card Expiration Date (Format: MMYYYY, e.g. "122026").
CUST_LOGIN Optional Cardholder's Login or User Name.
CUST_PASSWORD Optional Cardholder's Password.
MERCH_ACCT_ID Optional Merchant Account ID. If null, the system will follow merchant's bank settings.
REQUEST_CURRENCY Required 3-letter Currency Code (e.g., USD).
PMT_DESCRIPTOR Optional Dynamic Descriptor. This parameters will replace the static statement descriptor that appears in the cardholder's bank statement. (Not supported by all Processors)
PMT_DESCRIPTOR_PHONE Optional Bank Dynamic Customer Support Phone Number. This parameters will replace the static statement descriptor that appears in the cardholder's bank statement. (Not supported by all Processors)
PMT_DESCRIPTOR_CITY Optional Bank Dynamic Customer Support City (Applicable to MasterCard only).
CUST_PHONE Optional Cardholder's Phone Number.
REQUEST_AFF_ID Optional External Affiliate ID.
REQUEST_AFF_ID_SUB Optional External Sub-affiliate ID.
UNIQUE_XTL_ORDER_ID Optional Enforces External Order ID uniqueness ("0" - disables, "1" - declines, "2" - returns Approval).
PMT_ID_XTL Optional External Payment Unique Identifier.
MBSHP_ID_XTL Optional External Membership ID.
TRANS_REBILL_TYPE Optional Rebill Type (NONE, TRIAL, INITIAL, REBILL).
REQUEST_INITIATOR Optional CIT (C) and MIT (M) Used to identify transaction origination.
REQUEST_INSTALLMENT Optional 0 (not used), 1 (used) Used to denote if the rebill is an installment.
PMT_NUMB_COF Optional 0 (not used), 1 (used) Used to denote use of payment number stored by Merchant.
REQUEST_REBILL Optional 1 (yes for rebill), 2 (Start Subscription), not used.
TRANS_TRIAL_REBILL_CUSTOMER_CONSENT Optional Customer Consent for rebill after trial period. Required for first REBILL following TRIAL.
TRANS_CUSTOMER_RECEIPT Optional Payment Receipt content sent to the customer.
CARD_ON_FILE_FLAG Optional Flags if COF or New PMT Card (0=COF, 1=New).

Handling the Response

While the gateway returns a comprehensive payload for data modeling, you should primarily monitor the following fields to determine the outcome of an authorization, especially in cases of partial or variable authorizations:

Field Name Description
TRANS_STATUS_NAME Check this to ensure the transaction was APPROVED.
TRANS_VALUE The exact amount the issuing bank authorized. If this is less than your requested amount, it was a partial authorization.
PO_ID The Purchase Order ID. You must pass this exact value into your subsequent CCCAPTURE request to settle the funds.
TRANS_ID The unique Transaction ID for the authorization.
PROC_AUTH_RESPONSE The authorization code generated by the processor.
AVS_RESPONSE / CVV_RESPONSE Indicates if the address and security codes matched, allowing you to apply internal risk modeling.
curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=CCAUTHORIZE&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&pmt_numb=4111111111111111&pmt_expiry=122026&pmt_key=123&request_currency=USD&li_value_1=84.50&cust_fname=John&cust_lname=Doe&bill_addr=123+Main+St&bill_addr_city=Los+Angeles&bill_addr_state=CA&bill_addr_zip=90001&bill_addr_country=US"