PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Processing an Authorization

Overview

An authorization transaction authorizes (holds) the payment amount on the card but does not transfer it yet. It then goes on to check whether the customer's account has sufficient funds for the transaction. A CAPTURE transaction must be made to collect this amount. See the section Capturing an Authorization.

As it can be captured more than once, this kind of transaction sets the total amount that the customer may or may not need to be charged with eventually, securing the sufficient funds ahead.

The workflow for this kind of transaction goes as follows:

  1. Customer/Merchant Initiation: The customer or merchant initiates the authorization request via the PayConex™ V4 API through their Payment Processor.

  2. Payment Processor Role: The Payment Processor forwards the request to the appropriate card network (e.g., Visa, Mastercard).

  3. Card Issuer Authorization: The card issuer evaluates the request based on:

    • Available credit or funds in the customer's account.

    • Fraud detection and security checks.

    • Transaction details (e.g., amount, merchant, location).

  4. Response Flow: The issuer either approves or declines the request and sends the response back through the Payment Processor to the customer/merchant.

🚧

Note

While an authorization is commonly used as a CIT transaction, there are scenarios where the merchant needs to authorize the bill payment and run captures against it as an MIT.

Authorization and Capture transactions are components of the CIT environment as they are not necessarily regarded as recurring MIT payments.

📘

Did you know?

In the case of CNP transactions where the Checkout Component form is required to be completed to receive the token, this type of transaction can be suitable if a significant delay is required between the tokenization of the payment data and the actual payment(transaction processing). Upon authorization, the transaction can be later captured. This is due to the fact that the token will expire within a few minutes if not used.

Non-Zero Amount Authorization

A Non-Zero amount authorization is a transaction that holds the payment amount on the card but does not transfer it yet, as stated above.

📘

Note

Many card networks allow for the capture amount to exceed the original authorization, often by a certain percentage (commonly 10-20%). This is referred to as a tolerance limit and is commonly used in industries like hospitality and car rentals where the final amount can be uncertain. For example, a restaurant might authorize $50 but capture $60 to include a tip.

🚧

Not Refundable

Since the authorization doesn't transfer the funds and only authorizes that the amount is available on the card, an authorization via V4 API is made essentially irreversible or non-refundable.

{
  "message": "Transaction type AUTHORIZATION is not refundable",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "traceId": "c9239fea-6467-4bfa-a011-778de0f23aec"
}

Request

POST /api/v4/accounts/{accountId}/payments/auth

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:auth

Even though an authorization transaction can be authorized for 10 dollars, and even if we capture just 5 dollars - the customer will be charged 5 dollars when that transaction settles.

The body parameters for this transaction are almost identical to sale transaction. For the specific parameters, see API Reference.

Running this request also adds the authorization action entry to the trace.history of the transaction metadata. This is useful for reporting and debugging purposes given the following:

  • Tracks the initial kind of transaction that is "authorization".

  • Tracks how many times the transaction was captured.

For example:

{
  ...
  "trace": {
    "history": [
      {
        "action": "authorization",
        "requestId": "c8251379-dbf3-43e1-b0c8-ab3b66a3f939",
        "correlationId": "27e3033c-d108-4517-8233-514c56873944",
        "timestamp": "2024-07-12T07:56:47-05:00"
      },
      {
        "action": "capture",
        "requestId": "4faa6cf8-016f-47f3-83b3-9966dbd9c95f",
        "correlationId": "a0e42ea6-a323-4f7b-94ba-26c49da48752",
        "timestamp": "2024-07-12T08:35:45-05:00"
      }
    ],
    ...
  }
}

Zero Amount Authorization

Another common use case is where the merchant does not charge or reserve any funds on the customer's card but initiates a transaction to verify the card's validity. This is referred to as a zero-amount or zero-dollar transaction.

📘

Saved Zero-Amount Authorization

With savePaymentOption enabled, a zero-amount authorization essentially functions the same way as the store transaction. It is the merchant that decides which one to use as either can be used interchangeably as a matter of personal preference or use case. For example, the merchant can either use the vaulted PayConex™ token returned in response or repeatedly capture the same zero-amount transaction.

🚧

Note

If savePaymentOption is turned off, the zero-amount authorization or store transaction will be rejected.

Request

POST /api/v4/accounts/{accountId}/payments/auth

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "0",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:auth

Response

{
  "transactionId": "000000046466",
  "status": "SAVED",
  "timestamp": "2025-04-02T21:03:44.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "history": [
      {
        "action": "authorization",
        "requestId": "be0aa6f4-505c-43ff-beef-43a8bb5b30be",
        "correlationId": "5a13bd76-61d0-4143-90f3-fe43fb1d5a15",
        "timestamp": "2025-04-02T16:03:42-05:00"
      }
    ],
    "networkTransactionId": "015092598402315CN  "
  },
  "amounts": {
    "currency": "USD",
    "approved": "0.00",
    "requested": "0.00"
  },
  "auth": {
    "code": "OK6860",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "AUTHORIZATION",
  "entryMode": "KEYED",
  "bfTokenReference": "bft_abfddede2a0b43b789ae570955fd5e9a",
  "refundObject": {
    "refundBalance": "0.00"
  },
  "shieldConexToken": {
    "bfid": "djI6...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  }
}