Credit Card Setup Guide

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.

For detailed API information, see the following page:

Credit Card Processing

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.

Credit Card Life Cycle: Normal Flow

This flow covers the system interactions that occur for the standard, happy-path credit card use case:

Credit card checkout in the webstore is successful.
The order passes the fraud check.
The order is successfully fulfilled.
Payment is settled.

Shopper Checkout

The webstore sends a CreditCardAuthRequest message to the Payment Service and receives an approval.
The webstore places the order in the order management system.

Order Management

The order management system sends the order for fraud review via a RiskAssessmentRequest message.
The order management system waits for a RiskAssessmentReply message to be returned asynchronously via the Advanced Message Queuing Protocol (AMQP).
The Risk Service uses order and payment data to assess risk. Some orders might be flagged for manual review.
The Risk Service sends a RiskAssessmentReply message with the result that the order passed its fraud check.
The order is released for fulfillment.

When part or all of the order is available for fulfillment, the following steps are performed:

The order management system prepares an invoice for the shipment.
The order management system calls confirm funds to confirm that the payment authorization is still valid for the currency amount of the invoice.
If the confirm funds response is positive, the shipment is released for fulfillment from the warehouse or third-party shipper.
The fulfillment system sends a confirmation that the shipment was shipped.
The order management system calls issues a payment settlement request to collect payment on the shipment.

Credit Card Fault Response

When credit card processing encounters an exception that should be handled at the web store or the client layer, a fault response message is returned. For a list of fault response codes and more information, see Credit Card Fault Response Codes.

Credit Card Life Cycle: Order Canceled Due to Fraud

This flow covers the system interactions that occur when the risk review rejects an order that used a credit card for payment:

Credit card checkout in the webstore is successful.
The order is rejected in the fraud check.
The credit card authorization is canceled.

Shopper Checkout

The webstore sends a CreditCardAuthRequest message to the Payment Service and receives an approval.
The webstore places the order in the order management system.

Order Management

The order management system sends the order for fraud review via a RiskAssessmentRequest message.
The order management system waits for a RiskAssessmentReply message to be returned asynchronously via the AMQP.
The Risk Service uses order and payment data to assess risk. Some orders might be flagged for manual review.
The Risk Service sends a RiskAssessmentReply message with the result that the order failed its fraud check.
The order management system cancels the order.
The order management system sends a PaymentAuthCancelRequest message to the Payment Service to release the authorization hold on the customer's funds.
The order management system waits for a PaymentAuthCancelReply message to be returned asynchronously via the AMQP.
The Payment Service sends a PaymentAuthCancelReply message.

Credit Card API Operations

Credit card processing uses the following API operations:

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.

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.
Perform Tokenization - Submit the pan for AJAX tokenization and use the returned token for subsequent API calls. See the tokenization documentation for further information.
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 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 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.

The customer selects a digital wallet payment method on the payment page.
The customer is redirected to another site or application on their device to authenticate themselves.
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.