On This Page

Payments Developer Guide

This section describes how to use this guide and where to find further information.
Audience and Purpose
This guide is written for application developers who want to use the
Simple Order API
 to integrate payment card processing into an order management system.
Implementing the
Cybersource
 payment services requires software development skills. You must write code that uses the API request and response fields to integrate the payment card services into your existing order management system.
Conventions
These statements appear in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
A
Warning
 contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional processor-specific versions of this guide and additional technical documentation.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

26.04.01

Added related reference information (Related to this Page) to applicable topics.

26.02.01

Test Cards
Added UATP test card numbers. See Test Card Numbers.

26.01.02

This revision contains only editorial changes and no technical updates.

26.01.01

This revision contains only editorial changes and no technical updates.

25.09.02

This revision contains only editorial changes and no technical updates.

25.09.01

This revision contains only editorial changes and no technical updates.

25.08.01

This revision contains only editorial changes and no technical updates.

25.07.01

This revision contains only editorial changes and no technical updates.

25.05.01

International Transaction Compliance
Added a section about international transaction compliance. See Compliance.

Introduction to Payments

This introduction provides the basic information that you need to successfully process payment transactions. It also provides an overview of the payments industry and provides workflows for each process.
With
Cybersource
 payment services, you can process payment cards (tokenized or non-tokenized), digital payments such as Apple Pay and Google Pay, and customer ID transactions. You can process payments across the globe and across multiple channels with scalability and security.
Cybersource
 supports a large number of payment cards and offers a wide choice of gateways and financial institutions, all through one connection.
Visit the
Cybersource
 documentation hub to find additional processor-specific versions of this guide and additional technical documentation.

Financial Institutions and Payment Networks

Financial institutions and payment networks enable payment services to function. These entities work together to complete the full payment cycle.

Merchant Financial Institutions (Acquirers)

A merchant financial institution, also known as an
acquirer
, offers accounts to businesses that accept payments. Before you can accept payments, you must have a merchant account from an acquirer. Your merchant account must be configured to process card-not-present or mail-order/telephone-order (MOTO) transactions.
Each acquirer has connections to a limited number of payment processors. You must choose a payment processor that your acquirer supports.
You can expect to pay these fees:
  • Discount rates: your acquirer charges a fee and collects a percentage of every transaction. The combination of the fee and the percentage is called the
    discount rate
    . These charges can be
    bundled
     (combined into a single charge) or
    unbundled
     (charged separately).
  • Interchange fees: payment networks, such as Visa or Mastercard, each have a base fee, called the
    interchange fee
    , for each type of transaction. Your acquirer and processor can show you ways to reduce this fee.
  • Chargebacks: when cardholders dispute charges, you can incur
    chargebacks
    . A chargeback occurs when a charge on a customer’s account is reversed. Your acquirer removes the money from your account and could charge you a fee for processing the chargeback.
Take these precautions to prevent chargebacks:
  • Use accurate merchant descriptors so that customers can recognize the transactions on their statements.
  • Provide good customer support.
  • Ensure rapid problem resolution.
  • Maintain a high level of customer satisfaction.
  • Minimize fraudulent transactions.
If excessive chargebacks or fraudulent changes occur, these actions might be taken:
  • You might be required to change your business processes to reduce the number chargebacks, fraud, or both.
  • Your acquiring institution might increase your discount rate.
  • Your acquiring institution might revoke your merchant account.
Contact your sales representative for information about products that can help prevent fraud.

Customer Financial Institutions (Issuers)

A customer financial institution, also known as an
issuer
, provides payment cards to and underwrites lines of credit for their customers. The issuer provides monthly statements and collects payments. The issuer must follow the rules of the payment card companies to which they belong.

Payment Networks

Payment networks manage communications between acquirers and issuing banks. They also develop industry standards, support their brands, and establish fees for acquiring institutions.
Some payment networks, such as Visa and Mastercard, are trade associations that do not issue cards. Issuers are members of these associations, and they issue cards under license from the association.
Other networks, such as Discover
and American Express
, issue their own cards. Before you process cards from these companies, you must sign agreements with them.

Payment Processors

Payment processors connect with acquirers. Before you can accept payments, you must register with
a payment processor
.
An acquirer might require you to use a payment processor with an existing relationship with the acquirer.
Your payment processor
 assigns one or more merchant IDs (MIDs) to your business. These unique codes identify your business during payment transactions.
This table lists the processors and corresponding card types that are supported for payment services.
Only the card types explicitly listed here are supported.
Payment Processor and Supported Card Types
Payment Processor
Supported Card Types
Notes
UATP
UATP

Card Types

You can process payments with these kinds of cards:
  • Credit cards
  • Debit cards
For a list of supported card types, see Payment Processors.

Credit Cards

Cardholders use credit cards to borrow money from issuing banks to pay for goods and services offered by merchants that accept credit cards.

Debit Cards

A debit card is linked to a cardholder's bank account. The funds are taken out of the customer's bank account, and the transaction is included on the customer's bank account statement. The customer does not receive a credit card bill as with a regular credit card.

Transaction Types

This topic provides information about transaction types that are supported by your processor.

Card-Not-Present Transactions

Authorizations with Card Verification Numbers

Card verification numbers (CVNs) are a required feature for the authorization service.
The CVN is printed on a payment card, and only the cardholder can access it. The CVN is used in card-not-present transactions as a verification feature. Using the CVN helps reduce the risk of fraud.
CVNs are not included in payment card track data and cannot be obtained from a card swipe, tap, or dip.
CVNs must not be stored after authorization.
In Europe, Visa mandates that you not include a CVN for mail-order transactions and not record a CVN on any physical format such as a mail-order form.

CVN Locations and Terminology

For most cards, the CVN is a three-digit number printed on the back of the card, to the right of the signature field.
For American Express, the CVN is a four-digit number printed on the front of the card above the card number.

Figure:

CVN Locations
Image depicting the location of the CVN on the back of most cards and the front of an American Express card.
Each payment card company has its own name for the CVN value:
  • Mastercard calls it the
    card validation code
     (CVC2).
  • Visa calls it the
    card verification value
     (CVV2).

International Transactions

Consider compliance and merchant remittance funding when processing international transactions.

Compliance

Accepting payments from a country other than your own requires that you observe the processing rules and practices of the payment systems in that country. This list describes areas of compliance that are especially important:
  • Merchant descriptor requirements—A merchant descriptor communicates merchant information to customers to remind them of the circumstances that triggered a payment. Merchant descriptors reduce the possibility of a chargeback. Accordingly, the merchant descriptor displayed on a customer’s statement should be a close match to the name on your website. It is not good practice to consolidate multiple websites into a single merchant account and use a generic descriptor that more-or-less covers all offerings.
  • Excessive chargebacks—To prevent an excessive number of chargebacks, you must maintain good customer support, rapid problem resolution, a high level of customer satisfaction, and transaction management processes that minimize fraudulent transactions. When payment card chargebacks become excessive, you must change business processes to reduce chargebacks. If chargebacks are not reduced to a satisfactory level, your account can be terminated.

Merchant Remittance Funding

You can request that the transaction proceeds be converted to another currency. Currency conversion uses a foreign exchange rate to calculate the conversion to the requested currency. The foreign exchange rate might be explicitly stated as a rate or implicitly stated as a transaction amount. The funded amount and can vary from day to day. The foreign exchange rate might also include an increase for the foreign exchange risk, sales commissions, and handling costs.

Payment Services

Various services are involved in processing payments.
These services enable customers to purchase goods and services. They also enable merchants to receive payments from customer accounts, to provide refunds, and to void transactions.

Authorization

An authorization confirms that a payment card account holds enough funds to pay for a purchase. Authorizations can be made online or offline.

Micropayment Authorization

Micropayments are payments for less than one unit in the transaction’s currency.
Cybersource
 does not support micropayment authorizations for
UATP
.

Online Authorization

Online authorizations provide immediate confirmation of funds availability. The customer's financial institution also reduces the amount of credit available in the customer's account, setting aside the authorized funds for the merchant to capture at a later time. Authorizations for most payment cards are processed online. Typically, it is safe to start fulfilling the order when you receive an authorization confirmation.
An
An online authorization confirmation and the subsequent hold on funds expire after a specific length of time. Therefore it is important to capture funds in a timely manner. The issuing bank sets the expiration time interval, but most authorizations expire within
5 to
7 days.
The issuing bank does not inform
Cybersource
 when an authorization confirmation expires. By default, the authorization information for each transaction remains in the
Cybersource
 database for 180 days after the authorization date. To capture an authorization that expired with the issuing bank, you can resubmit the authorization request.

Offline Authorization

Online transactions require an internet connection. In situations where the internet is not available, for example, due to an outage, merchants can continue to take credit card payments using offline transactions. An offline authorization is an authorization request for which you do not receive an immediate confirmation about the availability of funds.
Offline authorizations have a higher level of risk than online transactions because they do not confirm funds availability or set aside the funds for later capture. Further, it can take up to 5 days to receive payment confirmations for offline transactions. To mitigate this risk, merchants may choose to fulfill orders only after receiving payment confirmation.

Authorization Workflow

This image and description show the authorization workflow:
  1. The customer purchases goods or services from the merchant using a payment card.
  2. You send an authorization request over secure internet connection to
    Cybersource
    . When the customer buys a digitally delivered product or service, you can request both the authorization and the capture at the same time. When the customer buys a physically fulfilled product, do not request the capture until you ship the product.
  3. Cybersource
     validates the order information then contacts your payment processor and requests authorization.
  4. The processor sends the transaction to the payment card company, which routes it to the issuing bank for the customer's payment card. Some card companies, including Discover
    and American Express
    , act as their own issuing banks.
  5. The issuing bank approves or declines the request.
    • If funds are available, the issuing bank reserves the amount of the authorization request and returns an authorization approval to
      Cybersource
      .
    • If the issuing bank denies the request, it returns an authorization denial to
      Cybersource
      .
  6. Cybersource
     runs its own tests then tells you whether the authorization succeeded.

Sale

A sale is a bundled authorization and capture. Some processors and acquirers require a sale transaction instead of using separate authorization and capture requests. For other processors and acquirers, you can request a sale instead of a separate authorization and capture when you provide the goods or services immediately after taking an order.
There are two types of sale processing: dual-message processing and single-message processing.

Dual-Message Processing

Dual-message processing is a two-step process. The authorization is processed first. If the authorization is successful, the capture is processed immediately afterward. The response includes the authorization and the capture information. If the authorization is declined, the capture is not processed, and the response message includes only the authorization information.

Capture

A capture is a follow-on transaction to an authorization. It is used to transfer the authorized funds from the customer's account to the merchant account. To link the authorization transaction to the capture transaction, you include a request ID in your capture request. This request ID is returned to you in the authorization response.
Captures are typically not performed in real time. They are placed in a batch file and sent to the processor, and the processor settles all of the captures at one time. In most cases, these batch files are sent and processed outside of the merchant's business hours. It usually takes 2 to 4 days for the acquiring financial institution to deposit the funds into the merchant account.
When fulfilling only part of a customer’s order, do not capture the full amount of the authorization. Capture only the cost of the delivered items. When you deliver the remaining items, request a new authorization, and then capture the new authorization.
It is not possible to perform a capture if a transaction is in a review state, which can occur if you use a fraud management service. You must accept the transaction prior to capture. For more information, see the fraud management documentation in
the
Business Center
.

Capture Workflow

The capture workflow begins when you send a request for a capture.
  1. The merchant sends a request for a capture to the
    Cybersource
     gateway.
  2. For online captures,
    Cybersource
     validates the order information then sends an online capture to the payment processor.
    For offline captures,
    Cybersource
     stores the capture request in a batch file and sends the batch file to the payment processor after midnight.
  3. The processor validates the request and forwards it to the issuing bank.
  4. The issuing bank transfers funds to the acquiring bank.
The payment processor does not notify
Cybersource
 that the money has been transferred. To ensure that all captures are processed correctly, you should reconcile your capture requests with the capture reports from your processor.

Credit

Credits are payment refunds from a merchant to the cardholder after a cardholder pays for a product or service and that payment is captured by the merchant. When a credit request is successful, the issuer transfers funds from the merchant bank (acquirer) account to the customer's account. It typically takes 2 to 4 days for the acquirer to transfer funds from your merchant account.
There are two types of credits: a
follow-on credit
 that is linked to an original capture or sale, and a
stand-alone credit
 that is not linked to an original capture or sale.

Follow-on Credit

Follow-on credits, also known as
refunds
,
 use the capture request ID to link the refund to the original transaction.
This request ID is returned during the capture request (also known as a
settlement
) and is used in all subsequent refunds associated with the original capture.
 The request ID links the transaction to the customer’s billing and account information, so you are not required to include those fields in the
follow-on credit
 request.
When you combine a request for a
follow-on credit
 with a request for another service, such as the tax calculation service, you must provide the customer’s billing and account information.
Unless otherwise specified,
follow-on credits
 must be requested within 180 days of a settlement. You can request multiple follow-on
credits
 against a single capture or sale transaction as long as the total amount does not exceed the original purchase amount. To perform multiple follow-on
credits
, use the same request ID in each request.

Stand-Alone Credits

Stand-alone credits are not connected to an original transaction. Stand-alone credits do not have a time restriction, and they can be used to issue refunds more than 180 days after a transaction settlement.

Refund and Credit Workflow

This workflow applies to follow-on credits, also known as refunds, and stand-alone credits. It begins when you send a request for a refund or credit.
Refunds and credits do not happen in real time. All of the credit requests for a day are typically placed in a file and sent to the processor as a single
batch
 transaction. In most cases, the batch transaction is settled overnight.
  1. The merchant sends the refund or credit request to
    Cybersource
    .
  2. For online refunds and credits,
    Cybersource
     validates the order information then sends the request to the payment processor.
    For offline refunds and credits,
    Cybersource
     stores the request in a batch file and sends the batch file to the payment processor after midnight.
  3. The processor validates the request and forwards it to the acquiring bank.
  4. The acquiring bank transfers funds to the issuing bank.
Not all processors support stand-alone credits.

Void

A void cancels a capture or credit request that you submitted to
Cybersource
 but has not already been submitted to your processor. Capture and credit requests are usually submitted to your processor once a day, so your window for successfully voiding a capture or credit request is small. A void request is declined when the capture or credit request has already been sent to the processor.
After a void is processed, you cannot credit or capture the funds. You must perform a new transaction to capture or credit the funds. Further, when you void a capture, a hold remains on the authorized funds. If you are not going to re-capture the authorization,
and if your processor supports authorization reversal after void (ARAV),
 you should request an authorization reversal to release the hold on the unused funds.
A void uses the capture or credit request ID to link the transactions. The authorization request ID is used to look up the customer’s billing and account information, so there is no need to include those fields in the void request. You cannot perform a follow-on credit against a capture that has been voided.

Testing the Payment Services

To ensure that requests are processed correctly, you must test the basic success and error conditions for each service you plan to use.

Requirements for Testing

Before you can test, contact customer support to activate the credit card services and configure your account for testing. You must also contact your processor to set up your processor account.
When building your connection to the
Cybersource
 payment gateway, ensure that you have implemented controls to prevent card testing or card enumeration attacks on your platform.
For more information, see the best practices guide.
When we detect suspicious transaction activity associated with your merchant ID, including a card testing or card enumeration attack,
Cybersource
 reserves the right to enable fraud management tools on your behalf in order to mitigate the attack. The fraud team might also implement internal controls to mitigate attack activity. These controls block traffic that is perceived as fraudulent. Additionally, if you are using one of our fraud tools and experience a significant attack, our internal team might modify or add rules to your configuration to help prevent the attack and minimize the threat to our infrastructure. However, any actions taken by
Cybersource
 would not replace the need for you to follow industry standard best practices to protect your systems, servers, and platforms.
Follow these requirements when you test your system:
  • Use your regular merchant ID.
  • Use a real combination for the city, state, and postal code.
  • Use a real combination for the area code and telephone number.
  • Use a nonexistent account and domain name for the customer’s email address.
  • Simple Order API test server:
    https://ics2wstesta.ic3.com/commerce/1.x/transactionProcessor

Test Card Numbers

Use these payment card numbers to test the authorization, capture, and credit services. Remove the spaces from the test card numbers when sending them to the test system. Do not use real payment card numbers. To test card types that are not included in the list, use an account number that is in the card’s BIN range. For best results, try each test with a different service request and with different test payment card numbers.
The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with these card numbers, remove the spaces and replace each X with a 0 (zero).
  • American Express—3782 8224 631X XX5
  • Discover—6X11 1111 1111 1117
  • JCB—3566 1111 1111 1113
  • Maestro (International)
    • 5X33 9619 89X9 17
    • 5868 2416 0825 5333 38
  • Maestro (UK Domestic)—the issue number is not required for Maestro (UK Domestic) transactions.
    • 6759 4111 XXXX XXX8
    • 6759 56XX 45XX 5727 054
    • 5641 8211 1116 6669
  • Mastercard
    • 2222 42XX XXXX 1113
    • 2222 63XX XXXX 1125
    • 5555 5555 5555 4444
  • UATP (CVV not required)
    • 1354 1234 5678 911
    • 1485 1234 5678 9X5
  • Visa—4111 1111 1111 1111

Using Amounts to Simulate Errors

You can simulate error messages by requesting authorization, capture, or credit services with specific amounts that trigger the error messages. These triggers work only on the test server, not on the production server.
Each payment processor uses its own error messages.
For more information, see: Simple Order API Testing Information

Test American Express Card Verification

Before using CVN with American Express, it is strongly recommended that you follow these steps:
  1. Contact customer support to have your account configured for CVN. Until you do this, you will receive a
    1
     in the
    ccAuthReply_cvCode
     response field.
  2. Test your system in production using a small currency amount, such as one currency unit. Instead of using the test account numbers, use a real payment card account number, and send an incorrect CVN in the request for authorization. The card should be refused and the request declined.

Standard Payment Processing

This section shows you how to process various authorization, capture, credit, and sales transactions.

Basic Authorization

This section provides the information you need in order to process a basic authorization.
All supported card types can process authorizations.

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Declined Authorization

If an authorization is declined, you can use response categories to help you decide whether to retry or block a declined transaction. These response fields provide additional information:
  • ccAuthReply_paymentInsightsInformation_responseInsightsCategory
  • ccAuthReply_paymentInsightsInformation_responseInsightsCategoryCode
    These fields are available starting in the XML schema version 1.193.
Category codes have possible values (such as
01
) each of which corresponds to a category that contains a description.
You cannot retry this category code and category:
  • 01 ISSUER_WILL_NEVER_APPROVE
For these values, you can retry the transaction a maximum of 15 times over a period of 30 days:
  • 02 ISSUER_CANNOT_APPROVE_AT_THIS_TIME
  • 03 ISSUER_CANNOT_APPROVE_WITH_THESE_DETAILS
    : Data quality issue. Revalidate data prior to retrying the transaction.
  • 04 GENERIC_ERROR
  • 97 PAYMENT_INSIGHTS_INTERNAL_ERROR
  • 98 OTHERS
  • 99 PAYMENT_INSIGHTS_RESPONSE_CATEGORY_MATCH_NOT_FOUND

Required Fields for Processing a Basic Authorization

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccAuthService_run
Set the value to
true
.
merchantID
merchantReferenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Processing a Basic Authorization

Request
billTo_city=Ann Arbor
billTo_country=US

billTo_email=null@cybersource.com

billTo_firstname=John
billTo_lastname=Smith
billTo_postalCode=48104-2201
billTo_state=MI
billTo_street1=201 S. Division St.
card_accountNumber=41111111XXXXXXXX
card_expirationMonth=12
card_expirationYear=2023
ccAuthService_run=true
merchant_id=npr_paymentech
merchant_referenceCode=TC42703-1
purchaseTotals_currency=usd
purchaseTotals_grandTotalAmount=100
Response to a Successful Request
requestID=6629977932421985593067
decision=ACCEPT
reasonCode=100
merchantReferenceCode=TC42703-1
purchaseTotals_currency=usd
ccAuthService_reconciliationID=57953165A7YFPS77
ccAuthReply_amount=100.00
ccAuthReply_avsCode=5
ccAuthReply_authorizationCode=570110
ccAuthReply_processorResponse=1
ccAuthReply_authorizedDateTime=2022-09-12T154953Z
ccAuthReply_paymentNetworkTransactionID=123456789619999
Response to a Declined Request
requestID=6629977932421985593067
merchantReferenceCode=Merchant_REF
decision=REJECT
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=Y
ccAuthReply_paymentNetworkTransactionID=111222
ccAuthReply_transactionID=111222

ccAuthReply_paymentInsightsInformation_responseInsightsCategory=
    ISSUER_CANNOT_APPROVE_WITH_THESE_DETAILS
ccAuthReply_paymentInsightsInformation_responseInsightsCategoryCode=03

ccAuthReply_processorResponse=183  
ccAuthReply_reasonCode=233

Authorization with Line Items

This section shows you how to process an authorization with line items.
The main difference between a basic authorization and an authorization that includes line items is that the
purchaseTotals_grandTotalAmount
 field, which is included in a basic authorization, is substituted with one or more line items that are included in
the
item_#_
 fields, starting with the
item_0_
 fields
.

Fields Specific to this Use Case

These
fields
 are required for each line item that you use:
item_#_unitPrice
item_#_quantity
item_#_productCode
item_#_productSKU
Optional when
item_#_productCode
 is set to
default
,
shipping_only
,
handling_only
, or
shipping_and_handling
item_#_productName
Optional when
item_#_productCode
 is set to
default
,
shipping_only
,
handling_only
, or
shipping_and_handling
At a minimum, you must include the
item_#_unitPrice
 field in order to include a line item in an authorization. When this field is the only field included in the authorization, the system sets:
  • item_#_productCode
    :
    default
  • item_#_quantity
    :
    1
For example, these three line items are valid.
item_0_unitPrice=10.00
item_1_unitPrice=5.99
item_1_quantity=3
item_1_productCode=shipping_only
item_2_unitPrice=29.99
item_2_quantity=3
item_2_productCode=electronic_good
item_2_productSKU=12384569
item_2_productName=receiver

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Optional Line Item Fields

These fields can be used to provide more line item information. For more information on each field, see the field reference guide:
  • item_#_buyerRegistration
  • item_#_commodityCode
  • item_#_nationalTax
  • item_#_orderAcceptanceCity
  • item_#_orderAcceptanceCountry
  • item_#_orderAcceptancePostalCode
  • item_#_orderAcceptanceState
  • item_#_orderOriginCity
  • item_#_orderOriginCountry
  • item_#_orderOriginPostalCode
  • item_#_orderOriginState
  • item_#_otherTax_#_passengerFirstName
  • item_#_otherTax_#_passengerLastName
  • item_#_productCode
  • item_#_productDescription
  • item_#_productName
  • item_#_productSKU
  • item_#_quantity
  • item_#_shippingDestinationType
  • item_#_unitPrice

Required Fields for Processing an Authorization with Line Items

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccAuthService_run
Set the value to
true
.
merchantID
merchantReferenceCode
Required when
billTo_personalID
 is included in the request.
purchaseTotals_currency
purchaseTotals_grandTotalAmount
Either
purchaseTotals_grandTotalAmount
 or
item_#_unitPrice
 must be included in the request.

Simple Order Example: Processing an Authorization with Line Items

Request
billTo_city=Palo Alto
billTo_country=US

billTo_email=null@cybersource.com

billTo_firstname=Julia
billTo_lastname=Fernandez
billTo_postalCode=94053
billTo_state=CA
billTo_street1=123 Main St.
card_accountNumber=41111111XXXXXXXX
card_expirationMonth=12
card_expirationYear=2023
ccAuthService_run=true
dcc_dccIndicator=1
merchant_id=MID23
merchant_referenceCode=Merchant_REF
purchaseTotals_currency=usd
item_0_unitPrice=10.00
item_1_unitPrice=5.99
item_1_quantity=3
item_1_productCode=shipping_only
item_2_unitPrice=29.99
item_2_quantity=3
item_2_productCode=electronic_good
item_2_productSKU=12384569
item_2_productName=receiver
purchaseTotals_exchangeRate=0.91
purchaseTotals_originalAmount=107.33
purchaseTotals_originalCurrency=eur
Response to a Successful Request
additional_processor_response=e1cdcafc-cdbb-4ef7-8788-a1234e844805
request_id=6461515866500167772420
decision=ACCEPT
reasonCode=100
merchantReferenceCode=Merchant_REF
purchaseTotals_currency=usd
cardCategory=FccAuthService_reconciliationID=ZUDCXJO8KZRFXQJJ
ccAuthReply_amount=117.94
ccAuthReply_avsCode=5
ccAuthReply_authorizationCode=570110
ccAuthReply_processorResponse=1
ccAuthReply_authorizedDateTime=2022-03-01T161947Z
ccAuthReply_paymentNetworkTransactionID=111222

Sale

This section provides the information you need in order to process a sale transaction.
A sale combines an authorization and a capture into a single transaction.

Endpoint

Set the
ccAuthService_run
 field to
true
, and the
ccCaptureService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for a Sale

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_cardType
card_expirationMonth
card_expirationYear
ccAuthService_commerceIndicator
ccAuthService_run
Set the value to
true
.
ccCaptureService_run
Set the value to
true
.
merchantID
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Sale

Request
ccAuthService_run=true
ccCaptureService_run=true
merchantID=Napa Valley Vacations
merchantReferenceCode=482046C3A7E94F5
billTo_firstName=John
billTo_lastName=Doe
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_postalCode=94043
billTo_country=US
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD
card_expirationMonth=12
card_expirationYear=2031
card_accountNumber=4111111111111111
card_cardType=001
Response to a Successful Request
requestID=0305782650000167905080
decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5
purchaseTotals_currency=USD
ccAuthReply_reconciliationID=ABCDE12345FGHIJ67890
ccAuthReply_cardCategory=F^
ccAuthReply_cardGroup=0
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_accountBalance=50.05
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_processorResponse=A
ccAuthReply_paymentNetworkTransactionID=3312345
ccCaptureReply_amount=49.95
ccCaptureReply_reasonCode=100
ccCaptureReply_reconciliationID=1094820975023470

Capture

This section describes how to capture an authorized transaction.

Endpoint

Set the
ccCaptureService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Capturing an Authorization

ccCaptureService_authRequestID
ccCaptureService_run
merchantID
merchantReferenceCode
Set the value to
merchant_ref_number
 value used in corresponding authorization request.
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Capturing an Authorization

Request
ccCaptureService_authRequestID=6629978499572480812782
ccCaptureService_run=true
merchantID=npr_paymentech
merchantReferenceCode=TC42703-1
purchaseTotals_grandTotalAmount=100.00
Response to a Successful Request
ccCaptureReply_amount=100.00
ccCaptureReply_requestDateTime=2022-09-12T173947Z
decision=ACCEPT
merchantReferenceCode=TC42703-1
purchaseTotals_currency=USD
requestID=6630043878211258349460

Follow-On
Credit

This section provides the information you need in order to process a follow-on
credit
, which is linked to a capture or sale. You must request a follow-on
credit
 within 180 days of the authorization or sale.

Endpoint

Set the
ccCreditService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Processing a
Follow-On Credit

ccCreditService_captureRequestID
ccCreditService_run
Set the value to
true
.
merchantID
merchantReferenceCode
Set the value
merchantReferenceCode
 value used in corresponding capture or sale request.
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Stand-Alone Credit

This section shows you how to process a
stand-alone
credit, which is not linked to a capture or sale. There is no time limit for requesting a
stand-alone
credit.

Endpoint

Set the
ccCreditService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Processing a
Stand-Alone
Credit

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccCreditService
Set the value to
true
. For example
ccCreditService run="true"
.
merchantID
merchantReferenceCode
Set to
merchantReferenceCode
 value used in corresponding capture request.
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Processing a Stand-Alone Credit

Request
<requestMessage>
    <billTo>
        <firstName>John</firstName>
        <lastName>Doe</lastName>
        <street1>1295 Charleston Road</street1>
        <city>Mountain View</city>
        <state>CA</state>
        <postalCode>94043</postalCode>
        <country>US</country>
        <email>
test@cybs.com
</email>
    </billTo>
    <card>
        <accountNumber>CARD_NUMBER</accountNumber>
        <expirationMonth>12</expirationMonth>
        <expirationYear>2026</expirationYear>
    </card>
    <merchantID>lrsebctest</merchantID>
    <merchantReferenceCode>Postman-1666381004</merchantReferenceCode>
    <purchaseTotals>
        <currency>USD</currency>
        <grandTotalAmount>1.01</grandTotalAmount>
    </purchaseTotals>
    <ccCreditService run="true"/>
</requestMessage>
Response to a Successful Request
<c:replyMessge>
    <c:merchantReferenceCode>Postman-1666374834</c:merchantReferenceCode>
    <c:requestID>6663748348516429203007</c:requestID>
    <c:decision>ACCEPT</c:decision>
    <c:reasonCode>100</c:reasonCode>
    <c:purchaseTotals>
        <c:currency>USD</c:currency>
    </c:purchaseTotals>
    <c:ccAuthReply>
        <c:reasonCode>100</c:reasonCode>
        <c:amount>1.01</c:amount>
        <c:authorizationCode>888888</c:authorizationCode>
        <c:avsCode>X</c:avsCode>
        <c:avsCodeRaw>I1</c:avsCodeRaw>
        <c:authorizedDateTime>2022-10-21T17:53:54Z</c:authorizedDateTime>
        <c:processorResponse>100</c:processorResponse>
        <c:reconciliationID>66737280B9CGUCCP</c:reconciliationID>
        <c:paymentNetworkTransactionID>123456789619999</c:paymentNetworkTransactionID>
    </c:ccAuthReply>
    <c:card>
        <c:cardType>001</c:cardType>
    </c:card>
</c:replyMessge>

Void a Payment

This section describes how to void a payment that was submitted but not yet processed by the processor. A payment is also known as a sale, which is an authorization and capture in one API request. Include the payment ID in the void request endpoint to cancel the payment.

Required Fields for Voiding a Payment

merchantID
merchantReferenceCode
voidService_voidRequestID
Set this field to the request ID that was included in the sale response message.
voidService_run
Set the value to
true
.

Simple Order Example: Void a Payment

Request
<requestMessage>
    <merchantID>Napa Valley Vacations</merchantID>
    <merchantReferenceCode>482046C3A7E94F5</merchantReferenceCode>
    <voidService run="true">
        <voidRequestID>098123456789</voidRequestID>
    </voidService>
</requestMessage>
Response to a Successful Request
<c:replyMessage>
    <c:requestID>0305782650000167905080</c:requestID>
    <c:decision>ACCEPT</c:decision>
    <c:reasonCode>100</c:reasonCode>
    <c:merchantReferenceCode>482046C3A7E94F5</c:merchantReferenceCode>
    <c:voidReply>
        <c:reconciliationID>ABCDE12345FGHIJ67890</c:reconciliationID>
        <c:reasonCode>100</c:reasonCode>
        <c:amount>100.00</c:amount>
        <c:currency>USD</c:currency>
    </c:voidReply>
</c:replyMessage>

Void for a Capture or Credit

This section describes how to void a capture or credit that was submitted but not yet processed by the processor.

Endpoints

Void a Capture
Void a Credit
Set the
VoidService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Voiding a Capture or Credit

merchantID
merchantReferenceCode
voidService_voidRequestID
Set the value to the request ID included in the authorization response message.
voidService_run
Set the value to
true
.

Simple Order API Example: Voiding a Capture or Credit

Request
merchantID=Napa Valley Vacations
merchantReferenceCode=482046C3A7E94F5
voidService_run
voidService_voidRequestID=6522033834410167772169
Response to a Successful Request
requestID=0305782650000167905080
decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5
voidReply_reconciliationID=ABCDE12345FGHIJ67890
voidReply_reasonCode=100
voidReply_amount=49.95
voidReply_currency=USD