Credit Card Authorization

Overview

Credit cards are the most commonly accepted payment method type and are enabled for all Payment Service integrations. To take an order, funds are authorized on a credit card. As merchandise for an order is shipped, authorized funds are captured in the amount that matches the value of the shipped goods.

There are currently two different sequences that can be used for making a credit card authorization.

  • Card Not Present: This sequence is the most commonly used for credit cards. The primary element in the request is the encrypted or tokenized card number. Use Radial-provided encryption or tokenization before initiating the card not present sequence.
  • Digital Wallet: This sequence is used for a digital wallet transaction (such as Apple Pay) when the digital wallet data has not been decrypted yet. The primary element in the request is an encrypted payload defined by the digital wallet provider. To use the digital wallet sequence, the payments system must be appropriately configured so that the payload can be decrypted.

Workflows

Workflow descriptions are available for both card not present and digital wallet payments.

Card Not Present

Digital Wallet

Raw PAN Workflows

The following diagram illustrates the possible workflows when attempting to obtain a credit card authorization when the payment information provided by the customer is a raw PAN.

1: Collect Payment Information

The customer will enter their payment information (credit card PAN and CSC) into the payment page. After they have submitted the payment information the webstore should take the following steps depending if the integration uses client side encryption of tokenization.

2: Protect Payment Information

After the payment information has been entered by the customer the webstore should protect it. This may be done either using client side encryption or tokenization.

2a: Client Side Encryption

If the integration uses client side encryption the credit card data should be encrypted using the store's encryption keys and the associated javascript encryption libraries. See the Client Side Encryption documentation for further details. Once encrypted the authorization should be submitted using the encrypted payment data.

2b: Tokenization

If the integration uses tokenization the following steps should be taken.

  1. Perform a Tender Type Lookup - Perform a tender type lookup for the entered card and use the returned tender type for tokenization. If the tender type look fails with an invalid card number error the customer should be returned to step 1 to provide new payment information.
  2. Perform Tokenization - Submit the pan for AJAX tokenization and use the returned token for subsequent API calls. See the tokenization documentation for further information.
  3. If errors occur during the tokenization process the next action should be determined based the webstore's PCI comliance level:
    • PCI Compliant - If the webstore is PCI compliant the authorization may proceed using the raw credit card data.
    • Webstore is NOT PCI Compliant - The customer should be returned to step 1 and asked to select an alternate payment method.

3: Perform Authorization

After the payment data has been protected the CreditCardAuthRequest should be submitted to the payment service. Further processing is performed based on the response code / if a timeout occurs.

3a: APPROVED

If the response code is APPROVED, the order may be submitted to the order management system for processing.

3b: AVS / CSC Corrections

When the authorization response code is AVS, CSC, or AVSCSC the following steps should be taken, based on a configurable number of attempts to perform a correction.

  • Maximum Attempts Not Reached - Prompt the user for updated address / CSC information based on the response code and submit a new CreditCardAuthorizationRequest with the updated information and the isRequestToCorrectCVVOrAVSError flag set to true.

    • AVS - Updated billing address information
    • CSC - Updated security code
    • AVSCSC - Updated billing address information and security code

    See notes below containing important information for performing corrections.

  • Maximum Attempts Reached - Submit the order to the order management system using the data from the most recent authorization attempt.

Important: When authorization requests are resubmitted for AVS / CSC / AVSCSC corrections only the billing address and card security code information should be updated. The same order number from the previous authorized transaction must be used in the new request. Although an AVS or CSC failure was returned, the card has already been authorized and the new request is simply trying to address the AVS/CSC/AVSCSC failure. If a new order number is used with the correction, the previous authorization will not be cancelled automatically. If a request is submitted with a different order number, it is the responsibility of the webstore to make a payment authorization cancel call with the previous order number to cancel the previous authorization.

3c: PaymentProcessorTimeout

If the authorization response code is PaymentProcessorTimeout the following steps should be taken based on a configurable number of retries.

  • Maximum Retries Not Reached - The webstore should attempt to resubmit the authorization. The submitted request must be submitted using a new request ID. All other request data should remain the same.
  • Maximum Retries Reached - The webstore should display an error message to the customer and return to Step 1 asking them to choose an alternate payment method.

3d: DECL / DECLF

For a authorizations rejected with response codes of DECL or DECLF the following steps should be followed based on a configurable number of authorization attempts.

  • Maximum Authorization Attempts Not Reached - The customer should be returned to step 1 and prompted to enter new payment information. The webstore must keep track internally of the number of times during the checkout the user provided payment data that resulted in a DECL / DECLF response.
  • Maximum Authorization Attempts Reached - Behavior should be based on the capabilities of the fraud system responsible for processing the order:
    • Fraud System Capable of Rejecting Order - If the fraud system is capable of properly identifying the order as fraudulent the order should be submitted for fraud processing.
    • Fraud System Not Capable of Rejecting Order - The order should be rejected and an error message displayed to the customer.

3e: DECLR

For a authorizations rejected with response codes of DECLR

  • Fraud System Capable of Rejecting Order - If the fraud system is capable of properly identifying the order as fraudulent the order should be submitted for fraud processing.
  • Fraud System Not Capable of Rejecting Order - The order should be rejected and an error message displayed to the customer.

3f: Response Timeout

If the webstore experiences a timeout before receiving a reply the following steps should be taken based on a configurable number of retries.

  • Maximum Retries Not Reached - The webstore should attempt to resubmit the authorization. The submitted request must be the same as the original request, including using the same request ID.
  • Maximum Retries Reached - The webstore should submit an authorization cancel request for the authorization request sent. The customer should be returned to the payment page (Step 1) and prompted for an alternate payment.

Digital Wallet Work Flows

The following diagram illustrates the possible workflows when attempting to obtain a credit card authorization when the payment information provided by the customer is a digital wallet payment (e.g. Apple Pay)..

1: Collect Payment Information

The following steps will be taken for the customer to provide their digital wallet payment information.

  1. The customer selects a digital wallet payment method on the payment page.
  2. The customer is redirected to another site or application on their device to authenticate themselves.
  3. The site or application returns the customer to the webstore with the digital payment payload which is to be used for the authorization process.

2: Perform Authorization

After the payment data has been protected the CreditCardAuthRequest should be submitted to the payment service. Further processing is performed based on the response code / if a timeout occurs.

2a: Successful Authorization

If the response code for the authorization is APPROVED, AVS, CSC, or AVSCSC the order should be submitted to the order management system for further processing.

2b: PaymentProcessorTimeout

If the authorization response code is PaymentProcessorTimeout the following steps should be taken based on a configurable number of retries.

  • Maximum Retries Not Reached - The webstore should attempt to resubmit the authorization. The submitted request must be submitted using a new request ID. All other request data shoudl remain the same.
  • Maximum Retries Reached - The webstore should display an error message to the customer and return to Step 1 asking them to choose an alternate payment method.

2c: DECL / DECLF

For a authorizations rejected with response codes of DECL or DECLF the following steps should be followed based on a configurable number of authorization attempts.

  • Maximum Authorization Attempts Not Reached - The customer should be returned to step 1 and prompted to enter new payment information. The webstore must keep track internally of the number of times during the checkout the user provided payment data that resulted in a DECL / DECLF response.
  • Maximum Authorization Attempts Reached - Behavior should be based on the capabilities of the fraud system responsible for processing the order:
    • Fraud System Capable of Rejecting Order - If the fraud system is capable of properly identifying the order as fraudulent the order should be submitted for fraud processing.
    • Fraud System Not Capable of Rejecting Order - The order should be rejected and an error message displayed to the customer.

2d: DECLR

For a authorizations rejected with response codes of DECLR

  • Fraud System Capable of Rejecting Order - If the fraud system is capable of properly identifying the order as fraudulent the order should be submitted for fraud processing.
  • Fraud System Not Capable of Rejecting Order - The order should be rejected and an error message displayed to the customer.

2e: Response Timeout

If the webstore experiences a timeout before receiving a reply the following steps should be taken based on a configurable number of retries.

  • Maximum Retries Not Reached - The webstore should attempt to resubmit the authorization. The submitted request must be the same as the original request, including using the same request ID.
  • Maximum Retries Reached - The webstore should submit an authorization cancel request for the authorization request sent. The customer should be returned to the payment page (Step 1) and prompted for an alternate payment.

Samples

Samples and detailed API documentation are available on the following pages:

Endpoint Summary

Action URI Template URI Example Request Body Response
POST /v[M.m]/stores/[StoreID]/
payments/creditcard/auth/
[TenderCode].[format]		 /v1.0/stores/store123/
payments/creditcard/auth/VC.xml		 XML 200 + XML response