# Authorize (CCAUTHORIZE)

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

Source: https://developer.inoviopay.com/api/authorize.html  
Markdown: https://developer.inoviopay.com/api/authorize.md

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.

**POST** `https://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](https://developer.inoviopay.com/api/status.md#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](https://developer.inoviopay.com/api/tokenization.md#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**

```bash
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"
```

**PHP**

```php
use Inovio\Gateway\{Credentials, InovioClient};
use Inovio\Gateway\Model\{Address, Customer, LineItem, Money, PaymentMethods};
use Inovio\Gateway\Request\TransactionRequest;

$client = new InovioClient(new Credentials('api_user', 'P@ssw0rd!', '12345'), 'SANDBOX');

$req = new TransactionRequest(
    PaymentMethods::card('4111111111111111', '122026', '123'),
    [new LineItem('SKU-492', 1, Money::of('84.50', 'USD'))]
);
$req->customer = new Customer();
$req->customer->firstName = 'John';
$req->customer->lastName = 'Doe';
$req->billingAddress = new Address();
$req->billingAddress->line1 = '123 Main St';
$req->billingAddress->city = 'Los Angeles';
$req->billingAddress->state = 'CA';
$req->billingAddress->zip = '90001';
$req->billingAddress->country = 'US';

$auth = $client->authorize($req);

echo $auth->status, ' order=', $auth->orderRef?->poId() ?? '-', "\n";
// Keep $auth->orderRef — capture() and reverse() both consume it.
```

**Node**

```ts
import { InovioClient, Money, PaymentMethods } from '@inovio/gateway-sdk';

const client = new InovioClient(
  { reqUsername: 'api_user', reqPassword: 'P@ssw0rd!', siteId: '12345' },
  { environment: 'SANDBOX' }
);

const auth = await client.authorize({
  paymentMethod: PaymentMethods.card('4111111111111111', '122026', '123'),
  lineItems: [{ productId: 'SKU-492', count: 1, value: Money.of('84.50', 'USD') }],
  customer: { firstName: 'John', lastName: 'Doe' },
  billingAddress: { line1: '123 Main St', city: 'Los Angeles', state: 'CA', zip: '90001', country: 'US' },
});

console.log(auth.status, 'order=', auth.orderRef?.poId ?? '-');
// Keep auth.orderRef — capture() and reverse() both consume it.
```

**Python**

```python
from inovio_gateway import Credentials, InovioClient, Money, PaymentMethods
from inovio_gateway.model import Address, Customer, LineItem
from inovio_gateway.request import TransactionRequest

client = InovioClient(Credentials("api_user", "P@ssw0rd!", "12345"), environment="SANDBOX")

req = TransactionRequest(
    payment_method=PaymentMethods.card("4111111111111111", "122026", "123"),
    line_items=[LineItem("SKU-492", 1, Money.of("84.50", "USD"))],
)
req.customer = Customer(first_name="John", last_name="Doe")
req.billing_address = Address(
    line1="123 Main St", city="Los Angeles", state="CA", zip="90001", country="US"
)

auth = client.authorize(req)

print(auth.status.value, "order=", auth.order_ref.po_id if auth.order_ref else "-")
# Keep auth.order_ref — capture() and reverse() both consume it.
```

**Java**

```java
TransactionRequest req = new TransactionRequest(
    PaymentMethods.card("4111111111111111", "122026", "123"),
    new LineItem("SKU-492", 1, Money.of("84.50", "USD")));

Customer customer = new Customer();
customer.firstName = "John";
customer.lastName = "Doe";
req.customer = customer;

Address billing = new Address();
billing.line1 = "123 Main St";
billing.city = "Los Angeles";
billing.state = "CA";
billing.zip = "90001";
billing.country = "US";
req.billingAddress = billing;

TransactionResult auth = client.authorize(req);

System.out.println(auth.status() + " order=" + (auth.orderRef() == null ? "-" : auth.orderRef().poId()));
// Keep auth.orderRef() — capture() and reverse() both consume it.
```

**Response**

```json
{
  "REQUEST_ACTION": "CCAUTHORIZE",
  "REQ_ID": "83920174",
  "TRANS_STATUS_NAME": "APPROVED",
  "TRANS_VALUE": 84.50,
  "CURR_CODE_ALPHA": "USD",
  "TRANS_VALUE_SETTLED": 84.50,
  "CURR_CODE_ALPHA_SETTLED": "USD",
  "TRANS_EXCH_RATE": "",
  "TRANS_ID": 9482710345,
  "CUST_ID": 1029384,
  "XTL_CUST_ID": "xTr92mPqL1",
  "PO_ID": 55829102,
  "XTL_ORDER_ID": "",
  "BATCH_ID": 883921,
  "PROC_NAME": "Inovio Primary",
  "MERCH_ACCT_ID": 449201,
  "CARD_BRAND_NAME": "Mastercard",
  "CARD_TYPE": "MASTERCARD WORLD",
  "CARD_CLASS": "Consumer Credit",
  "CARD_PREPAID": 0,
  "CARD_BANK": "CAPITAL ONE",
  "CARD_COUNTRY": "USA",
  "CARD_DETAIL": "Credit",
  "CARD_BALANCE": "",
  "PMT_L4": "5521",
  "PMT_ID": 8839201,
  "PMT_ID_XTL": "",
  "PMT_AAU_UPDATE_DT": "",
  "PMT_AAU_UPDATE_DESC": "",
  "PROC_UDF01": "",
  "ANI_RESP_DECISION": "",
  "PROC_UDF02": "",
  "PROC_AUTH_RESPONSE": "APV992",
  "PROC_RETRIEVAL_NUM": "9A8B7C6D-5E4F-3A2B-1C0D-E9F8A7B6C5D4",
  "PROC_REFERENCE_NUM": "REF88291039",
  "PROC_REDIRECT_URL": "",
  "AVS_RESPONSE": "Y",
  "CVV_RESPONSE": "M",
  "CARD_BRAND_TRANSID": "",
  "REQUEST_API_VERSION": "4.14",
  "P3DS_VENDOR": "",
  "P3DS_RESPONSE": "",
  "PO_LI_ID_1": "9928172",
  "PO_LI_COUNT_1": 1,
  "PO_LI_AMOUNT_1": "84.50",
  "PO_LI_PROD_ID_1": "SKU-492",
  "MBSHP_ID_1": "",
  "TRANS_NTOKEN_USED": 0
}
```