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 theREST APIto integrate payment card processing into an order management system.Implementing theCybersourcepayment 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:IMPORTANTAnImportantstatement contains information essential to successfully completing a task or learning a concept.WARNINGAWarningcontains 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 theCybersourcedocumentation 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
25.09.01
This revision contains only editorial changes and no technical updates.
25.08.01
- Standard Payment Processing
- Added support for using dynamic merchant category codes (MCCs) to override the MCC that is assigned to your account in an authorization or refund request.
- See the Merchant Category Codes section in:
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.
25.04.01
This revision contains only editorial changes
and no technical updates.
25.03
This revision contains only editorial changes and no technical updates.
25.02
This revision contains only editorial changes and no technical updates.
25.01
Added a testing section. See Testing the Payment Services.
- Credentialed Transactions
- Removed Mastercard required field for retrieving customer credentials during a CIT request. See Card-Specific Required Field for Retrieving Customer Credentials During a CIT.
24.14
This revision contains only editorial
changes and no technical updates.
24.13
This revision contains only editorial changes
and no technical updates.
24.12
This revision contains only editorial changes and no technical updates.
24.11
This revision contains only editorial changes and no technical updates.
24.10
This revision contains only editorial changes and no technical updates.
24.09
This revision contains only editorial changes and no technical updates.
Introduction to Payments
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 payment cards. 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, card-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 your acquirer to charge 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 thediscount rate. These charges can bebundled(combined into a single charge) orunbundled(charged separately).
- Interchange fees: payment networks, such as Visa or Mastercard, each have a base fee, called theinterchange 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 incurchargebacks. 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 fraudulant 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.
IMPORTANT
Only the card types explicitly listed here are
supported.
Payment Processor | Supported Card Types | Notes |
---|---|---|
FDC Nashville Global | Visa, Mastercard, American Express, Discover, Diners Club, JCB,
China UnionPay
|
Card Types
You can process payments with these kinds of cards:
- Co-badged cards
- Co-branded cards
- Credit cards
- Debit cards
- Prepaid cards
- Private label cards
- Quasi-cash
For a list of supported card types, see Payment Processors.
Co-Badged Cards
Co-badged cards are credit and debit cards that integrate two or more payment networks.
Co-Branded Cards
Co-branded cards are credit cards that are branded with a merchant's logo, brand, or other identifier as well as the payment network logo. These cards are not limited for use at the branded merchant and can be used at any merchant that accepts credit cards.
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 checking account. A merchant who accepts the debit
card can deduct funds directly from the account.
Prepaid Cards
Prepaid cards enable cardholders to pay for goods and services using money stored directly on
the card.
Private Label Cards
Private label cards are issued by private companies. They enable cardholders to borrow money
to pay for goods exclusively at the issuing company’s stores.
Transaction Types
This topic provides information about transaction types that are supported by your processor,
such as card-present, card-not-present, and international transactions.
Card-Not-Present Transactions
When a customer provides a card number, but the card and the customer are not physically
present at the merchant's location, the purchase is known as a
card-not-present
transaction
. Typical card-not-present transactions are internet and phone transactions.
Card-not-present transactions pose an additional level of risk to your business because the
customer’s identification cannot be verified. You can reduce that risk by using features such
as the Address Verification System (AVS) and Card Verification Numbers (CVNs). The AVS and
CVNs provide additional protection from fraud by verifying the validity of the customer’s
information and notifying you when discrepancies occur.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.
IMPORTANT
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
Each payment card company has its own name for the CVN value:
- American Express and Discover call it theCard Identification Number(CID).
- JCB calls it theCard Authentication Value(CAV2).
- Mastercard calls it theCard Validation Code(CVC2).
- Visa calls it theCard 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.
Token Management Service
Token Management Service
The
Token Management Service
(TMS
) tokenizes, securely stores,
and manages customer and payment data. TMS
enables you to: - Securely store a customer's payment details and their billing and shipping addresses.
- Create a network token of a customer's payment card.
TMS
simplifies your PCI DSS compliance. TMS
passes back to you tokens that represent this data. You then store these tokens in your
environment and databases instead of customer payment details. TMS
Token Types- Customer — Stores the buyer’s email address and the merchant's account ID for that buyer plus any other custom fields.
- Shipping Address — Stores a shipping address for a specific customer.
- Instrument Identifier — Stores either a payment card number or a bank account number and routing numberThis resource creates either:
- An Instrument Identifier token using details of a payment card or an ACH bank account.
- A payment network token using the details of a payment card; also uses the card expiration date and billing address, which are pass-through only fields.
- Payment Instrument — Stores a Payment Instrument using an Instrument Identifier token. It does not store the card number and cannot exist without an associated Instrument Identifier. It stores:
- Card expiration date
- Billing address
- Customer Payment Instrument — Creates and stores a payment instrument for a specific customer ID and an Instrument Identifier token.
TMS
Features- Create, retrieve, update, and delete tokens.
- Set a default payment instrument and shipping address for a customer.
- Process follow-on payment transactions with token IDs.
- Create and update tokens through bundled payment transactions.
IMPORTANT
Due to mandates from the Reserve Bank of India, Indian merchants cannot
store personal account numbers (PAN). Use network tokens instead. For more information
on network tokens, see the Network Tokenization section of the
Token Management Service
Guide.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.
Authorizations
An authorization confirms that
a payment
card account holds enough funds to pay
for a purchase. Authorizations can be made online or offline.Micropayment Authorizations
Micropayments are payments for less than one unit in the transaction’s currency.
For
FDC Nashville Global
, Cybersource
supports micropayment authorizations for these cards:- American Express
- Discover (in the US only)
- JCB (in the US only)
- Mastercard
- Visa
Online Authorizations
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
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 Authorizations
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.
Incremental Authorizations
Incremental authorizations are useful when a customer adds products and services to a purchase. After a successful initial authorization, you can request subsequent authorizations and request one capture for the initial authorization and the incremental authorizations.
The incremental authorization service is not the same as the incremental authorization scenario for a merchant-initiated transaction.
Scenario for the Incremental Authorization Service
This sequence is an example of how incremental authorizations work:
- The customer reserves a hotel room for two nights at a cost of 200.00 per night. You request an authorization for 400.00. The authorization request is approved.
- The customer orders dinner through room service the first night. You request an incremental authorization of 50.00 for the dinner.
- The customer decides to stay an extra night. You request an incremental authorization of 200.00 for the additional night.
- The customer uses items from the mini-bar. The cost of the mini-bar items is 50.00. You request an incremental authorization of 50.00.
- When the customer checks out, they sign a receipt for 700.00, which is the total of all costs incurred.
- You request a capture for 700.00.
Pre-Authorizations
A pre-authorization enables you to authorize a payment when the final amount is
unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant
transactions.
For a pre-authorization:
- The authorization amount must be greater than zero.
- The authorization must be submitted for capture within 30 calendar days of its request.
- When you do not capture the authorization, you must reverse it.In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed.In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.
- Chargeback protection is in effect for 30 days after the authorization.
Payment Network Token Authorizations
You can integrate authorizations with payment network tokens into your existing order
management system. For an incremental authorization, you do not need to include any
payment network tokenization fields in the authorization request because
Cybersource
obtains the payment network tokenization information from the
original authorization request. Authorization Workflow
This image and description show the authorization workflow:
- The customer purchases goods or services from the merchant using a payment card.
- You send an authorization request over secure internet connection toCybersource. 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.
- Cybersourcevalidates the order information then contacts your payment processor and requests authorization.
- 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 Discoverand American Express, act as their own issuing banks.
- 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 toCybersource.
- If the issuing bank denies the request, it returns an authorization denial toCybersource.
- Cybersourceruns 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.
Partial Authorizations
All debit and prepaid card processors as well as a limited number of credit card processors
support partial authorizations when dual-message processing is in place.
When partial authorization is enabled, the issuing financial institution can approve a
partial amount when the balance on the card is less than the requested amount. When a partial
amount is authorized, the capture is not processed. The merchant can then use a second card to
cover the balance, adjust the total cost, or void the transaction.
Single-Message Processing
Single-message processing treats the
authorization and capture as a single transaction. There are important differences between dual-message processing and single-message
processing:
- Single-message processing treats the request as a full-financial transaction, and with a successful transaction, funds are immediately transferred from the customer account to the merchant account.
- Authorization and capture amounts must be the same.
- Some features cannot be used with single-message processing.
Authorization Reversals
The authorization reversal service releases the hold that an authorization placed on a
customer’s payment card funds.
Each card-issuing financial institution has its own rules for deciding whether an
authorization reversal succeeds or fails. When a reversal fails, contact the card-issuing
financial institution to learn whether there is a different way to reverse the
authorization.
If your processor supports authorization reversal after void (ARAV),
you can reverse an authorization after you void the associated capture. If your processor does
not support ARAV, you can use the authorization reversal service only for an authorization
that has not been captured and settled.
An authorization reversal is a follow-on transaction that uses the request ID returned from
an authorization. The main purpose of a follow-on transaction is to link two transactions. The
request ID links the follow-on transaction to the original transaction. The authorization
request ID is used to look up the customer’s billing and account information in the
Cybersource
database. You are not required to include those fields in the full
authorization reversal request. The original transaction and follow-on transaction are linked
in the database and in the
Business Center
.For processors that support debit cards and prepaid cards, the full
authorization reversal service works for debit cards and prepaid cards in addition to credit
cards.
IMPORTANT
You cannot perform an authorization reversal if a transaction is in a
review state, which can occur if you use a fraud management service. You must reject the
transaction prior to authorization reversal. For more information, see the fraud management
documentation in
the
Business Center
.Automatic Partial Authorization Reversals
Automatic partial authorization reversals are supported for:
- Credit cards
- Debit cards and prepaid cards.
- Quasi-cash.
If the capture amount is less than the authorization amount,
Cybersource
automatically
performs a partial authorization reversal before it sends the capture request to the
processor. The results of a successful partial authorization reversal are:- The capture amount matches the new authorization amount at the payment card company.
- The hold on the unused credit card funds might be released. The issuing bank decides whether or not to release the hold on unused funds.Not all issuers act on a request for a partial authorization reversal. Therefore,Cybersourcecannot guarantee that the funds will be released.
Captures
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.
IMPORTANT
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.
- The merchant sends a request for a capture toCybersource.
- For online captures,Cybersourcevalidates the order information then sends an online capture to the payment processor.For offline captures,Cybersourcestores the capture request in a batch file and sends the batch file to the payment processor after midnight.
- The processor validates the request and forwards it to the issuing bank.
- The issuing bank transfers funds to the acquiring bank.
IMPORTANT
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.Credits
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.
WARNING
You should carefully control access to the credit service. Do not request
this service directly from your customer interface. Instead, incorporate this service as part
of your customer service process. This process reduces the potential for fraudulent
transactions.
There are two basic types of credits:
refunds
and stand-alone credits.Refunds
Refunds
Refunds, also known as
, use the capture
request ID to link the refund to a specific transaction. follow-on credits
This request ID is returned during the capture request (also known as a
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 credit request.settlement
) and is used in all subsequent refunds associated with the original
capture.However, when you combine a request for a refund 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, refunds must be requested within 180 days of a settlement. You can request multiple refunds against a single capture or sale transaction as
long as the total amount does not exceed the original purchase amount. To perform
multiple refunds, 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.
Credit Workflow
The credit workflow begins when you send a request for a credit.
A credit does 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.- The merchant sends a request for a credit toCybersource.
- For online credits,Cybersourcevalidates the order information then sends an online credit to the payment processor.For offline credits,Cybersourcestores the credit request in a batch file and sends the batch file to the payment processor after midnight.
- The processor validates the request and forwards it to the acquiring bank.
- The acquiring bank transfers funds to the issuing bank.
Voids
A void cancels a capture or credit request that was submitted but not yet processed by the
processor.
Capture and credit requests are usually submitted once a day. 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.
Payment Features
You can apply features to different payment services to enhance the customer payment
processing experience. This section includes an overview of these features:
Debit and Prepaid Card Payments
Debit cards are linked to a cardholder's checking account. A merchant who accepts the debit
card can deduct funds directly from the linked cardholder's account.
You can process debit cards using these services:
- Credit card services
- PIN debit services
- Partial authorizations, which are a special feature available for debit cards
- Balance inquiries, which are a special feature available for debit cards
Related Information
- See Standard Payment Processing for information that shows you how to use credit card services.
- See Debit and Prepaid Card Processing for information that shows you how to process authorizations that use a debit or prepaid card.
Airline Data
Airline data processing goes beyond basic payment transactions by allowing you to process
specific travel data. This requires you to submit additional information, such as:
- Carrier
- Departure Date
- Destination Airport
- Purchase Date
- Originating Airport
- Ticket Class
- Trip Legs
Requirement
When you are ready to go live with airline data processing, contact
Cybersource
Customer
Support to have your account configured to process airline data. If your account is not
enabled, and you try to send airline transactions, you will receive an error for invalid
data.Related Information
- See Airline Data Processing for information that shows you how to process payments that include airline data.
Cybersource Airline Data Processing
Cybersource
Airline Data ProcessingCybersource
does not store airline data. Instead, it functions as a
pass-through service for the data. Cybersource
enforces only the minimal
level of field validation.When you request an airline service,
Cybersource
responds with certain
fields and values to indicate whether the airline data was processed. The response
fields for each service are:- Authorization:processingInformation.enhancedDataEnabled
- Capture:processingInformation.enhancedDataEnabled
- Credit:processingInformation.enhancedDataEnabled
The possible values for the response fields are:
- Y: the airline data was included in the request to the processor.
- N: the airline data was not included in the request to the processor.
Cybersource
temporarily disables your account's airline
data processing capability and contacts you if your airline data transactions produce
batching errors when the information is sent to the processor. If this happens, your
request is not rejected, but you receive one of the above listed fields with the
N
value in the response indicating that airline data in the request
has been ignored and not sent to the processor. Airline Data Reference Information
This section contains reference information that is useful when using Airline Data.
Airline Document Type Codes
To indicate the purpose of a purchase, set the
travelInformation.transit.airline.documentType
field to a value listed in the Code column.Code | Description |
---|---|
01 | Passenger ticket |
02 | Additional collection |
03 | Excess baggage |
04 | Miscellaneous charge order (MCO) or
prepaid ticket authorization |
05 | Special service ticket |
06 | Supported refund |
07 | Unsupported refund |
08 | Lost ticket application |
09 | Tour order voucher |
10 | Ticket by mail |
11 | Undercharge adjustment |
12 | Group ticket |
13 | Exchange adjustment |
14 | SPD or air freight |
15 | In-flight adjustment |
16 | Agency passenger ticket |
17 | Agency tour order or voucher |
18 | Agency miscellaneous charge order
(MCO) |
19 | Agency exchange order |
20 | Agency group ticket |
21 | Debit adjustment for duplicate
refund or use |
22 | In-flight merchandise order |
23 | Catalogue merchandise order |
24 | In-flight phone charges |
25 | Frequent flyer fee or
purchase |
26 | Kennel charge |
27 | Animal transportation charge |
28 | Firearms case |
29 | Upgrade charge |
30 | Credit for unused
transportation |
31 | Credit for class of service
adjustment |
32 | Credit for denied boarding |
33 | Credit for miscellaneous
refund |
34 | Credit for lost ticket
refund |
35 | Credit for exchange refund |
36 | Credit for overcharge
adjustment |
37 | Credit for multiple Unused
tickets |
38 | Exchange order |
39 | Self-service ticket |
41 | In-flight duty-free purchase |
42 | Senior citizen discount
booklets |
43 | Club membership fee |
44 | Coupon book |
45 | In-flight charges |
46 | Tour deposit |
47 | Frequent flyer overnight delivery
charge |
48 | Frequent flyer fulfillment |
49 | Small package delivery |
50 | Vendor sale |
51 | Miscellaneous taxes or fees |
52 | Travel agency fee |
60 | Vendor refund or credit |
64 | Duty free sale |
65 | Preferred seat upgrade |
66 | Cabin upgrade |
67 | Lounge or club access or day
pass |
68 | Agent assisted reservation or
ticketing fee |
69 | Ticket change or cancel fee |
70 | Trip insurance |
71 | Unaccompanied minor |
72 | Standby fee |
73 | Curbside baggage |
74 | In-flight medical equipment |
75 | Ticket or pass print fee |
76 | Checked sporting or special
equipment |
77 | Dry ice fee |
78 | Mail or postage fee |
79 | Club membership fee or temporary
trial |
80 | Frequent flyer activation or
reinstatement |
81 | Gift certificate |
82 | Onboard or in-flight prepaid
voucher |
83 | Optional services fee |
84 | Advance purchase for excess
baggage |
85 | Advance purchase for preferred seat
upgrade |
86 | Advance purchase for cabin
upgrade |
87 | Advance purchase for optional
services |
88 | Wi-Fi |
89 | Packages |
90 | In-flight entertainment or internet
access |
91 | Overweight bag fee |
92 | Sleep sets |
93 | Special purchase fee |
Ancillary Service Category Codes
To indicate the service provided in an ancillary purchase, set the
travelInformation.transit.airline.ancillaryInformation.service[].categoryCode
and travelInformation.transit.airline.ancillaryInformation.service[].subCategoryCode
fields to a value listed in the Ancillary Service Category Code column.Ancillary Service Category
Codes | Description |
---|---|
BF | Bundled service |
BG | Baggage fee |
CF | Change fee |
CG | Cargo |
CO | Carbon offset |
FF | Frequent flyer |
GF | Gift card |
GT | Ground transport |
IE | In-flight entertainment |
LG | Lounge |
MD | Medical |
ML | Meal or beverage |
OT | Other |
PA | Passenger assist fee |
PT | Pets |
SA | Seat fees |
SB | Standby |
SF | Service fee |
ST | Store |
TS | Travel service |
UN | Unaccompanied travel |
UP | Upgrades |
WI | Wi-Fi |
Payer Authentication
Payer authentication is run before a transaction is submitted for authorization. Most of
the time payer authentication is bundled with authorization so that after payer
authentication happens, the transaction is automatically submitted for authorization.
Payer authentication and authorization can be configured to occur as separate
operations. This section shows you how to run payer authentication as a separate process
and pass the payer authentication data when seeking authorization for a transaction.
Payer authentication consists of a two-step verification process that adds an extra layer
of fraud protection during the payment process. During transactions, the transaction
device, location, past purchasing habits, and other factors are analyzed for indications
of fraud. This process collects customer data during the transaction from at least two
of these three categories:
- Something you have: A payment card or a payment card number
- Something you know: A password or pin
- Something you are: Facial recognition or fingerprint
Each of these payment card companies has its own payer authentication product:
- Discover: ProtectBuy
- JCB: J/Secure
- Mastercard: Identity Check
- Visa: Visa Secure
Payer authentication can be used to satisfy the Strong Customer Authentication (SCA)
requirement of the Payment Services Directive (PSD2). SCA applies to the European
Economic Area (EEA) and the United Kingdom. SCA requires banks to perform additional
checks when customers make payments to confirm their identity.
Related Information
- See the Payer Authentication Developer Guide for more information about payer authentication.
- See Payer Authentication Processing for information about how to process payments with payer authentication.
Relaxed Requirements for Address Data and Expiration Date in Payment Transactions
With relaxed requirements for address data and the expiration date, not all standard
payment request fields are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required.
Related Information
- See Relaxed Requirements for Address Data and Expiration Date in Payment Transactions for information about how to process payments with relaxed requirements for address data and expiration date.
Introduction to Credentialed Transactions
Credentialed transactions are transactions that involve either storing a customer's
payment credentials for future transactions or using a customer's already stored payment
credentials. When processing a credentialed transaction, you must indicate the type of
credentialed transaction and the reason for the transaction. Credentialed transactions
are also known as
credential-on-file
(COF) transactions.There are several types of credentialed transactions:
- Customer-Initiated Transactions (CITs):Any transaction a customer is actively participating in such as making a card-present payment, completing an online checkout, or by using a stored credential. CIT transactions can store the customer's credentials in your system for future CITs or merchant-initiated transactions.
- Merchant-Initiated Transactions (MITs):Any transaction a merchant initiates without the customer's participation such as an industry practice transaction or a standing instruction transaction.
- Industry Practice Transactions:MITs that are performed as subsequent transactions to a CIT because the initial transaction could not be completed in one transaction. Not every industry practice transaction involves a stored credential. If a stored credential is used only for one transaction, that transaction is not considered a credentialed transaction.
- Standing Instruction Transactions:MITs that are performed to follow agreed-upon instructions from the customer for the provision of goods and services.
Supported Services
These are the supported merchant-initiated services:
- Installment Transactions
- Mastercard Standing Order Transactions
- Mastercard Subscription Transactions
- Reauthorization
- Recurring Transactions
- Unscheduled Credentials-on-File Transactions
The service determines the reason for the credentialed transaction.
Token Management Service
The
Token Management Service
(TMS
) enables you to replace personally
identifiable information (PII), such as the primary account numbers (PANs), with
unique tokens. These tokens do not include the PII data, but act as a placeholder
for the personal information that would otherwise need to be shared. By using
tokens, businesses can provide a secure payment experience, reduce the risk of
fraud, and comply with industry consumer security regulations such as PCI-DSS.TMS
links tokens across service providers, payment types, and channels
for sellers, acquirers, and technology partners. TMS
tokenizes, securely stores, and manages the primary account number (PAN), the
payment card expiration date, electronic check
details,
and customer data. TMS
also enables you
to create a network token of a customer's payment card.IMPORTANT
Due to mandates from the Reserve
Bank of India, Indian merchants cannot store PANs. Use network tokenization instead.
You can manage sensitive data securely by
creating, retrieving, updating, and deleting tokens through the TMS API.
TMS
simplifies your PCI DSS compliance. TMS
passes tokens
back to you that represent this data. You then store these tokens in your
environment and databases instead of storing customer payment
details.TMS
protects sensitive payment information through tokenization and
secures and manages customer data using these token types:- Customer tokens
- Instrument identifier tokens
- Payment instrument tokens
- Shipping address tokens
TMS
tokens can be used individually, or they can
be associated with one customer token:Figure:
TMS
Token TypesRelated Information
- See thefor more information about theToken Management ServiceDeveloper GuideTMS.
- See Token Management Service Processing for information that shows you how to process payments using theTMS.
Visa Bill Payments
Visa provides a Bill Payment program that enables customers to use their Visa cards to
pay their bills. When you participate in this program, Visa requests that you flag the
bill payments and credits so they can be easily identified.
The bill payment indicator is accepted no matter which processor you are using, do not use this indicator if you have not signed up with Visa to participate in the program.
IMPORTANT
This feature is not the same as the Visa Consumer Bill Payment Service.
Supported Services
You can process Visa Bill Payments using these services:
- Authorization
- Credit
Fields Specific to this Use Case
Authorization:
include this field in a standard authorization when processing
a Visa Bill Payment: - processingInformation.authorizationOptions.billPayment
Credit:
include this field in a standard credit when processing a Visa Bill
Payment: Endpoints
Authorization:
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsCredit:
Production:
POST
https://api.cybersource.com
/pts/v2/credits/Test:
POST
https://apitest.cybersource.com
/pts/v2/credits/Requirement
Before you process Visa Bill Payments, you must sign up with Visa to participate in the program.
Related Information
- See Visa Bill Payments Processing for information that shows you how to process Visa Bill Payment transactions.
Visa Consumer Bill Payments
The Visa Consumer Bill Payment Service (CBPS) is an optional service that enables you to
provide bill payment services to consumers using a Visa card. Cardholders can pay one or
more of their bills in one transaction using a third-party intermediary rather than
paying each bill separately. When you request a Visa CBPS authorization, you must
include the
processingInformation.businessApplicationId
field set to
CB
.IMPORTANT
This feature is not the same as Visa Bill Payments.
Supported Service
You can process Visa Consumer Bill Payments using the authorization service.
Requirements
IMPORTANT
As a Visa CBPS provider you must comply with all Visa rules. For the Visa CBPS rules,
see Rule ID# 0030635 of the Visa Rules "Acquirer Responsibilities Related to
Consumer Bill Payment Service Providers" at visa-rules-public.pdf.
Before you process Visa CBPS payments, you must:
- Contact your acquirer to register your account for the Visa Consumer Bill Pay Service.
- ContactCybersourcecustomer support to have your account configured for this feature.
Related Information
- See Visa Consumer Bill Payment Processing for a instructions that show you how to process a Visa Consumer Bill Payment.
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.
IMPORTANT
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.
- REST API test endpoint:POSThttps://apitest.cybersource.com/pts/v2/payments
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.
IMPORTANT
The test card numbers that are provided are
formatted with Xs for zeroes in the card number. When testing with the card numbers, 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—1354 1234 5678 911
- 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: REST API Testing Guide
.
Test American Express Card Verification
Before using CVN with American Express, it is strongly recommended that you follow these
steps:
- Contact customer support to have your account configured for CVN. Until you do this, you will receive a1in theprocessorInformation.cardVerification.resultCoderesponse field.
- 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 Authorizations
This section provides the information you need in order to process a basic
authorization.
Merchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsDeclined Authorizations
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:
- paymentInsightsInformation.responseInsights.category
- paymentInsightsInformation.responseInsights.categoryCode
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
- 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
Use these required fields for processing a basic authorization.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
REST Interactive Example: Processing a Basic
Authorization
Simple Authorization(Internet)
Live Console URL: index.html#payments_payments_process-a-payment
REST Example: Processing a Basic Authorization
Request
{ "orderInformation": { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Kyong-Jin", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } } }
Response to a Successful Request
{ "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6461731521426399003473" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/captures" } }, "clientReferenceInformation" : { "code" : "1646173152047" }, "id" : "6461731521426399003473", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "100.00", "currency" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "paymentInsightsInformation" : { "responseInsights" : { "categoryCode" : "01" } }, "processorInformation" : { "systemTraceAuditNumber" : "862481", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6461731521426399003473", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-01T22:19:12Z" }
Response to a Declined Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_ERROR", "message": "Invalid account" }, "id": "6583553837826789303954","paymentInsightsInformation": { "responseInsights": { "categoryCode": "01", "category": "ISSUER_WILL_NEVER_APPROVE" } },"pointOfSaleInformation": { "amexCapnData": "1009S0600100" }, "processorInformation": { "systemTraceAuditNumber": "004544", "merchantNumber": "1231231222", "networkTransactionId": "431736869536459", "transactionId": "431736869536459", "responseCode": "111", "avs": { "code": "Y", "codeRaw": "Y" } }, "status": "DECLINED" }
Authorizations 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
orderInformation.amountDetails.totalAmount
field, which is
included in a basic authorization, is substituted with one or more line items that
are included in a
.lineItem[]
arrayFields Specific to this Use Case
These
fields
are required for each line item that you use:- orderInformation.lineItems[].unitPrice
- orderInformation.lineItems[].quantity
- orderInformation.lineItems[].productCode
- orderInformation.lineItems[].productSku
- Optional whenitem_#_productCodeis set todefault,shipping_only,handling_only, orshipping_and_handling
- orderInformation.lineItems[].productName
- Optional whenitem_#_productCodeis set todefault,shipping_only,handling_only, orshipping_and_handling
At a minimum, you must include the
orderInformation.lineItems[].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:- orderInformation.lineItems[].productCode:default
- orderInformation.lineItems[].quantity:1
For example, these three line items are valid.
"orderInformation": { "lineItems": [ { "unitPrice": "10.00" }, { "unitPrice": "5.99", "quantity": "3", "productCode": "shipping_only" }, { "unitPrice": "29.99", "quantity": "3", "productCode": "electronic_good", "productSku": "12384569", "productName": "receiver" } ] }
Merchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing an Authorization with Line Items
Use these required fields for processing an authorization that includes line items.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
REST Example: Processing an Authorization with Line Items
Request
{ "currencyConversion": { "indicator": "Y" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "currency": "USD", "exchangeRate": ".91", "originalAmount": "107.33", "originalCurrency": "eur" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com" }, "lineItems": [ { "unitPrice": "10.00" }, { "unitPrice": "5.99", "quantity": "3", "productCode": "shipping_only" }, { "unitPrice": "29.99", "quantity": "3", "productCode": "electronic_good", "productSku": "12384569", "productName": "receiver" } ] } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6482385519226028804003/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6482385519226028804003" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6482385519226028804003/captures" } }, "clientReferenceInformation": { "code": "1648238551902" }, "id": "6482385519226028804003", "orderInformation": { "amountDetails": { "authorizedAmount": "117.94", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "systemTraceAuditNumber": "191521", "approvalCode": "831000", "merchantAdvice": { "code": "01", "codeRaw": "M001" }, "responseDetails": "ABC", "networkTransactionId": "016153570198200", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "transactionId": "016153570198200", "responseCode": "00", "avs": { "code": "Y", "codeRaw": "Y" } }, "reconciliationId": "6482385519226028804003", "status": "AUTHORIZED", "submitTimeUtc": "2022-03-25T20:02:32Z" }
Authorizations with Payment Network Tokens
This section shows you how to successfully process an authorization with payment network
tokens.
IMPORTANT
Due to mandates from the Reserve Bank of India, Indian merchants cannot
store personal account numbers (PAN). Use network tokens instead. For more information
on network tokens, see Network Tokenization in
the .
Token Management Service
Developer GuideMerchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizations with Payment Network Tokens
Use these required fields for processing an authorization with payment network tokens.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- paymentinformation.tokenizedCard.cryptogram
- paymentinformation.tokenizedCard.expirationMonth
- paymentinformation.tokenizedCard.expirationYear
Related Information
Optional Fields for Authorizations with Payment Network Tokens
You can use these optional fields to include additional information when processing
an authorization with a payment network token.
- clientReferenceInformation.code
- consumerAuthenticationInformation.cavv
- For 3-D Secure in-app transactions for Visaand JCB, set this field to the 3-D Secure cryptogram. Otherwise, set to the network token cryptogram.
- consumerAuthenticationInformation.ucafAuthenticationData
- For Mastercard requests using 3-D Secure, set this field to the Identity Check cryptogram.
- consumerAuthenticationInformation.ucafCollectionIndicator
- For Mastercard requests using 3-D Secure, set the value to2.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.country
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- orderInformation.billTo.locality
- orderInformation.billTo.postalCode
- Required only for transactions in the US and Canada.
- orderInformation.billTo.administrativeArea
- Required only for transactions in the US and Canada.
- processingInformation.commerceIndicator
- paymentInformation.tokenizedCard.cardType
- It is strongly recommended that you send the card type even if it is optional for your processor. Omitting the card type can cause the transaction to be processed with the wrong card type.
- paymentInformation.tokenizedCard.cryptogram
- paymentInformation.tokenizedCard.expirationMonth
- Set to the token expiration month that you received from the token service provider.
- paymentInformation.tokenizedCard.expirationYear
- Set to the token expiration year that you received from the token service provider.
- paymentInformation.tokenizedCard.number
- Set to the token value that you received from the token service provider.
- paymentInformation.tokenizedCard.requestorId
- paymentInformation.tokenizedCard.transactionType
Related Information
REST Example: Authorizations with Payment Network Tokens
Request
{ "orderInformation" : { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Kyong-Jin", "email": "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100", "currency" : "USD" } }, "paymentInformation" : { "tokenizedCard" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "transactionType" : "1", "cryptogram" : "qE5juRwDzAUFBAkEHuWW9PiBkWv=" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6838294805206235603954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/captures" } }, "clientReferenceInformation": { "code": "1683829480593" }, "id": "6838294805206235603954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "1" } }, "reconciliationId": "60332034UHI9PRJ0", "status": "AUTHORIZED", "submitTimeUtc": "2023-05-11T18:24:40Z" }
Authorizations with a Card Verification Number
This section shows you how to process an authorization with a Card Verification Number
(CVN).
CVN Results
The response includes a raw response code and a mapped response code:
- The raw response code is the value returned by the processor. This value is returned in theprocessorInformation.cardVerification.resultCodeRawfield. Use this value only for debugging purposes; do not use it to determine the card verification response.
- The mapped response code is the pre-defined value that corresponds to the raw response code. This value is returned in theprocessorInformation.cardVerification.resultCodefield.
Even when the CVN does not match the expected value, the issuing bank might still authorize the transaction. You will receive a CVN decline, but you can still capture the transaction because it has been authorized by the bank. However, you must review the order to ensure that it is legitimate.
Settling authorizations that fail the CVN check might have an impact on the fees charged by your bank. Contact your bank for details about how card verification management might affect your discount rate.
When a CVN decline is received for the authorization in a sale request, the capture request is not processed unless you set the
processingInformation.authorizationOptions.ignoreCvResult
field to true
.- CVN Results for American Express
- A value of1in theprocessorInformation.cardVerification.resultCodefield indicates that your account is not configured to use card verification. Contact customer support to have your account enabled for this feature.
- CVN Results for Discover
- CVN results can be returned for any of the card types on the Discover Network. When CVN results are returned to you, it is your responsibility to decide whether or not to accept the transaction.
- CVN Results for Visa and Mastercard
- A CVN code ofDorNcauses the request to be declined with a reason code value of230. You can still capture the transaction, but you must review the order to ensure that it is legitimate.Cybersource, not the issuer, assigns the CVN decline to the authorization. You can capture any authorization that has a valid authorization code from the issuer, even when the request receives a CVN decline.When the issuer does not authorize the transaction and the CVN does not match, the request is declined because the card is refused. You cannot capture the transaction.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing an Authorization with a Card Verification Number
Use these required fields for processing an authorization that includes a Card Verification
Number (CVN).
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
Optional Fields for Processing an Authorization with a Card Verification Number
You can use these optional fields to include additional information when processing
an authorization with a card verification number.
REST Example: Processing an Authorization with a Card Verification Number
Request
{ "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031", "type": "001", "securityCode": "999" } }, "orderInformation": { "amountDetails": { "totalAmount": "49.95", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1295 Charleston Rd.", "locality": "Mountain View", "administrativeArea": "CA", "postalCode": "94043", "country": "US", "email": "jdoe@example.com", "phoneNumber": "650-965-6000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6554147587216874903954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6554147587216874903954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6554147587216874903954/captures" } }, "clientReferenceInformation": { "code": "1655414758839" }, "id": "6554147587216874903954", "orderInformation": { "amountDetails": { "authorizedAmount": "49.95", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67546603C43Z6JWN", "status": "AUTHORIZED", "submitTimeUtc": "2022-06-16T21:25:58Z" }
Authorizations with Strong Customer Authentication Exemption
This section shows you how to process an authorization with a strong customer authentication
(SCA) exemption.
You can use SCA exemptions to streamline the payment process. SCA exemptions are part of the
European second Payment Services Directive (PSD2) and allow certain types of low-risk
transactions to bypass additional authentication steps while still remaining compliant with
PSD2. You can choose which exemption can be applied to a transaction, but the card-issuing
bank actually grants an SCA exemption during card authentication.
You can process an authorization with two types of SCA exemptions:
- Exemption on Authorization: Send an authorization without payer authentication and request an SCA exemption on the authorization. If it is not approved, you may be required to request further authentication upon retry.
- Exemption on Authentication: Request an SCA exemption during payer authentication and if successful, send an authorization including the SCA exemption details.
Depending on your processor, use one of these exemption fields:
IMPORTANT
If you send more than one SCA exemption field with a single
authentication, the transaction is denied.
- Authentication Outage: Payer authentication is not available for this transaction due to a system outage.
- B2B Corporate Card: Payment cards specifically for business-to-business transactions are exempt.
- Delegated Authentication: Payer authentication was performed outside of the authorization workflow.
- Follow-On Installment Payment: Installment payments of a fixed amount are exempt after the first transaction.
- Follow-On Recurring Payment: Recurring payments of a fixed amount are exempt after the first transaction.
- Low Risk: The average fraud levels associated with this transaction are considered low.
- Low Value: The transaction value does not warrant SCA.
- Merchant Initiated Transactions: As follow-on transactions, merchant-initiated transactions are exempt.
- Stored Credential Transaction: Credentials are authenticated before storing, so stored credential transactions are exempt.
- Trusted Merchant: Merchants registered as trusted beneficiaries.
Fields Specific to the Strong Customer Authentication Exemptions
Use one of these fields to request an SCA exemption:
- consumerAuthenticationInformation. strongAuthentication. secureCorporatePaymentIndicator
- Exemption type: B2B Corporate Card Transaction
- Value:1
- consumerAuthenticationInformation. strongAuthentication. delegatedAuthenticationExemptionIndicator
- Exemption type: Delegated Authentication
- Value:1
- processingInformation. commerceIndicator
- Exemption type: Follow-On Installment
- Value:installment
- consumerAuthenticationInformation. strongAuthentication. riskAnalysisExemptionIndicator
- Exemption type: Low Risk Transaction
- Value:1
- consumerAuthenticationInformation. strongAuthentication. lowValueExemptionIndicator
- Exemption type: Low Value Transaction
- Value:1
- processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction.reason
- Exemption type: Merchant Initiated Transaction
- Value: See field description.
- processingInformation. authorizationOptions.initiator. storedCredentialUsed
- Exemption type: Stored Credential Transaction
- Value:1
- consumerAuthenticationInformation. strongAuthentication. trustedMerchantExemptionIndicator
- Exemption type: Trusted Merchant Transaction
- Value:1
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing an Authorization with an SCA Exemption
Use these required fields for processing an authorization that includes an SCA exemption.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
REST Example: Processing an Authorization with an SCA Exemption for Low-Value
Transactions
Request
{ "consumerAutenticationInformation" : { "strongAuthentication" : { "lowValueExemptionIndicator" : "1" } }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Kim", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "Kyong-Jin", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "eur" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6709780221406171803955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6709780221406171803955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6709780221406171803955/captures" } }, "clientReferenceInformation": { "code": "1670978022258" }, "id": "6709780221406171803955", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "eur" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "123456" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62859554PBDEMI43", "status": "AUTHORIZED", "submitTimeUtc": "2022-12-14T00:33:42Z" }
Zero Amount Authorizations
Zero Amount Authorizations
This section provides the information that you need in order to process a zero amount authorization.
Authorizing
a payment for a zero amount shows whether a payment card account is valid and whether the card is lost or stolen. You cannot capture a zero amount authorization.
Processor-Specific Information
- FDC Nashville Global
- AVS and CVN are supported. CVN is not supported for American Express.
- Card types: American Express, Diners Club, Discover, Mastercard, Visa
- Discover and Diners Club—only USD is supported for zero amount authorizations.
- American Express, Mastercard, and Visa—all currencies that are supported for standard authorizations are also supported for zero amount authorizations.
Merchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing a Zero Amount Authorization
a Zero Amount Authorization
Use these required fields for processing
a zero amount authorization
.IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set this value to0.
Related Information
REST Example: Processing a Zero Amount Authorization
a Zero Amount Authorization
Request
{ "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Kim", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "Kyong-Jin", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "0.00", "currency" : "usd" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12" } } }
Response to a Successful Request
{ "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6461731521426399003473" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/captures" } }, "clientReferenceInformation" : { "code" : "1646173152047" }, "id" : "6461731521426399003473", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "0", "currency" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "processorInformation" : { "systemTraceAuditNumber" : "862481", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6461731521426399003473", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-01T22:19:12Z" }
Pre-Authorizations
This section provides the information you need in order to process a pre-authorization.
A pre-authorization enables you to authorize a payment when the final amount is
unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant
transactions.
For a pre-authorization:
- The authorization amount must be greater than zero.
- The authorization must be submitted for capture within 30 calendar days of its request.
- When you do not capture the authorization, you must reverse it.In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed.In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.
- Chargeback protection is in effect for 30 days after the authorization.
Merchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for a Pre-Authorization
Use these required fields for processing a pre-authorization.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
REST Example: Processing a Pre-Authorization
Request
{ "orderInformation": { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Kyong-Jin", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } } }
Response to a Successful Request
{ "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6461731521426399003473" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6461731521426399003473/captures" } }, "clientReferenceInformation" : { "code" : "1646173152047" }, "id" : "6461731521426399003473", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "100.00", "currency" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "paymentInsightsInformation" : { "responseInsights" : { "categoryCode" : "01" } }, "processorInformation" : { "systemTraceAuditNumber" : "862481", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6461731521426399003473", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-01T22:19:12Z" }
Response to a Declined Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_ERROR", "message": "Invalid account" }, "id": "6583553837826789303954","paymentInsightsInformation": { "responseInsights": { "categoryCode": "01", "category": "ISSUER_WILL_NEVER_APPROVE" } },"pointOfSaleInformation": { "amexCapnData": "1009S0600100" }, "processorInformation": { "systemTraceAuditNumber": "004544", "merchantNumber": "1231231222", "networkTransactionId": "431736869536459", "transactionId": "431736869536459", "responseCode": "111", "avs": { "code": "Y", "codeRaw": "Y" } }, "status": "DECLINED" }
Final Authorization Indicator
The purpose of this feature is to ensure that unused funds are reversed, so that
customer’s funds are available again when an order is not fulfilled.
For an authorization with an amount greater than zero, indicate whether the authorization
is a final authorization, a pre-authorization, or an undefined authorization.
You can set a default authorization type in your account. To set the default
authorization type in your account, contact customer support.
Chargeback protection is in effect for seven days after the authorization.
Supported Services
Services
- Authorization
- Incremental authorization
Supported Card Types
- Maestro (International)
- Maestro (UK Domestic)
- Mastercard
Requirements for Final Authorizations
For a final authorization:
- The authorization amount must be greater than zero.
- The authorization amount must be the final amount that the customer agrees to pay.
- The authorization should not be cancelled after it is approved except when a system failure occurs.
- The authorization must be submitted for capture within seven calendar days of its request.
- The capture amount and currency must be the same as the authorization amount and currency.
Pre-Authorizations
A pre-authorization enables you to authorize a payment when the final amount is
unknown. It is typically used for lodging, auto rental, e-commerce, and restaurant
transactions.
For a pre-authorization:
- The authorization amount must be greater than zero.
- The authorization must be submitted for capture within 30 calendar days of its request.
- When you do not capture the authorization, you must reverse it.In the U.S., Canada, Latin America, and Asia Pacific, Mastercard charges an additional fee for a pre-authorization that is not captured and not reversed.In Europe, Russia, Middle East, and Africa, Mastercard charges fees for all pre-authorizations.
- Chargeback protection is in effect for 30 days after the authorization.
Unmarked Authorizations
An authorization is unmarked when the default authorization type is not set in your
account and you do not include the
authIndicator
field in the
authorization request. To set the default authorization type in your account, contact
customer support.Unmarked authorizations are supported only in the US, Canada, Latin America, and Asia
Pacific. They are not supported in Europe, Russia, Middle East, and Africa.
Cybersource
does not set a mark or indicator for the type of authorization in the request
that is sent to the processor.IMPORTANT
Your acquirer processes an unmarked authorization as a final
authorization, a preauthorization, or an undefined authorization. Contact your acquirer
to learn how they process unmarked authorizations.
Requirements for Unmarked Authorizations
For an unmarked authorization:
- The authorization amount must be greater than zero.
- The authorization amount can be different from the final transaction amount.
Undefined Authorizations
An authorization is undefined when you set the default authorization type in your account
to undefined and do not include the
authIndicator
field in the
authorization request. To set the default authorization type in your account, contact
customer support.Undefined authorizations are supported only in the U.S., Canada, Latin America, and Asia Pacific.
They are not supported in Europe, Russia, Middle East, and Africa.
Chargeback protection is in effect for seven days after the authorization.
Requirements for Undefined Authorizations
For an undefined authorization:
- The authorization amount must be greater than zero.
- The authorization amount can be different from the final transaction amount.
- The authorization should not be cancelled after it is approved except when a system failure occurs.
- The authorization must be submitted for capture within seven calendar days of its request.
- When you do not capture the authorization, you must reverse it; otherwise, Mastercard charges an additional fee for the transaction.
Required Fields for Final Authorizations
Use these required fields for final authorizations and preauthorizations.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value to0for preauthorizations, or to1for final authorizations.Do not include this field for unmarked or undefined authorizations.
REST Example: Final Authorizations
Request
{ "orderInformation" : { "billTo" : { "firstName" : "RTS", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "country" : "US", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "usd" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "type" : "001" } }, "processingInformation" : { "authorizationOptions" : { "authIndicator" : "1" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6910040807416719003955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6910040807416719003955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6910040807416719003955/captures" } }, "clientReferenceInformation": { "code": "1691004080800" }, "id": "6910040807416719003955", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "usd" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67628631TKRG2OVE", "status": "AUTHORIZED", "submitTimeUtc": "2023-08-02T19:21:20Z" }
Authorization Reversal
This section provides the information about how to process an authorization reversal.
Reversing an authorization releases the hold on the customer’s payment card funds that the
issuing bank placed when processing the authorization.
For a debit card or prepaid card in which only a partial amount was approved, the amount of
the reversal must be the amount that was authorized, not the amount that was requested.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/reversalsTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/reversalsThe is the transaction ID returned in the
authorization response.
{id}
Required Fields for Processing an Authorization Reversal
- The amount of the reversal must be the same as the authorization amount that was included in the authorization response message. Do not use the amount that was requested in the authorization request message.
REST Example: Processing an Authorization Reversal
Request
{ "clientReferenceInformation": { "code": "test123" } "reversalInformation" : { "amountDetails" : { "totalAmount" : "100.00", "currency" : "USD" } } }
Response to a Successful Request
{ "_links" : { "self" : { "method" : "GET", "href" : "/pts/v2/reversals/6869460219566537303955" } }, "clientReferenceInformation" : { "code" : "RTS-Auth-Reversal" }, "id" : "6869460219566537303955", "orderInformation" : { "amountDetails" : { "currency" : "USD" } }, "processorInformation" : { "responseCode" : "200" }, "reconciliationId" : "82kBK3qDNtls", "reversalAmountDetails" : { "reversedAmount" : "100.00", "currency" : "USD" }, "status" : "REVERSED", "submitTimeUtc" : "2023-06-16T20:07:02Z" }
Time-Out Authorization Reversals
When you do not receive a response message after sending an authorization request, this
feature enables you to reverse the authorization that you requested.
IMPORTANT
Wait 60 seconds before requesting a time-out authorization
reversal.
Include the
clientReferenceInformation.transactionId
field in the original request for an
authorization. The value of the merchant transaction ID must be unique for 180 days.When the original transaction fails, the response message for the reversal request
includes these fields:
- reversalAmountDetails.originalTransactionAmount
- processorInformation.responseCode
Requirements
Unless your processor supports authorization reversal after void (ARAV), time-out
authorization reversals are supported only for authorizations that have not been
captured and settled.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/reversalsTest:
POST
https://apitest.cybersource.com
/pts/v2/reversalsRequired Fields for Processing a Time-Out Authorization
Reversal
Use these required fields for processing a time-out authorization reversal.
- Identifier that links the reversal request to the original request.
- The amount of the reversal must be the same as the authorization amount that was included in the authorization response message. Do not use the amount that was requested in the authorization request message.
Related Information
REST Example: Processing a Time-Out Authorization
Reversal
Request
{ "clientReferenceInformation": { "transactionId": "987654321" }, "reversalInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }, "reason": "testing" } }
Response to Successful Request
{ "_links" : { "self" : { "method" : "GET", "href" : "/pts/v2/reversals/6869460219566537303955" } }, "clientReferenceInformation" : { "code" : "RTS-Auth-Reversal" }, "id" : "6869460219566537303955", "orderInformation" : { "amountDetails" : { "currency" : "USD" } }, "processorInformation" : { "responseCode" : "200" }, "reconciliationId" : "82kBK3qDNtls", "reversalAmountDetails" : { "reversedAmount" : "100.00", "currency" : "USD" }, "status" : "REVERSED", "submitTimeUtc" : "2023-06-16T20:07:02Z" }=
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
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing a Sale
- Set the value totrue.
Related Information
REST Example: Processing a Sale
Request
{ "processingInformation": { "capture": true }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "RTS", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "usd" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "type" : "001 } } }
Response to a Successful Request
Most processors do not return all of the fields that are shown in this
example.
{ "_links" : { "void" : { "method" : "POST", "href" : "/pts/v2/payments/6485004068966546103093/voids" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6485004068966546103093" } }, "clientReferenceInformation" : { "code" : "RTS-Auth" }, "id" : "6485004068966546103093", "orderInformation" : { "amountDetails" : { "totalAmount" : "100.00", "authorizedAmount" : "100.00", "currency" : "usd" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "processorInformation" : { "systemTraceAuditNumber" : "841109", "approvalCode" : "831000", "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "retrievalReferenceNumber" : "208720841109", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } }, "reconciliationId" : "6485004068966546103093", "status" : "AUTHORIZED", "submitTimeUtc" : "2022-03-28T20:46:47Z" }
Sales with Payment Network Tokens
This section shows you how to successfully process a sale with payment network
tokens.
IMPORTANT
Due to mandates from the Reserve Bank of India, Indian merchants cannot
store personal account numbers (PAN). Use network tokens instead. For more information
on network tokens, see Network Tokenization in
the .
Token Management Service
Developer GuideEndpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Sales with Payment Network Tokens
Use these required fields for processing a sale with payment network tokens.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- paymentinformation.tokenizedCard.cryptogram
- paymentinformation.tokenizedCard.expirationMonth
- paymentinformation.tokenizedCard.expirationYear
- Set the value totrue.
Related Information
Optional Fields for Sales with Payment Network Tokens
You can use these optional fields to include additional information when processing a
sale with a payment network token.
- clientReferenceInformation.code
- consumerAuthenticationInformation.cavv
- For 3-D Secure in-app transactions for Visaand JCB, set this field to the 3-D Secure cryptogram. Otherwise, set to the network token cryptogram.
- consumerAuthenticationInformation.ucafAuthenticationData
- For Mastercard requests using 3-D Secure, set this field to the Identity Check cryptogram.
- consumerAuthenticationInformation.ucafCollectionIndicator
- For Mastercard requests using 3-D Secure, set the value to2.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.country
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- orderInformation.billTo.locality
- orderInformation.billTo.postalCode
- Required only for transactions in the US and Canada.
- orderInformation.billTo.administrativeArea
- Required only for transactions in the US and Canada.
- processingInformation.commerceIndicator
- paymentInformation.tokenizedCard.cardType
- It is strongly recommended that you send the card type even if it is optional for your processor. Omitting the card type can cause the transaction to be processed with the wrong card type.
- paymentInformation.tokenizedCard.cryptogram
- paymentInformation.tokenizedCard.expirationMonth
- Set to the token expiration month that you received from the token service provider.
- paymentInformation.tokenizedCard.expirationYear
- Set to the token expiration year that you received from the token service provider.
- paymentInformation.tokenizedCard.number
- Set to the token value that you received from the token service provider.
- paymentInformation.tokenizedCard.requestorId
- paymentInformation.tokenizedCard.transactionType
Related Information
REST Example: Sale with a Payment Network Token
Request
{ "orderInformation" : { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Smith", "email": "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100", "currency" : "USD" } }, "paymentInformation" : { "tokenizedCard" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12", "transactionType" : "1", "cryptogram" : "qE5juRwDzAUFBAkEHuWW9PiBkWv=" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6838294805206235603954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6838294805206235603954/captures" } }, "clientReferenceInformation": { "code": "1683829480593" }, "id": "6838294805206235603954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "1" } }, "reconciliationId": "60332034UHI9PRJ0", "status": "AUTHORIZED", "submitTimeUtc": "2023-05-11T18:24:40Z" }
Captures
This section provides the information you need in order to capture an authorized
transaction.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe is the transaction ID
returned in the authorization response.
{id}
Required Fields for Capturing an Authorization
Use these required fields for capturing an authorization.
- This field value maps from the original authorization, sale, or credit transaction.
REST Example: Capturing an Authorization
Request
{ "clientReferenceInformation": { "code": "ABC123" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6662994431376681303954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6662994431376681303954" } }, "clientReferenceInformation": { "code": "1666299443215" }, "id": "6662994431376681303954", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }, "reconciliationId": "66535942B9CGT52U", "status": "PENDING", "submitTimeUtc": "2022-10-20T20:57:23Z" }
Multiple Partial Captures
This section shows you how to process multiple partial captures for an authorization.
This feature enables you to request multiple partial captures for one authorization. A
multiple partial capture allows you to incrementally settle authorizations over time. Ensure
that the total amount of all the captures does not exceed the authorized amount.
Fields Specific to This Use Case
These API request fields and values are specific to this use case:
Limitations
Multiple partial captures are supported only for card-not-present transactions; they are not supported for card-present transactions.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe is the transaction ID
returned in the authorization response.
{id}
Required Fields for Processing Multiple Partial Captures
- Set toclientReferenceInformation.codevalue used in corresponding authorization request.
- For the final capture request, set this field andprocessingInformation.captureOptions.totalCaptureCountto the same value.
- For Visa and Mastercard, the value for this field is sent to the processor. For all card types, the value for this field is used to determine whether to initiate an automatic partial authorization reversal.
- When you do not know the total number of captures that you are going to request, set this field to at least one more than theprocessingInformation.captureOptions. captureSequenceNumberfield until you reach the final capture. For the final capture request, set this field andprocessingInformation.captureOptions. captureSequenceNumberto the same value.
- For Visa and Mastercard, the value for this field is sent to the processor. For all card types, the value for this field is used to determine whether to initiate an automatic partial authorization reversal.
Related Information
REST Example: Processing Multiple Partial Captures
Request
{ { "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "captureOptions": { "captureSequenceNumber": "2", "totalCaptureCount": "3" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6742496815656503003954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6742496815656503003954" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6742496815656503003954", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } }, "reconciliationId": "67332020GD2G1OO1", "status": "PENDING", "submitTimeUtc": "2023-01-20T21:21:21Z" }
Forced Captures
This feature allows merchants to process authorizations obtained through an organization
other than
Cybersource
. For example, a merchant might call their
processor to request a manual authorization, at which point they can request a forced
capture of the authorization.A manual authorization cannot be captured for more than the original authorization
amount, and the authorization expires after seven days.
Supported Services
- Authorization
Required Fields for Forced Captures
Use these required fields for processing forced captures.
- Set the value toverbal.
- Set this field to the manually obtained authorization code.
Related Information
REST Example: Forced Captures
Request
{ "orderInformation": { "billTo" : { "firstName" : "RTS", "lastName" : "VDP", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "country" : "US", "email" : "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } }, "processingInformation": { "authorizationOptions": { "authType": "verbal", "verbalAuthCode": "ABC123" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6915126171696653403954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6915126171696653403954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6915126171696653403954/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6915126171696653403954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "ABC123" }, "status": "AUTHORIZED", "submitTimeUtc": "2023-08-08T16:36:57Z" }
Refunds
Refunds
This section provides the information you need in order to process a
refund
, which is linked to a capture or
sale. You must request a
refund
within 180 days of the authorization. When your account is enabled for credit authorizations, also known as purchase return
authorizations,
Cybersource
authenticates the card and customer during a refund or
credit request.
Every
credit request is automatically authorized. Credit authorization results are returned in
these response fields:
- processorInformation.approvalCode
- processorInformation.networkTransactionId
- processorInformation.responseCode
When you request a void for the credit and the credit is voided. If your account is enabled
for credit authorizations, the credit authorization is also reversed.
Merchant Category Codes
When your business onboards with
Cybersource
, Cybersource
assigns your account a merchant category code (MCC) based on
your primary business type. Cybersource
sends this MCC to the card
networks with every transaction you process. If you process a transaction that is
unrelated to your usual goods or services, include the merchantInformation.categoryCode
field and set it to the relevant MCC. Cybersource
and FDC Nashville Global
do not validate the MCC you
send. Using an incorrect MCC can result in increased decline rates, interchange
downgrades, or fines. To verify the correct MCC, contact your Cybersource
account manager.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/refundsTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/refundsThe is the transaction ID
returned in the capture or sale response.
{id}
Required Fields for Processing a Refund
Refund
Use these required fields for processing a
refund
.Related Information
REST Interactive Example: Processing a Refund
Refund a Payment
Live Console URL: index.html#payments_refund_refund-a-payment
REST Example: Processing a Refund
Request
{ "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6699964581696622603955/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6699964581696622603955" } }, "clientReferenceInformation": { "code": "1669996458298" }, "creditAmountDetails": { "currency": "eur", "creditAmount": "100.00" }, "id": "6699964581696622603955", "orderInformation": { "amountDetails": { "currency": "EUR" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "016153570198200", "responseCode": "100" }, "reconciliationId": "61873329OAILG3Q6", "status": "PENDING", "submitTimeUtc": "2022-12-02T15:54:18Z" }
Credits
Credits
This section shows you how to process a credit, which
is not linked to a capture or sale. There is no time limit for requesting a credit.
When your account is enabled for credit authorizations, also known as purchase return
authorizations,
Cybersource
authenticates the card and customer during a refund or
credit request.
Every
credit request is automatically authorized. Credit authorization results are returned in
these response fields:
- processorInformation.approvalCode
- processorInformation.networkTransactionId
- processorInformation.responseCode
When you request a void for the credit and the credit is voided. If your account is enabled
for credit authorizations, the credit authorization is also reversed.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/credits/Test:
POST
https://apitest.cybersource.com
/pts/v2/credits/Required Fields for Processing a Credit
Use these required fields for processing a credit.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
REST Interactive Example: Processing a Credit
Credit
Live Console URL: index.html#payments_credit_process-a-credit
REST Example: Processing a Credit
Request
{ "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Kim", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "Kyong-Jin", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "eur" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "expirationMonth" : "12" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6663069906146706403954/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6663069906146706403954" } }, "clientReferenceInformation": { "code": "1666306990717" }, "creditAmountDetails": { "currency": "eur", "creditAmount": "100.00" }, "id": "6663069906146706403954", "orderInformation": { "amountDetails": { "currency": "eur" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "016153570198200", "responseCode": "100" }, "reconciliationId": "66490108K9CLFJPN", "status": "PENDING", "submitTimeUtc": "2022-10-20T23:03:10Z" }
Voids 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
Production:
POST
https://api.cybersource.com
/pts/v2/captures/{id}
/voidsTest:
POST
https://apitest.cybersource.com
/pts/v2/captures/{id}
/voidsVoid a Credit
Production:
POST
https://api.cybersource.com
/pts/v2/credits/{id}
/voidsTest:
POST
https://apitest.cybersource.com
/pts/v2/credits/{id}
/voidsThe is the transaction ID returned during the
capture or credit response.
{id}
Required Fields for Voiding a Capture or Credit
- Including this field is recommended, but not required.
REST Example: Voiding a Capture or Credit
Request
{ "clientReferenceInformation": { "code": "test123" } }
Response to a Successful Request
{ "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/6541933390746728203005" } }, "clientReferenceInformation": { "code": "1654193339056" }, "id": "6541933390746728203005", "orderInformation": { "amountDetails": { "currency": "USD" } }, "status": "VOIDED", "submitTimeUtc": "2022-06-02T18:08:59Z", "voidAmountDetails": { "currency": "usd", "voidAmount": "100.00" } }
Time-Out Voids for a Capture, Sale, Refund, or Credit
Time-Out Voids for a Capture, Sale,
Refund
, or Credit
When you do not receive a response message after requesting a capture, sale,
refund
, or credit
, this
feature enables you to void the transaction that you requested.Include the
clientReferenceInformation.transactionId
field in the original request for a
capture, sale, refund
, or credit
. The value of the merchant transaction ID must be unique for 180
days.When the original transaction fails, the response message for the reversal request
includes these fields:
- voidAmountDetails.originalTransactionAmount
- processorInformation.responseCode
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/voids/Test:
POST
https://apitest.cybersource.com
/pts/v2/voids/Required Fields for a Time-Out Void for a Capture, Sale, Refund, or Credit
Refund
, or Credit
Related Information
REST Example: Time-Out Void for a Capture, Sale, Refund, or
Credit
Request
{ "clientReferenceInformation": { "transactionId": "987654321" }, "reversalInformation": { "amountDetails": { "totalAmount": "100.00" }, "reason": "testing" } }
Request the Full Authorization Reversal Service
{ "orderInformation" : { "amountDetails" : { "currency" : "USD" } }, "reversalInformation" : { "amountDetails" : { "totalAmount" : "100.00" } } }
Response to a Successful Request
{ "_links": { "self": { "method": "GET", "href": "/pts/v2/voids/6541933390746728203005" } }, "clientReferenceInformation": { "code": "1654193339056" }, "id": "6541933390746728203005", "orderInformation": { "amountDetails": { "currency": "USD" } }, "status": "VOIDED", "submitTimeUtc": "2022-06-02T18:08:59Z", "voidAmountDetails": { "currency": "usd", "voidAmount": "100.00" } }
Debit and Prepaid Card Processing
This section shows you how to process authorizations that use a debit or prepaid card.
Related Information
- See Debit and Prepaid Card Payments for a description of the debit or prepaid card transactions you can process.
Processing Debit and Prepaid Authorizations
This section shows you how to process an authorization using debit and prepaid cards.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing Debit and Prepaid Authorizations
Use these required fields for processing debit and prepaid authorizations.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Related Information
Optional Field for Processing Debit and Prepaid Authorizations
You can use this optional field to include additional information when processing debit
and prepaid authorizations.
- Set this field to the request ID that was returned in the response message from the original authorization request.
Related Information
REST Example: Processing Debit and Prepaid Authorizations
Request
{ "orderInformation" : { "billTo" : { "country" : "US", "firstName" : "John", "lastName" : "Deo", "address1" : "901 Metro Center Blvd", "postalCode" : "40500", "locality" : "Foster City", "administrativeArea" : "CA", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "100.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "4111111111111111", "securityCode" : "123", "expirationMonth" : "12", "type" : "001" } } }
Response to a Successful Request
{ "_links" : { "authReversal" : { "method" : "POST", "href" : "/pts/v2/payments/6595482584316313203494/reversals" }, "self" : { "method" : "GET", "href" : "/pts/v2/payments/6595482584316313203494" }, "capture" : { "method" : "POST", "href" : "/pts/v2/payments/6595482584316313203494/captures" } }, "clientReferenceInformation" : { "code" : "RTS-Auth" }, "consumerAuthenticationInformation" : { "token" : "Axj/7wSTZYq1MhJBMfMmAEQs2auWrRwyauGjNi2ZsWbJgzaOWiaVA+JbK AU0qB8S2VpA6cQIp4ZNvG2YbC9eM4E5NlirUyEkEx8yYAAA4A1c" }, "id" : "6595482584316313203494", "orderInformation" : { "amountDetails" : { "authorizedAmount" : "100.00", "currency" : "USD" } }, "paymentAccountInformation" : { "card" : { "type" : "001" } }, "paymentInformation" : { "tokenizedCard" : { "type" : "001" }, "card" : { "type" : "001" } }, "processorInformation" : { "systemTraceAuditNumber" : "853428", "approvalCode" : "831000", "cardVerification" : { "resultCodeRaw" : "M", "resultCode" : "M" }, "merchantAdvice" : { "code" : "01", "codeRaw" : "M001" }, "responseDetails" : "ABC", "networkTransactionId" : "016153570198200", "retrievalReferenceNumber" : "221517853428", "consumerAuthenticationResponse" : { "code" : "2", "codeRaw" : "2" }, "transactionId" : "016153570198200", "responseCode" : "00", "avs" : { "code" : "Y", "codeRaw" : "Y" } } }
Enabling Debit and Prepaid Partial Authorizations
Partial authorizations and balance responses are special features that are available for
debit cards and prepaid cards. This section shows you how to enable partial
authorizations for a specific transaction.
Field Specific to this Use Case
Include this field in addition to the fields required for a standard authorization
request:
- Indicate that this request is a partial authorization.Set theprocessingInformation.authorizationOptions.partialAuthIndicatortotrue.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Enabling Debit and Prepaid Partial Authorizations
Use these required fields for enabling debit and prepaid partial authorizations.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value totrue.
Related Information
Optional Field for Enabling Debit and Prepaid Partial Authorizations
You can use these optional fields to include additional information when enabling debit and
prepaid partial authorizations.
- Set this field to the request ID that was returned in the response message from the original authorization request.
Related Information
REST Example: Enabling Debit and Prepaid Partial Authorizations
Request
{ "clientReferenceInformation" : { "code" : "TC50171_3" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Deo", "address2" : "Address 2", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "John", "phoneNumber" : "999999999", "district" : "MI", "buildingNumber" : "123", "company" : "Visa", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "1000.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "5555555555xxxxxx", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } }, "processingInformation" : { "authorizationOptions" : { "partialAuthIndicator" : "true" } } }
Response to a Successful Request
{ "_links" : { "self" : { "method" : "GET", "href" : "/pts/v2/payments/6595549144566655003494" } }, "clientReferenceInformation" : { "code" : "TC50171_3" }, "id" : "6595549144566655003494", "orderInformation" : { "amountDetails" : { "totalAmount" : "1000.00", "authorizedAmount" : "499.01", "currency" : "USD" } }, "paymentInformation" : { "accountFeatures" : { "currency" : "usd", "balanceAmount" : "0.00" } }, "pointOfSaleInformation" : { "terminalId" : "261996" }, "processorInformation" : { "merchantNumber" : "000000092345678", "approvalCode" : "888888", "cardVerification" : { "resultCode" : "" }, "networkTransactionId" : "123456789619999", "transactionId" : "123456789619999", "responseCode" : "100", "avs" : { "code" : "X", "codeRaw" : "I1" } }, "reconciliationId" : "56059417N6C86KTJ", "status" : "PARTIAL_AUTHORIZED", "submitTimeUtc" : "2022-08-03T19:28:34Z" }
Disabling Debit and Prepaid Partial
Authorizations
This topic shows you how to successfully disable partial authorizations for specific
transactions.
Field Specific to this Use Case
Include this field in addition to the fields required for a standard authorization
request:
- Indicate that this request is not a partial authorization.Set theprocessingInformation.authorizationOptions.partialAuthIndicatortofalse.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Field for Disabling Debit and Prepaid Partial Authorizations
Use these required fields for disabling debit and prepaid partial authorizations.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value tofalsein an authorization or sale request. When you do so, only that specific transaction is disabled for partial authorization.
Related Information
Optional Field for Disabling Debit and Prepaid Partial Authorizations
You can use this optional field to include additional information when disabling debit and
prepaid partial authorizations.
- Set this field to the request ID that was returned in the response message from the original authorization request.
Related Information
REST Example: Disabling Debit and Prepaid Partial Authorizations
Request
{ "processingInformation":{ "authorizationOptions":{ "partialAuthIndicator": "false" } }, "clientReferenceInformation" : { "code" : "TC50171_3" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Deo", "address2" : "Address 2", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "John", "phoneNumber" : "999999999", "district" : "MI", "buildingNumber" : "123", "company" : "Visa", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "501.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "5555555555xxxxxx", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } } }
Response to a Successful Request
{ "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/6595545423896900104953" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_DECLINED", "message": "Decline - General decline of the card. No other information provided by the issuing bank." }, "id": "6595545423896900104953", "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "status": "DECLINED" }
Airline Data Processing
This section describes how to process airline payments.
Requirement
When you are ready to go live with airline data processing, contact
Cybersource
Customer
Support to have your account configured to process airline data. If your account is not
enabled, and you try to send airline transactions, you will receive an error for invalid
data.Related Information
- See Airline Data for information about and requirements for processing payments that include airline data.
- See Airline Data Reference Information for a list and description of the different document type and ancillary service category codes that are used when processing payments that include airline data.
Airline Travel Legs
Some processors require travel legs in the API service request, even for direct flights.
This section describes how to successfully include travel legs in an API request.
Using Travel Legs
To include travel legs in an airline transaction, include one or more
travel legs in the
legs[]
array. For example, these three travel legs are valid:
"travelInformation": { "transit": { "airline": { "legs": [ { "carrierCode": "XX" }, { "carrierCode": "XZ" }, { "carrierCode": "XX" } ] }
Travel Leg Limitations
Some processors limit the number of travel legs for each trip based on the card type.
Authorize a Payment
This section describes how to process an airline authorization.
Authorization Restrictions
Ticket purchases that include multiple passengers may be included in a single
authorization request, however,
Cybersource
recommends sending a
separate capture request for each passenger.If any ancillary purchases are made at the same time as the ticket purchase, you may
include all the items in a single authorization request, however,
Cybersource
recommends separating the ancillary and ticket purchases into
individual capture requests.If any ancillary purchases are not made at the same time as the ticket purchase,
Cybersource
recommends separating the authorization and capture requests
for the ancillary and ticket purchases. Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for an Airline Authorization
Include these fields to process an airline authorization.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set toairline.
Card-Specific Fields for an Airline Authorization
This section includes card-specific information required for an airline
authorization.
American Express
Include these fields in addition to the required fields when using an American
Express card. American Express requires leg fields in the authorization request. For
more information about leg fields, see Airline Travel Legs.
REST Example: Airline Authorization
REST
Example: Airline Authorization Request
{ "clientReferenceInformation": { "code": "RTS-Auth" }, "orderInformation": { "billTo": { "country": "US", "lastName": "VDP", "address2": "test", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "RTS", "phoneNumber": "999999999", "district": "MI", "buildingNumber": "123", "company": "Visa", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" }, "shipTo": { "firstName": "Michale" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "3782822463xxxxx", "expirationMonth": "12", "securityCode": "123", "type": "003" } }, "processingInformation": { "industryDataType": "airline" }, "travelInformation": { "transit": { "airline": { "passengerName": "Michale", "legs": [ { "carrierCode": "123", "fareBasis": "B1", "departureDate": "20230202", "destinationAirportCode": "NY", "originatingAirportCode": "SFO" }, { "carrierCode": "456", "fareBasis": "B2", "departureDate": "20230202", "destinationAirportCode": "SFO", "originatingAirportCode": "SJC" } ] } } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6902464806406008803234/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6902464806406008803234" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6902464806406008803234/captures" } }, "clientReferenceInformation": { "code": "1690246480572" }, "id": "6902464806406008803234", "issuerInformation": { "responseRaw": "0110322000000E1000020000000000000100000725005441300026475537344F4B48495131314D38333130303030300001590064003631342030313631373831313031353439343520202020202036363030533036303030303100103232415050524F56414C0012534443523030355959595959" }, "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "usd" } }, "paymentAccountInformation": { "card": { "type": "003" } }, "paymentInformation": { "tokenizedCard": { "type": "003" }, "card": { "type": "003" } }, "pointOfSaleInformation": { "terminalId": "00092940" }, "processorInformation": { "electronicVerificationResults": { "phoneNumberRaw": "Y", "emailRaw": "Y", "phoneNumber": "Y", "code": "Y", "postalCodeRaw": "Y", "street": "Y", "postalCode": "Y", "codeRaw": "Y", "streetRaw": "Y", "email": "Y" }, "merchantNumber": "000000000001234", "approvalCode": "831000", "responseCode": "00", "avs": { "code": "Y", "codeRaw": "Y" } }, "reconciliationId": "GU74OKHIQ11M", "status": "AUTHORIZED", "submitTimeUtc": "2023-07-25T00:54:41Z" }
Request
{ "clientReferenceInformation": { "code": "RTS-Auth" }, "processingInformation": { "industryDataType": "airline" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031", "type": "001" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com" } } }
Successful Response
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6917758602546577403955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6917758602546577403955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6917758602546577403955/captures" } }, "clientReferenceInformation": { "code": "1691775860306" }, "id": "6917758602546577403955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "68209505QL5OEHAU", "status": "AUTHORIZED", "submitTimeUtc": "2023-08-11T17:44:20Z" }
Unsuccessful Response
{ "submitTimeUtc" : "2020-05-20T21:06:56Z", "status" : "INVALID_REQUEST", "reason" : "INVALID_DATA", "message" : "Declined - One or more fields in the request contains invalid data", "details" : [ { "field" : "stopover_code", "reason" : "INVALID_DATA" } ] }
Capture a Ticket Payment
This section describes how to capture an airline ticket payment, such as when a person is
purchasing a ticket on your e-commerce store.
Capture Restrictions
For a ticket purchase with multiple passengers,
Cybersource
recommends
sending separate capture requests for each passenger. The original authorization may
be a single request. When ancillary purchases are made at the same time as the ticket purchase,
Cybersource
recommends sending separate capture requests for the ticket
and ancillary purchases. Airline Travel Legs
FDC Nashville Global
requires you to include travel leg fields in your
requests, even for direct flights. For more information about how to format travel
leg fields, see Airline Travel Legs.Leg Limitations
FDC Nashville Global
limits the maximum number of legs for each trip based
on card type. This table describes the maximum number of legs for each trip based on
processor and card type.Supported Card Types | Maximum Number of Trip Legs |
---|---|
American Express | 4 |
Discover | 4 |
Mastercard | 99 |
Visa | 4 |
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe is the transaction ID
returned in the authorization response.
{id}
Required Fields for Capturing a Ticket Payment
Include these required fields to capture an airline payment for tickets.
- Set toairline.
- travelInformation.transit.airline.ticketNumber
Card-Specific Fields for Capturing a Ticket
Payment
This section includes card-specific information required to capture a payment for
tickets.
Discover
Include these fields in addition to the required fields when using a Discover
card.
- Set toAorP.
- Set toAorP.
Mastercard
Include these fields in addition to the required fields when using a Mastercard
card.
Visa
Include this field in addition to the required fields when using a Visa card.
- Set to0for refundable.
- Set to1for nonrefundable.
Optional Fields for an Airline Capture
Choose from these optional fields to include additional information when capturing an
airline payment for direct flight tickets.
- travelInformation.transit.airline.clearingCount
- travelInformation.transit.airline.clearingSequence
- Set toO(capital letter "O") to indicate the leg of a trip is allowed to stopover. Default value.
- Set toXto indicate the leg of a trip is not allowed to stopover.
- travelInformation.transit.airline.totalClearingAmount
REST Example: Capturing a Visa Airline Payment
REST
Example: Capturing a Visa Airline PaymentRequest
{ "clientReferenceInformation": { "code": "RTS-Bill" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "processingInformation": { "industryDataType": "airline" }, "travelInformation": { "agency": { "name": "Thomascook" }, "transit": { "airline": { "passengerName": "John", "ticketNumber": "asd23", "customerCode": "LDTYOU789", "totalFeeAmount": "200", "planNumber": "49252", "exchangeTicketAmount": "11", "exchangeTicketFeeAmount": "1", "legs": [ { "carrierCode": "AA", "originatingAirportCode": "SFO", "class": "1", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "NY", "exchangeTicketNumber": "ticket12", "endorsementsRestrictions": "Endorsement1234", "feeAmount": "999.99", "taxAmount": "99" }, { "carrierCode": "BB", "originatingAirportCode": "NY", "class": "2", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "SFO", "exchangeTicketNumber": "ticket13", "endorsementsRestrictions": "Endorsement1234", "feeAmount": "999.99", "taxAmount": "99" } ] } } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6917768579016106103954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6917768579016106103954" } }, "clientReferenceInformation": { "code": "RTS-Bill" }, "id": "6917768579016106103954", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "reconciliationId": "682098706L5PQJ7Y", "status": "PENDING", "submitTimeUtc": "2023-08-11T18:00:58Z" }
Request
{ "clientReferenceInformation": { "code": "RTS-Bill" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "processingInformation": { "industryDataType": "airline" }, "travelInformation": { "agency": { "name": "Thomascook", "code": "123" }, "transit": { "airline": { "passengerName": "John", "ticketNumber": "asd23", "customerCode": "LDTYOU789", "totalFeeAmount": "200", "planNumber": "49252", "exchangeTicketAmount": "11", "exchangeTicketFeeAmount": "1", "ticketIssueDate": "20190202", "arrivalDate": "20230808", "ticketIssuer": { "address": "Silicon Vally" }, "legs": [ { "carrierCode": "AA", "flightNumber": "UA789", "originatingAirportCode": "SFO", "class": "1", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "NY", "fareBasis": "B1", "totalFareAmount": "12", "exchangeTicketNumber": "ticket12", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234", "arrivalTime": "1920", "arrivalTimeMeridian": "A", "departureTime": "1230", "departureTimeMeridian": "A" }, { "carrierCode": "BB", "flightNumber": "UA788", "originatingAirportCode": "NY", "class": "2", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "SFO", "fareBasis": "B1", "totalFareAmount": "12", "exchangeTicketNumber": "ticket13", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234", "arrivalTime": "0120", "arrivalTimeMeridian": "A", "departureTime": "2030", "departureTimeMeridian": "A" } ] } } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6917775047466121303955/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6917775047466121303955" } }, "clientReferenceInformation": { "code": "RTS-Bill" }, "id": "6917775047466121303955", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "reconciliationId": "68210417JL5O06RJ", "status": "PENDING", "submitTimeUtc": "2023-08-11T18:11:44Z" }
Request
{ "clientReferenceInformation": { "code": "RTS-Bill" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "processingInformation": { "industryDataType": "airline" }, "travelInformation": { "agency": { "name": "Thomascook" }, "transit": { "airline": { "passengerName": "John", "ticketNumber": "asd23", "customerCode": "LDTYOU789", "totalFeeAmount": "200", "planNumber": "49252", "exchangeTicketAmount": "11", "exchangeTicketFeeAmount": "1", "legs": [ { "carrierCode": "AA", "flightNumber": "UA789", "originatingAirportCode": "SFO", "class": "1", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "NY", "fareBasis": "B1", "exchangeTicketNumber": "ticket12", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234" }, { "carrierCode": "BB", "flightNumber": "UA788", "originatingAirportCode": "NY", "class": "2", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "SFO", "fareBasis": "B1", "exchangeTicketNumber": "ticket13", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234" } ] } } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6917778689216158003955/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6917778689216158003955" } }, "clientReferenceInformation": { "code": "RTS-Bill" }, "id": "6917778689216158003955", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "reconciliationId": "68210471JL5O06T1", "status": "PENDING", "submitTimeUtc": "2023-08-11T18:17:49Z" }
Request
{ "clientReferenceInformation": { "code": "RTS-Bill" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "processingInformation": { "industryDataType": "airline" }, "travelInformation": { "agency": { "name": "Thomascook" }, "transit": { "airline": { "passengerName": "John", "ticketNumber": "asd23", "customerCode": "LDTYOU789", "totalFeeAmount": "200", "planNumber": "49252", "exchangeTicketAmount": "11", "exchangeTicketFeeAmount": "1", "restrictedTicketIndicator": "0", "legs": [ { "carrierCode": "AA", "originatingAirportCode": "SFO", "class": "1", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "NY", "exchangeTicketNumber": "ticket12", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234" }, { "carrierCode": "BB", "originatingAirportCode": "NY", "class": "2", "stopoverIndicator": "O", "departureDate": "20230202", "destinationAirportCode": "SFO", "exchangeTicketNumber": "ticket13", "departureTime": "1720", "endorsementsRestrictions": "Endorsement1234" } ] } } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6917788755186225803955/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6917788755186225803955" } }, "clientReferenceInformation": { "code": "RTS-Bill" }, "id": "6917788755186225803955", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "reconciliationId": "68211484JL5O0702", "status": "PENDING", "submitTimeUtc": "2023-08-11T18:34:35Z" }
Capture an Ancillary Purchase
Ancillary purchases are any additional services, such as baggage, meals, and paid seats,
your customers can purchase. Captures for ancillary purchases must be separate for
captures for ticket purchases.
FDC Nashville Global
supports up to four
ancillary purchases for each capture. Capture Restrictions
When ancillary purchases are made at the same time as the ticket purchase,
Cybersource
recommends sending separate capture requests for the ticket
and ancillary purchases. When ancillary purchases are not made at the same time as the ticket purchase,
Cybersource
recommends sending separate authorization and
capture requests for the ancillary and ticket purchases.Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe is the transaction ID
returned in the authorization response.
{id}
Required Fields for an Airline Capture
Ancillary Airline Fields
Choose from these optional ancillary airline fields to include in your capture
request in addition to the required fields listed above.
IMPORTANT
FDC Nashville Global
supports up to four ancillary
purchases for each capture.- For a list of possible values, see Ancillary Service Category Codes.
- For a list of possible values, see Ancillary Service Category Codes.
- Set toCfor changing an existing ticket.
- Set toNfor a new ticket.
REST Example: Capturing an Airline Payment for Ancillary
Purchases
REST
Example: Capturing an Airline Payment for Ancillary
PurchasesRequest
{ "clientReferenceInformation": { "code": "TC50171_3" }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } }, "travelInformation": { "transit": { "airline": { "ancillaryInformation": { "ticketNumber": "123456789", "passengerName": "John Doe", "connectedTicketNumber": "987654321", "service": [ { "categoryCode": "65", "subCategoryCode": "75" } ] } } } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6811595456806928403955/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6811595456806928403955" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6811595456806928403955", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } }, "reconciliationId": "658927039G5GNF51", "status": "PENDING", "submitTimeUtc": "2023-04-10T20:45:45Z" }
Refund a Payment
Refund a Payment
This section describes how to process an airline refund, which requires
you to have the transaction ID from the original payment.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/refundsTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/refundsThe is the transaction ID
returned in the capture or sale response.
{id}
Required Fields for an Airline Refund
Refund
Include these fields to process an airline
refund
.Optional Fields for an Airline Refund
Refund
Choose from these optional fields to include additional information when processing an
airline
refund
.- travelInformation.transit.airline. clearingCount
- travelInformation.transit.airline. clearingSequence
- travelInformation.transit.airline. totalClearingAmount
- travelInformation. transit. airline.ancillaryInformation. creditReasonIndicator
- Set to one of these possible values:
- A: Passenger transport ancillary fee cancellation
- B: Airline ticket and passenger transport ancillary fee cancellation
- C: Airline ticket cancellation
- O: Other
- P: Partial refund of airline ticket
REST Example: Processing an Airline Refund
REST
Example: Processing an Airline Refund
Request
{ "processingInformation": { "industryDataType": "airline" }, "orderInformation": { "amountDetails": { "totalAmount": "102.21" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/refunds/6805496388936342404953/voids" }, "self": { "method": "GET", "href": "/pts/v2/refunds/6805496388936342404953" } }, "clientReferenceInformation": { "code": "1680549638986" }, "id": "6805496388936342404953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "712678686G0ONA52", "refundAmountDetails": { "currency": "USD", "refundAmount": "102.21" }, "status": "PENDING", "submitTimeUtc": "2023-04-03T19:20:39Z" }
Payer Authentication Processing
This section shows you how to process authorizations that use these payer authentication
methods:
- American Express: SafeKey
- Mastercard: Identity Check
- Visa: Visa Secure
Related Information
- See the Payer Authentication Developer Guide for details about payer authentication.
Providing Payer Authentication Information for Authorization
The values that are returned from payer authentication must be provided when seeking
authorization for the transaction. Authentication information that is not included when
considering authorization may cause the transaction to be refused or downgraded and
prevent the normal liability shift from occurring.
The level of security in payer authentication is denoted by the two digit Electronic
Commerce Indicator (ECI) that is assigned to the transaction. These digital values have
text equivalents which are assigned to the
processingInformation.commerceIndicator
field. The
American Express,
Diners, Discover, UPI, and Visa
card brands use 05, 06, and 07 digit values to express the authentication level for
a 3-D Secure transaction.ECI Value | Meaning | Visa | Diners | Discover | UPI | Amex |
---|---|---|---|---|---|---|
05 | Authenticated | vbv | pb | dipb | up3ds | aesk |
06 | Attempted authentication with a cryptogram | vbv_attempted | pb_attempted | dipb_attempted | up3ds_attempted | aesk_attempted |
07 | Internet, not authenticated | vbv_failure/internet | internet | internet | up3ds_failure/internet | internet |
Mastercard and Maestro cards use 00, 01, 02, 06, and 07 digit values to indicate the
authentication level of the transaction.
ECI Value | Meaning | Mastercard/Maestro |
---|---|---|
00 | Internet, not authenticated | spa/internet |
01 | Attempted authentication | spa |
02 | Authenticated | spa |
06 | Exemption from authentication or
network token without 3‑D Secure | spa |
07 | Authenticated merchant-initiated
transaction | spa |
The payer authentication response contains other information that needs to be passed on
for successful authorization. Be sure to include these fields when requesting a separate
authorization:
- consumerAuthenticationInformation.directoryServerTransactionId(Mastercard, Maestro, UPI only)
- consumerAuthenticationInformation.eciRaw
- consumerAuthenticationInformation.paresStatus
- consumerAuthenticationInformation.paSpecificationVersion
- consumerAuthenticationInformation.ucafAuthenticationData(Mastercard/Maestro only)
- consumerAuthenticationInformation.ucafCollectionIndicator(Mastercard/Maestro only)
- consumerAuthenticationInformation.cavv
- consumerAuthenticationInformation.xid
American Express SafeKey
American Express SafeKey is the authentication service in the American Express card network
that uses the 3-D Secure protocol to validate customers at checkout. When you request
an authorization using a supported card type and a supported processor, you can include payer
authentication data in the request.
IMPORTANT
FDC Nashville Global
supports 3-D Secure 2.0 transactions using an American
Express payment card.IMPORTANT
FDC Nashville Global
supports 3-D Secure
2.0 with America Express transactions. Before implementing payer authentication for American Express SafeKey, contact customer
support to have your account configured for this feature.
Fields Specific to the American Express SafeKey Use Case
These API fields are required specifically for this use case.
- consumerAuthenticationInformation.cavv
- Required when payer authentication is successful.
- processingInformation.commerceIndicator
- Set this field to one of these values:
- aesk: Successful authentication (3-D Secure value of05).
- aesk_attempted: Authentication was attempted (3-D Secure value of06).
- internet: Authentication failed or was not attempted (3-D Secure value of07).
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRelated Information
Required Fields for Processing an Authorization Using American Express SafeKey
These fields must be included in a request for an authorization with American SafeKey. The
values for these fields are in the response from the payer authentication validate service.
When you request the payer authentication validate and authorization services together, the
data is automatically passed from one service to the other.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- clientReferenceInformation.code
- consumerAuthenticationInformation.cavv
- consumerAuthenticationInformation.eciRaw
- Required when the payer authentication validation service returns a raw unmapped ECI value.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.administrativeArea
- orderInformation.billTo.country
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- orderInformation.billTo.locality
- orderInformation.billTo.postalCode
- paymentInformation.card.expirationMonth
- paymentInformation.card.expirationYear
- paymentInformation.card.number
- paymentInformation.card.type
- processingInformation.commerceIndicator
- Set this field to one of these values:
- aesk: Successful authentication (3-D Secure value of05).
- aesk_attempted: Authentication was attempted (3-D Secure value of06).
- internet: Authentication failed or was not attempted (3-D Secure value of07).
Related Information
Optional Field for Processing an Authorization Using American Express SafeKey
This field is optional in a request for an authorization with American Express SafeKey. The
value for this field is in the response from the payer authentication validate service. When
you request the payer authentication validate and authorization services together, the data
is automatically passed from one service to the other.
- consumerAuthenticationInformation.xid
Related Information
REST Example: Processing an Authorization Using American Express SafeKey
Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "aesk" }, "paymentInformation": { "card": { "number": "3400000XXXXXXX8", "expirationMonth": "01", "expirationYear": "2025" } }, "orderInformation": { "amountDetails": { "totalAmount": "100", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "201 S. Division St._1", "locality": "Foster City", "administrativeArea": "CA", "postalCode": "94404", "country": "US", "email": "accept@who.com", "phoneNumber": "6504327113" } }, "consumerAuthenticationInformation": { "cavv": "1234567890987654321ABCDEFabcdefABCDEF123", "xid": "1234567890987654321ABCDEFabcdefABCDEF123" } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6783071542936193303955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6783071542936193303955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6783071542936193303955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6783071542936193303955", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "003" } }, "paymentInformation": { "accountFeatures": { "currency": "usd", "balanceAmount": "70.00" }, "tokenizedCard": { "type": "003" }, "card": { "type": "003" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62427259FEYR18Q2", "status": "AUTHORIZED", "submitTimeUtc": "2023-03-08T20:25:54Z" }
Mastercard Identity Check
Mastercard Identity Check is the authentication service in the Mastercard card network
that uses the 3-D Secure protocol in online transactions to authenticate
customers at checkout.
Mastercard Identity Check generates a unique, 32-character transaction token, called the
account authentication value (AAV) each time a Mastercard Identity Check-enabled account
holder makes an online purchase. The AAV binds the account holder to a specific
transaction. Mastercard Identity Check transactions use the universal cardholder
authentication field (UCAF) as a standard to collect and pass AAV data.
Before implementing payer authentication for Mastercard Identity Check, contact customer support to have your account configured for this feature.
IMPORTANT
FDC Nashville Global
supports 3-D
Secure 2.0 with Mastercard transactions. FDC Nashville Global
also supports the
use of digital payments in 3-D Secure 2.0 transactions when used with Mastercard
transactions. A 3-D Secure data-only flow that does not require contacting the customer
is also supported. A full liability shift is applied if the UCAF data is collected and
the ECI is set to 04
. Fields Specific to the Mastercard Identity Check Use Case
These API fields are required specifically for this use case.
- consumerAuthenticationInformation. directory ServerTransactionId
- Set this field to the transaction ID returned by Mastercard Identity Check during the authentication process.
- consumerAuthenticationInformation. paSpecificationVersion
- Set this field to the Mastercard Identity Check version returned by Mastercard Identity Check during the authentication process.
- consumerAuthenticationInformation. ucafCollectionIndicator
- Set to the last digit of the raw ECI value returned from authentication. For example, if ECI=02, this value should be 2.
- processingInformation.commerceIndicator
- Set this field to one of these values:
- spa: Successful authentication (3-D Secure value of02).
- spa: Authentication was attempted (3-D Secure value of01).
- spaorinternet: Authentication failed or was not attempted (3-D Secure value of00)
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing an Authorization Using Mastercard Identity Check
Use these required fields to process an authorization using Mastercard Identity Check.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- consumerAuthenticationInformation.directoryServerTransactionId
- consumerAuthenticationInformation.paSpecificationVersion
- consumerAuthenticationInformation.ucafCollectionIndicator
- Set to the last digit of the raw ECI value returned from authentication. For example, if ECI=02, this value should be 2.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.administrativeArea
- orderInformation.billTo.country
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- orderInformation.billTo.locality
- orderInformation.billTo.postalCode
- paymentInformation.card.expirationMonth
- paymentInformation.card.expirationYear
- paymentInformation.card.number
- processingInformation.commerceIndicator
- Set this field to one of these values:
- spa: Successful authentication (3-D Secure value of02).
- spa: Authentication was attempted (3-D Secure value of01).
- spaorinternet: Authentication failed or was not attempted (3-D Secure value of00)
Related Information
REST Example: Processing an Authorization Using Mastercard Identity Check
Request
{ "clientReferenceInformation" : { "code" : "TC50171_6" }, "consumerAuthenticationInformation" : { "ucafCollectionIndicator" : "2", "ucafAuthenticationData" : "EHuWW9PiBkWvqE5juRwDzAUFBAk", "directoryServerTransactionId" : "f38e6948-5388-41a6-bca4-b49723c19437", "paSpecificationVersion" : "2.2.0" }, "processingInformation" : { "commerceIndicator" : "spa" }, "orderInformation" : { "billTo" : { "country" : "US", "lastName" : "Deo", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "John", "email" :test@cybs.com}, "amountDetails" : { "totalAmount" : "105.00", "currency" : "USD" } }, "paymentInformation" : { "card" : { "expirationYear" : "2031", "number" : "555555555555XXXX", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6758990751436655004951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6758990751436655004951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6758990751436655004951/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6758990751436655004951", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "71183995FDU0YRTK", "status": "AUTHORIZED", "submitTimeUtc": "2023-02-08T23:31:15Z" }
Visa Secure
Visa Secure is the authentication service in the Visa card network that uses the 3-D
Secure protocol to authenticate customers at checkout. This authentication is a two-step
process. First, the cardholder is authenticated by 3-D Secure. Then, the transaction is
authorized based on the 3-D Secure evaluation. This section explains how to authorize a
card payment based on the 3-D Secure evaluation.
IMPORTANT
FDC Nashville Global
supports 3-D
Secure 2.0 with Visa transactions. FDC Nashville Global
also supports the use
of digital payments in 3-D Secure 2.0 transactions when used with Visa transactions. A
3-D Secure data-only flow that does not require contacting the customer is also
supported. A full liability shift is applied if the CAVV data is collected and the ECI
is set to 07
. Before implementing Visa Secure, contact customer support to have your account configured
for this feature.
Fields Specific to the Visa Secure Use Case
These API fields are required specifically for this use case.
- processingInformation.commerceIndicator
- Set the value tovbvfor a successful authentication (3-D Secure value of05),vbv_attemptedif authentication was attempted but did not succeed (3-D Secure value of06), orvbv_failureif authentication failed (3-D Secure value of07).
- consumerAuthenticationInformation.cavv
- Required when payer authentication is successful.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRelated Information
Required Fields for Processing an Authorization Using Visa Secure
Use these required fields to process an authorization using Visa Secure.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all
fields in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. Refer to the Payments
guide for more information about relaxed requirements in payment transactions.
Required Fields
- This field is required when payer authentication is successful. Otherwise, this field is optional.
- Verosupports Brazilian real (BRL) currency only.
- Set this field to one of these values:
- vbv: Successful authentication (EMV3-D Securevalue of05).
- vbv_attempted: Authentication was attempted (EMV3-D Securevalue of06).
- vbv_failure: orinternet: Authentication failed or was not attempted (EMV3-D Securevalue of07).
Related Information
REST Example: Validating and Authorizing a Transaction
Request
{ "clientReferenceInformation": { "code": "test" }, "processingInformation": { "capture": "true", "authorizationOptions": { "ignoreAvsResult": "true" }, "actionList": [ "VALIDATE_CONSUMER_AUTHENTICATION" ] }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4XXXXXXXXXXX25X3", "securityCode": "123", "expirationMonth": "12", "type": "001" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "GBP" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "201 S. Division St._1", "address2": "Suite 500", "locality": "Foster City", "administrativeArea": "CA", "postalCode": "94404", "country": "US", "email": "accept@cybersource.com", "phoneNumber": "6504327113" } }, "consumerAuthenticationInformation": { "authenticationTransactionId": "2b4eAa4K3H778X34Ciy0" } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/payments/7478305945626990404807/voids" }, "self": { "method": "GET", "href": "/pts/v2/payments/7478305945626990404807" } }, "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "indicator": "vbv", "eciRaw": "05", "authenticationResult": "0", "strongAuthentication": { "OutageExemptionIndicator": "0" }, "authenticationStatusMsg": "Success", "eci": "05", "token": "Axj//wSTlWZX08jkcOTHAAIU3YMmzhgzcN2ie/LXsgSgKe/LXsgS50OnEFBWGTSTL0Yua1eAwHScqzK+nkcjhyY4wDi0", "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "paresStatus": "Y", "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "directoryServerTransactionId": "fa628ed8-ad77-4723-b28f-91952eaca8fe", "threeDSServerTransactionId": "71399671-8456-4c97-b056-e127622a5e26", "specificationVersion": "2.2.0", "acsTransactionId": "5f9fb589-08cc-4952-866d-30939868f411" }, "id": "7478305945626990404807", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "authorizedAmount": "100.00", "currency": "GBP" } }, "paymentAccountInformation": { "card": { "brandName": "VISA", "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "bin": "400000", "type": "VISA" } }, "pointOfSaleInformation": { "terminalId": "12345678" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013018036776997406844475", "merchantNumber": "12345678", "approvalCode": "100", "cardVerification": { "resultCodeRaw": "3", "resultCode": "2" }, "merchantAdvice": { "code": "00", "codeRaw": "0" }, "networkTransactionId": "123456789012345", "transactionId": "123456789012345", "responseCode": "0", "avs": { "code": "U", "codeRaw": "00" } }, "reconciliationId": "7026803874", "status": "AUTHORIZED", "submitTimeUtc": "2025-05-21T12:29:54Z" }
Relaxed Requirements for Address Data and Expiration Date in Payment Transactions
With relaxed requirements for address data and the expiration date, not all standard payment request fields are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required.
Requirements
You must contact customer support in order to enable relaxed requirements for address data and expiration date.
Services
Relaxed requirements for address data and expiration date are supported for these services:
- Authorization
- Capture
- Stand-alone credit
- Subscription create
- Subscription update
Relaxed Fields
IMPORTANT
When relaxed requirements for address data and expiration date are enabled for your
Cybersource
account, and your service request does not include one or more of the fields in the following list, you increase the risk of declined transactions and fraud depending on your location, your processor, and the cardholder's issuing bank.It is your responsibility to determine whether a field is required for the transaction you are requesting. For example, an issuing bank can decline an authorization request for a recurring transaction with a Visa Europe card if the expiration date is incorrect, invalid, or missing. If you do not provide the correct expiration date for a recurring transaction the authorization request may be declined.
- You can submit an expiration date that has expired. This exception does not apply when you combine any of the services listed above with any other service.
- This field is required for payment network token transactions and subscription creation requests.
- You can submit an expiration date that has expired. This exception does not apply when you combine any of the services listed above with any other service.
- This field is required for payment network token transactions and subscription creation requests.
Processing Payments Using Credentials
This section provides the information you need in order to process payments using
credentials.
Customer-Initiated Transactions with Credentials on
File
A customer-initiated transaction (CIT) is a transaction initiated by the customer. There
are two types of CITs:
- Customer transactions during which the credentials are stored for futurecustomer-initiated transactions.
- Customer transactions during which the credentials are stored for futuremerchant-initiated transactions.
Customers can initiate a CIT at a merchant payment terminal, through an online purchase
transaction, or by making a purchase using a previously stored credential. When storing
cardholder data for a CIT, you must also include 3-D Secure authentication credentials
to ensure that the CIT can successfully process. Authentication credentials can be
stored for future use with the card credentials by doing a non-payment authentication
(NPA).
Business Center
Business Center
You can create a new customer-initiated transaction in the
Business Center
by
going to the One-Time Payments section and requesting a new authorization. When you
have entered the customer's information, you can store the customer's credentials
with the customer's permission in the Payment Information section. By doing so, you
can perform merchant-initiated transactions for payments that the customer has
pre-approved. Storing Customer Credentials with a CIT and PAN
Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated
transaction (CIT) with credentials-on-file (COF), you must store the customer's
credentials for later use. Further, before you can store the user's credentials, you
must get the customer's consent to store their private information. This is also known
as establishing a relationship with the customer.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Storing Customer Credentials During a CIT
Use these required fields for storing customer credentials during a customer-initiated
transaction.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value totrue.
REST Example: Storing Customer Credentials During a CIT
Request
{ "processingInformation": { "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "email": "test@cybs.com", "phoneNumber": "5554327113" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" }
Storing Customer Credentials with a CIT and TMS
TMS
Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated
transaction (CIT) with credentials-on-file (COF), you must get the customer's consent to store their payment credentials. This is also known as establishing a relationship with the customer. After you have their consent, you can store their payment credentials for later use.
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Storing Customer Credentials with a
CIT and TMS
TMS
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value toTOKEN_CREATE
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymnentInstrument
REST Example: Storing Customer Credentials with a CIT and
TMS
TMS
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ] }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031", "securityCode": "123" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6972267090226779103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6972267090226779103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62506622XNMR6Q1Y", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-13T19:51:49Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } }
Retrieving Stored Customer Credentials During a
CIT
After customers store their credentials on file, you can retrieve these credentials to
use with subsequent transactions.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Retrieving Customer Credentials During a Customer-Initiated
Transaction
Use these required fields to retrieve customer credentials during a customer-initiated
transaction.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- orderInformation.billTo.firstName
- Set field totrue.
Card-Specific Required Field for Retrieving Customer
Credentials During a CIT
Discover
Discover requires the authorization amount from the original transaction in addition
to the above required fields.
- processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction. originalAuthorizedAmount
REST Example: Retrieving Customer Credentials During a CIT
Request
{ "processingInformation": { "authorizationOptions": { "initiator": { "storedCredentialUsed": "true" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "email": "test@cybs.com", "phoneNumber": "5554327113" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD", "originalAmount": "100" // Discover card Only } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } }, "processorInformation": { "transactionId": "12345678961000" } }
Response to a Successful Request
}, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63740353A3AJ2NSH", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T19:13:06Z" }
Reauthorization Transaction
A reauthorization occurs when the completion or fulfillment of the
original order or service extends beyond the authorized amount time limit. There are two
common reauthorization scenarios:
- Split or delayed shipments by a retailer
- Extended car rentals, hotel stays, or cruise line bookings
This section describes how to process a reauthorization transaction using these payment
methods:
Merchant-Initiated Reauthorization Transactions with PAN
A reauthorization occurs when the completion or fulfillment of the
original order or service extends beyond the authorized amount time limit. There are two
common reauthorization scenarios:
- Split or delayed shipments by a retailer
- Extended car rentals, hotel stays, or cruise line bookings
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing Merchant-Initiated Reauthorized Transactions
Use these required fields to process a merchant-initiated reauthorization transaction.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value to3.
- Required only for Discover and Visa.
- Set the value tomerchant.
Card-Specific Required Field for Processing a Merchant-Initiated Transactions
Discover
The listed card requires an additional field:
- processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. originalAuthorizedAmount
- Provide the original transaction amount.
REST Example: Processing a Merchant-Initiated Reauthorized Transaction
Request
{ "processingInformation": { "authorizationOptions": { "initiator": { "type": "merchant", "merchantInitiatedTransaction": { "originalAuthorizedAmount": "100", // Discover Only "previousTransactionId": "123456789619999", "reason": "3" } } } }, "orderInformation": { "billTo" : { "country" : "US", "lastName" : "Kim", "address1" : "201 S. Division St.", "postalCode" : "48104-2201", "locality" : "Ann Arbor", "administrativeArea" : "MI", "firstName" : "Kyong-Jin", "phoneNumber": "5554327113", "email" : "test@cybs.com" }, "amountDetails": { "totalAmount": "130.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6541178668686490403003/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6541178668686490403003" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6541178668686490403003/captures" } }, "clientReferenceInformation": { "code": "1654117866849" }, "id": "6541178668686490403003", "orderInformation": { "amountDetails": { "authorizedAmount": "130.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "65313868D3TXXC05", "status": "AUTHORIZED", "submitTimeUtc": "2022-06-01T21:11:06Z" }
Merchant-Initiated Reauthorization Transactions with TMS
TMS
A reauthorization occurs when the completion or fulfillment of the
original order or service extends beyond the authorized amount time limit. There are two
common reauthorization scenarios:
- Split or delayed shipments by a retailer
- Extended car rentals, hotel stays, or cruise line bookings
This section describes how to process a merchant-initiated reauthorization transactions
using one or more
TMS
token types: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } }
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token.
- Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } }
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID.
- "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }
- For more information about thisTMStoken type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for MIT Reauthorization Transaction with TMS
TMS
Include these Required Fields
- paymentInformation.[tokentype].id
- Where[tokentype]is theTMStoken type you are using:
- Set the value to3.
- Required only for Discover and Visa.
Instrument Identifier Required Fields
If you are using the
paymentInformation.instrumentIdentifier.id
token, include these required fields in addition to the required fields listed
above.Card-Specific Fields
The listed card type requires an additional field.
- Discover
- processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount
- Set to the original transaction amount.
Example: MIT Reauthorization Transaction with a TMS Instrument
Identifier
TMS
Instrument
IdentifierRequest
{ "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "3" } } } }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2031" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976922830456934003954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976922830456934003954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976922830456934003954/captures" } }, "clientReferenceInformation": { "code": "1697692283160" }, "id": "6976922830456934003954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62700184NNMR6XFK", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T05:11:23Z" }
Example: MIT Reauthorization Transaction with a TMS Payment
Instrument
TMS
Payment
InstrumentRequest
{ "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "3" } } } }, "paymentInformation": { "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976917718796256603955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976917718796256603955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976917718796256603955/captures" } }, "clientReferenceInformation": { "code": "1697691771976" }, "id": "6976917718796256603955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62700629BNN13VGW", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T05:02:52Z" }
Example: MIT Reauthorization Transaction with a TMS
Customer
TMS
CustomerRequest
{ "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "3" } } } }, "paymentInformation": { "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976916433716228003955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976916433716228003955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976916433716228003955/captures" } }, "clientReferenceInformation": { "code": "1697691643458" }, "id": "6976916433716228003955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE6DB37B09557E063A2598D0AA4C9" }, "card": { "type": "001" }, "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62700435FNN143RY", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T05:00:43Z" }
Installment Payments
An installment payment is a single purchase of goods or services billed to a customer in
multiple transactions over a period of time agreed to by you and the customer. The agreement
enables you to charge a specific amount at specified intervals.
Installments Service for Installment Payments
IMPORTANT
Do not use this document if you are using the Installments service. When
using the Installments service,
Cybersource
saves and stores payment
credentials for installment transactions, ensuring compliance with COF best practices. Customer-Initiated Installment Payments with PAN
An installment payment is a single purchase of goods or services
billed to a customer in multiple transactions over a period of time agreed to by you
and the customer, and sometimes, the issuing bank. The agreement enables you to
charge a specific amount at specified intervals. For customers, installment payments
provide greater purchasing power and lower impact on their monthly budget. For you,
offering installment payments at checkout can help increase the number of
successfully completed purchases.
Before you can accept installment payments, you and your
acquirer must agree on the maximum number of installments you can accept, which can
be different for each card type.
IMPORTANT
Do not use this document if you are using the
Installments service. When using the Installments service,
Cybersource
saves and stores payment credentials for installment transactions, ensuring
compliance with COF best practices. Supported Card Types
These are the supported card types for processing credentialed transactions:
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsSuccessful Response
You must store the
network transaction ID
from the successful response message
to include in subsequent MIT authorization requests in order to associate the CIT to
the MIT. The network transaction ID is the processorInformation.networkTransactionId
field value.Store the
network transaction ID
, which is the processorInformation.networkTransactionId
field value, from the
successful response message. You must include the network transaction ID in
subsequent MIT authorization requests in order to associate the CIT to the MIT.Required Fields for Initial Customer-Initiated Installment
Payments with a PAN
Include these required fields to authorize an initial customer-initiated installment
payment using a PAN.
- Set the value totrue.
- Set the value tocustomer.
- Set the value tointernet,MOTO, or a payer authentication value.
- Set the value toinstall.
Card-Specific Fields for Authorizing Initial Installment Payments
Use this required field if you are authorizing an initial installment payment using the
card type referenced below.
- Mastercard
- processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason
- Set the value to9.
REST Example: Authorizing Initial Customer-Initiated Installment Payments with a
PAN
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "type": "customer", "credentialStoredOnFile": "true", "merchantInitiatedTransaction": { "reason": "9" //Mastercard only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" }
Customer-Initiated Installment Payment with TMS
TMS
An installment payment is a single purchase of goods or services
billed to a customer in multiple transactions over a period of time agreed to by you
and the customer, and sometimes, the issuing bank. The agreement enables you to
charge a specific amount at specified intervals. For customers, installment payments
provide greater purchasing power and lower impact on their monthly budget. For you,
offering installment payments at checkout can help increase the number of
successfully completed purchases.
Before you can accept installment payments, you and your
acquirer must agree on the maximum number of installments you can accept, which can
be different for each card type.
IMPORTANT
Do not use this document if you are using the
Installments service. When using the Installments service,
Cybersource
saves and stores payment credentials for installment transactions, ensuring
compliance with COF best practices. Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for CIT Installment Payments with
TMS
- Set the value toTOKEN_CREATE.
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymnentInstrument
- Set the value tointernet,MOTO, or a payer authentication value.
Card-Specific Fields for Authorizing Initial Installment Payments
Use this required field if you are authorizing an initial installment payment using the
card type referenced below.
- Mastercard
- processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason
- Set the value to9.
REST Example: CIT Installment Payment with TMS
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet" }, "paymentInformation": { "card": { "number": "411111111111XXXX", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6972267090226779103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6972267090226779103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6972267090226779103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62506622XNMR6Q1Y", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-13T19:51:49Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } }
Customer-Initiated Installment Payment with Enrollable
Network Tokens
An installment payment is a single purchase of goods or services
billed to a customer in multiple transactions over a period of time agreed to by you
and the customer, and sometimes, the issuing bank. The agreement enables you to
charge a specific amount at specified intervals. For customers, installment payments
provide greater purchasing power and lower impact on their monthly budget. For you,
offering installment payments at checkout can help increase the number of
successfully completed purchases.
IMPORTANT
Do not use this document if you are using the
Installments service. When using the Installments service,
Cybersource
saves and stores payment credentials for installment transactions, ensuring
compliance with COF best practices. Using Enrollable Network Tokens
The
Token Management Service
can enroll certain network tokens
,
known as device tokens, into an instrument identifier token for future payments.
Device tokens
store and encrypt card-on-file information which enables
customers to make quick and easy purchases using their mobile device. When
authorizing a credentialed payment with a device token, you must create and store
the device token in a TMS
instrument identifier token. To
do this, include the device token information in the paymentInformation.tokenizedCard
fields and set the token creation
fields to create an instrument identifier token.Follow-on merchant-initiated transactions are performed using the created instrument
identifier as the payment information. For more information about how to request a
merchant-initiated transaction, see Merchant-Initiated Installment Payment with TMS.
Device tokens are also known as
digital payments
, digital wallets
, and
tokenized cards
.Network Token Types
In your request, include the
processingInformation.paymentSolution
field to identify the device
token type you are using, and set it to one of these possible values:- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for a CIT Installment Payment with
Enrollable Network Tokens
- paymentInformation.tokenizedCard.number
- Set the value to1.
- Set the value toTOKEN_CREATE.
- Set the value toinstrumentIdentifier.
- Set the value tointernet.
- Set to one of these possible values:
- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
Example: CIT Installment Payments with Enrollable Network
Tokens
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } }
Merchant-Initiated Installment Payments with PAN
After the initial CIT installment payment, subsequent installment payments are
merchant-initiated transactions (MITs).
Prerequisites
The first transaction in an installment payment is a
customer-initiated
transaction
(CIT). Before you can perform a subsequent merchant-initiated
transaction
(MIT), you must store the customer's credentials for later use.
Before you can store the user's credentials, you must get the customer's consent to
store their private information. This process is also known as establishing a
relationship with the customer.Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing Merchant-Initiated Subsequent Installment Payments
Use these required fields to authorize merchant-initiated subsequent installment
payments.
- Set the value totrue.
- Set the value tomerchant.
- Set the value toinstall.
REST Example: Authorizing Merchant-Initiated Subsequent Installment Payments
Request
{ "processingInformation": { "commerceIndicator": "install", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "reason": "9", "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" //Discover Only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Merchant-Initiated Installment Payment with TMS
TMS
This section describes how to process a merchant-initiated installment payment using these
TMS
token types:- Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } }
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token.
- Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } }
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID.
- "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }
- For more information about thisTMStoken type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
Prerequisites
The first transaction in an installment payment is a
customer-initiated
transaction
(CIT). Before you can perform a subsequent merchant-initiated
transaction
(MIT), you must store the customer's credentials for later use.
Before you can store the user's credentials, you must get the customer's consent to
store their private information. This process is also known as establishing a
relationship with the customer.Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for MIT Installment Payments with TMS
TMS
Include these Required Fields
- paymentInformation.[tokentype].id
- Where[tokentype]is theTMStoken type you are using:
- Set the value toinstall.
Instrument Identifier Required Fields
If you are using the
paymentInformation.instrumentIdentifier.id
token, include these required fields in addition to the required fields listed
above.Example: MIT with TMS Instrument Identifier Token
TMS
Instrument Identifier TokenRequest
{ "processingInformation": { "commerceIndicator": "install" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2031" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Recurring Payments
A recurring payment is a credentials-on-file (COF) transaction in a series of payments
that you bill to a customer for a fixed amount at regular intervals that do not exceed
one year between transactions. The series of recurring payments is the result of an
agreement between you and the customer for the purchase of goods or services that are
provided at regular intervals. Recurring payments are also known as
subscriptions
.Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.
Recurring Billing Service for Recurring Payments
IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer
Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for
recurring transactions, ensuring compliance with COF best practices.
Customer-Initiated Recurring Payment with PAN
A recurring payment is a credentials-on-file (COF) transaction in a
series of payments that you bill to a customer at a fixed amount, at regular
intervals that do not exceed one year between transactions. The series of recurring
payments is the result of an agreement between you and the customer for the purchase
of goods or services that are provided at regular intervals.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- Visa
Mastercard uses standing order and subscription payments instead of recurring
payments. See Mastercard Standing Order Payments and
Mastercard Subscription Payments.
Recurring Billing Service for Recurring Payments
IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer
Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for
recurring transactions, ensuring compliance with COF best practices.
Address Verification Service for Recurring Payments
If your processor supports the Address Verification Service (AVS), then the AVS
should verify every authorization request.
Cybersource
recommends
checking the AVS's results for the first recurring payment to ensure that the
payment information is accurate and to reduce the risk of fraud.You must determine how to handle the AVS results for any subsequent recurring
payments that are not the same as the already-verified billing address information
from the first recurring payment.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsSuccessful Response
You must store the
network transaction ID
from the successful response message
to include in subsequent MIT authorization requests in order to associate the CIT to
the MIT. The network transaction ID is the processorInformation.networkTransactionId
field value.Store the
network transaction ID
, which is the processorInformation.networkTransactionId
field value, from the
successful response message. You must include the network transaction ID in
subsequent MIT authorization requests in order to associate the CIT to the MIT.Required Fields for Authorizing a Customer-Initiated Recurring Payment with PAN
Use these required fields to request an initial customer-initiated recurring payment.
- Set the value totrue.
- Set the value tocustomer.
- Set the value tointernet, a payer authentication value, orMOTO.
- processingInformation. recurringOptions. firstRecurringPayment
- Set the value totrue.
REST Example: Authorizing a Customer-Initiated Recurring Payment with a PAN
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" }
Customer-Initiated Recurring Payment with TMS
TMS
A recurring payment is a credentials-on-file (COF) transaction in a
series of payments that you bill to a customer at a fixed amount, at regular
intervals that do not exceed one year between transactions. The series of recurring
payments is the result of an agreement between you and the customer for the purchase
of goods or services that are provided at regular intervals.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- Visa
Mastercard uses standing order and subscription payments instead of recurring
payments. See Mastercard Standing Order Payments and
Mastercard Subscription Payments.
Recurring Billing Service for Recurring Payments
IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer
Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for
recurring transactions, ensuring compliance with COF best practices.
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Address Verification Service for Recurring Payments
If your processor supports the Address Verification Service (AVS), then the AVS
should verify every authorization request.
Cybersource
recommends
checking the AVS's results for the first recurring payment to ensure that the
payment information is accurate and to reduce the risk of fraud.You must determine how to handle the AVS results for any subsequent recurring
payments that are not the same as the already-verified billing address information
from the first recurring payment.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Customer-Initiated
Recurring Payment with TMS
TMS
Use these required fields to request a customer-initiated recurring payment with
TMS
.- Set the value toTOKEN_CREATE.
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymentInstrument
- Set the value tointernet,MOTO, or a payer authentication value.
- Set the value totrue.
REST Example: Authorizing a Customer-Initiated Recurring Payment with TMS
TMS
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer" ], "commerceIndicator": "internet", "recurringOptions": { "firstRecurringPayment": true } }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976858134106105703954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/captures" } }, "clientReferenceInformation": { "code": "1697685813462" }, "id": "6976858134106105703954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62698397FNN143CC", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T03:23:33Z", "tokenInformation": { "customer": { "id": "080A3A742BF87171E063A2598D0AEABE" } } }
Customer-Initiated Recurring Payment with Enrollable Network Tokens
A recurring payment is a credentials-on-file (COF) transaction in a
series of payments that you bill to a customer at a fixed amount, at regular
intervals that do not exceed one year between transactions. The series of recurring
payments is the result of an agreement between you and the customer for the purchase
of goods or services that are provided at regular intervals.
Mastercard uses standing order and subscription payments instead of recurring
payments. See Mastercard Standing Order Payments and
Mastercard Subscription Payments.
Recurring Billing Service for Recurring Payments
IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer
Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for
recurring transactions, ensuring compliance with COF best practices.
Using Enrollable Network Tokens
The
Token Management Service
can enroll certain network tokens
,
known as device tokens, into an instrument identifier token for future payments.
Device tokens
store and encrypt card-on-file information which enables
customers to make quick and easy purchases using their mobile device. When
authorizing a credentialed payment with a device token, you must create and store
the device token in a TMS
instrument identifier token. To
do this, include the device token information in the paymentInformation.tokenizedCard
fields and set the token creation
fields to create an instrument identifier token.Follow-on merchant-initiated transactions are performed using the created instrument
identifier as the payment information. For more information about how to request a
merchant-initiated transaction, see Merchant-Initiated Recurring Payments with TMS.
Device tokens are also known as
digital payments
, digital wallets
, and
tokenized cards
.Network Token Types
In your request, include the
processingInformation.paymentSolution
field to identify the device
token type you are using, and set it to one of these possible values:- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Customer-Initiated
Recurring Payments with Enrollable Network Tokens
- Set the value to1.
- Set the value toTOKEN_CREATE.
- Set the value toinstrumentIdentifier.
- Set the value tointernet,MOTO, or a payer authentication value.
- Set to one of these possible values:
- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
REST Example: Authorizing a Customer-Initiated Recurring
Payment with Enrollable Network Tokens
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } }
Merchant-Initiated Recurring Payments with PAN
After the initial recurring payment (CIT), subsequent recurring payments are
merchant-initiated transactions (MITs).
Prerequisites
The first transaction in a recurring payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the
customer's credentials, you must get their consent to store their private
information. This is also known as establishing a relationship with the
customer.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- Visa
Mastercard uses standing order and subscription payments instead of recurring
payments. See Mastercard Standing Order Payments and
Mastercard Subscription Payments.
Address Verification Service for Recurring Payments
If your processor supports the Address Verification Service (AVS), then the AVS
should verify every authorization request.
Cybersource
recommends
checking the AVS's results for the first recurring payment to ensure that the
payment information is accurate and to reduce the risk of fraud.You must determine how to handle the AVS results for any subsequent recurring
payments that are not the same as the already-verified billing address information
from the first recurring payment.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Merchant-Initiated Recurring Payment
Use these required fields to authorize subsequent recurring payments.
- For Discover and American Express cards, use the transaction ID from the original transaction. For Visa, use the last successful transaction ID.
- Set the value totrue.
- Set the value tomerchant.
- Set the value torecurring.
Card-Specific Required Fields for Authorizing Subsequent Recurring Payments
Some card companies require additional information when making authorizations with stored credentials.
Discover
Include the authorization amount from the original transaction in this field:
- processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction. originalAuthorizedAmount
Mastercard
Mastercard supports subscription and standing order payments instead of recurring
payments.
REST Example: Authorizing a Merchant-Initiated Recurring Payment
Request
{ "processingInformation": { "commerceIndicator": "recurring", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" //Discover Only } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Merchant-Initiated Recurring Payments with TMS
TMS
After the customer-initiated recurring payment, you can send merchant-initiated recurring
payments using one or more
TMS
token types: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } }
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token.
- Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } }
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID.
- "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }
- For more information about thisTMStoken type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
Prerequisites
The first transaction in a recurring payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the
customer's credentials, you must get their consent to store their private
information. This is also known as establishing a relationship with the
customer.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- Mastercard
- Visa
Mastercard uses standing order and subscription payments instead of recurring
payments. See Mastercard Standing Order Payments and
Mastercard Subscription Payments.
Address Verification Service for Recurring Payments
If your processor supports the Address Verification Service (AVS), then the AVS
should verify every authorization request.
Cybersource
recommends
checking the AVS's results for the first recurring payment to ensure that the
payment information is accurate and to reduce the risk of fraud.You must determine how to handle the AVS results for any subsequent recurring
payments that are not the same as the already-verified billing address information
from the first recurring payment.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Merchant-Initiated
Recurring Payments with TMS
TMS
Use these required fields to authorize subsequent recurring payments.
- paymentInformation.[tokentype].id
- Where[tokentype]is theTMStoken type you are using:
- Set the value torecurring.
Instrument Identifier Required Fields
If you are using the
paymentInformation.instrumentIdentifier.id
token, include these required fields in addition to the required fields listed
above.Card-Specific Field
Some card companies require additional fields when making authorizations with stored
credentials. Include this field if you are using these card types:
- Discover
- processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount
- Mastercard
- Mastercard supports subscription and standing order payments instead of recurring payments.
REST Example: Authorizing a Merchant-Initiated Recurring
Payment with a TMS Instrument Identifier
TMS
Instrument IdentifierRequest
{ "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2025" }, "instrumentIdentifier": { "id": "4111xxxxxxxxxxxx" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
REST Example: Authorizing a Merchant-Initiated Recurring
Payment with TMS Payment Instrument
TMS
Payment InstrumentRequest
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "paymentInstrument": { "id": "07DB0915C20F2DDBE063A2598D0A6F26" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6974839908106304103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6974839908106304103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6974839908106304103955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6974839908106304103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "07DB0915C20F2DDBE063A2598D0A6F26" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62599243NNMR6324", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-16T19:19:51Z" }
REST Example: Authorizing a Merchant-Initiated Recurring
Payment with a TMS Customer Token
TMS
Customer TokenRequest
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "recurring" }, "paymentInformation": { "customer": { "id": "07DB50E35AE11DA2E063A2598D0A9995" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6974846967476340503955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6974846967476340503955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6974846967476340503955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6974846967476340503955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62599950BNN133LK", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-16T19:31:36Z" }
Mastercard Standing Order Payments
A standing order payment is a recurring COF transaction that is a variable amount at a
regular interval, such as a utility bill, not to exceed one year between transactions.
The series of recurring payments is the result of an agreement between you and the
customer for the purchase of goods or services that are provided at regular
intervals.
Mastercard Initial CIT Standing Order Payment
The first transaction in a standing order payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the user's
credentials, you must get the customer's consent to store their private information.
This process is also known as establishing a relationship with the customer.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsSuccessful Response
You must store the
network transaction ID
from the successful response message
to include in subsequent MIT authorization requests in order to associate the CIT to
the MIT. The network transaction ID is the processorInformation.networkTransactionId
field value.Store the
network transaction ID
, which is the processorInformation.networkTransactionId
field value, from the
successful response message. You must include the network transaction ID in
subsequent MIT authorization requests in order to associate the CIT to the MIT.Required Fields for Authorizing Initial CIT Standing Order Payments
Use these required fields to authorize initial customer-initated standing order
payments.
- Set the value totrue.
- Set the value tocustomer.
- Set the value tointernet,MOTO, or a payer authentication value.
- Set the value to8.
REST Example: Authorizing Initial CIT Standing Order Payments
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer", "merchantInitiatedTransaction": { "reason": "8" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "5555xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Mastercard Initial CIT Standing Order Payment with TMS
TMS
The first transaction in a standing order payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the user's
credentials, you must get the customer's consent to store their private information.
This process is also known as establishing a relationship with the customer.
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing Initial CIT Standing Order Payments with TMS
TMS
- Set the value toTOKEN_CREATE
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymentInstrument
- Set the value to8.
- Set the value tointernet,MOTO, or a payer authentication value.
REST Example: Authorizing Initial CIT Standing Order Payments with TMS
TMS
Request
{ "processingInformation": { "actionList": ["TOKEN_CREATE"], "actionTokenTypes": ["customer"], "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "8" } } } }, "paymentInformation": { "card": { "number": "555555555555xxxx", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Sunnyville", "administrativeArea": "CA", "postalCode": "55555", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7064959411486706503954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7064959411486706503954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7064959411486706503954/captures" } }, "clientReferenceInformation": { "code": "1706495941197" }, "id": "7064959411486706503954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "680915409RRMGL34", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-29T02:39:01Z", "tokenInformation": { "customer": { "id": "100D6CDA178DD64DE063A2598D0AD3D5" } } }
Mastercard Subscription Payments
A subscription payment is a recurring COF transaction that is processed at a fixed amount at regular intervals not to exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals.
Mastercard CIT Initial Subscription Payment
The first transaction in a subscription payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the user's
credentials, you must get the customer's consent to store their private information.
This process is also known as establishing a relationship with the customer.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsSuccessful Response
You must store the
network transaction ID
from the successful response message
to include in subsequent MIT authorization requests in order to associate the CIT to
the MIT. The network transaction ID is the processorInformation.networkTransactionId
field value.Store the
network transaction ID
, which is the processorInformation.networkTransactionId
field value, from the
successful response message. You must include the network transaction ID in
subsequent MIT authorization requests in order to associate the CIT to the MIT.Required Fields for Authorizing CIT Initial Subscription Payments
- Set the value totrue.
- Set the value tocustomer.
- Set the value torecurring.
- Set the value to7.
REST Example: Authorizing Initial CIT Subscription Payments
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "type": "customer", "credentialStoredOnFile": "true", "merchantInitiatedTransaction": { "reason": "7" } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Mastercard CIT Initial Subscription Payment with TMS
TMS
The first transaction in a subscription payment is a customer-initiated transaction
(CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you
must store the customer's credentials for later use. Before you can store the user's
credentials, you must get the customer's consent to store their private information.
This process is also known as establishing a relationship with the customer.
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing CIT Initial Subscription Payments with TMS
TMS
- Set the value toTOKEN_CREATE
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymentInstrument
- Set the value torecurring.
- Set the value to7.
REST Example: Authorizing Initial CIT Subscription Payments
with TMS
Request
{ "processingInformation": { "actionList": ["TOKEN_CREATE"], "actionTokenTypes": ["customer"], "commerceIndicator": "recurring", "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "reason": "7" } } } }, "paymentInformation": { "card": { "number": "555555555555xxxx", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Sunnyville", "administrativeArea": "CA", "postalCode": "55555", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7064946846256410103954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7064946846256410103954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7064946846256410103954/captures" } }, "clientReferenceInformation": { "code": "1706494684667" }, "id": "7064946846256410103954", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "68091233JRRDUQ34", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-29T02:18:04Z", "tokenInformation": { "customer": { "id": "100D1DC40CC7C803E063A2598D0A29BD" } } }
Unscheduled COF Payments
An unscheduled credentials-on-file (COF) transaction uses stored payment information for a
fixed or variable amount that does not occur regularly. An account top-up is one kind of
unscheduled COF.
Customer-Initiated Unscheduled COF Payment with PAN
An unscheduled credentials-on-file (COF) transaction uses stored
payment information for a fixed or variable amount that does not occur regularly. An
account top-up is one kind of unscheduled COF.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsSuccessful Response
You must store the
network transaction ID
from the successful response message
to include in subsequent MIT authorization requests in order to associate the CIT to
the MIT. The network transaction ID is the processorInformation.networkTransactionId
field value.Store the
network transaction ID
, which is the processorInformation.networkTransactionId
field value, from the
successful response message. You must include the network transaction ID in
subsequent MIT authorization requests in order to associate the CIT to the MIT.Required Fields for a Customer-Initiated Unscheduled COF Payment with PAN
These fields are required in a subsequent authorization request for an initial unscheduled
COF payment:
- Set the value totrue.
- Set the value tocustomer.
- Set the value tointernet,MOTO, or a payer authentication value.
REST Example: Customer-Initiated Unscheduled COF Payment with
PAN
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "credentialStoredOnFile": "true", "type": "customer" } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6528187198946076303004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6528187198946076303004/captures" } }, "clientReferenceInformation": { "code": "1652818719876" }, "id": "6528187198946076303004", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "63165088Z3AHV91G", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-17T20:18:40Z" }
Customer-Initiated Unscheduled COF Payments with TMS
TMS
An unscheduled credentials-on-file (COF) transaction uses stored
payment information for a fixed or variable amount that does not occur regularly. An
account top-up is one kind of unscheduled COF.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Creating a TMS Token
TMS
TokenWhen sending the initial CIT, you can create a
TMS
token to
store the customer's credentials for the subsequent MITs. To create a TMS
token, include the
processingInformation.actionTokenTypes
field in the
authorization request. Set the field to one of these values based on the TMS
token type you want to create: - Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "customer" ]
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ]
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID.
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ]
- For more information about this TMS token type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization:
- "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ]
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for CIT Unscheduled COF Payments with TMS
TMS
- Set the value toTOKEN_CREATE
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymnentInstrument
- Set the value tointernet,MOTO, or a payer authentication value.
REST Example: Initial CIT Unscheduled COF Payment in TMS
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer" ], "commerceIndicator": "internet" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976866073586557303955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976866073586557303955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976866073586557303955/captures" } }, "clientReferenceInformation": { "code": "1697686607441" }, "id": "6976866073586557303955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699023FNN143DG", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T03:36:47Z", "tokenInformation": { "customer": { "id": "080A6C3842C72DCBE063A2598D0AA98B" } } }
Customer-Initiated Unscheduled COF Payment with Enrollable Network Tokens
An unscheduled credentials-on-file (COF) transaction uses stored
payment information for a fixed or variable amount that does not occur regularly. An
account top-up is one kind of unscheduled COF.
Using Enrollable Network Tokens
The
Token Management Service
can enroll certain network tokens
,
known as device tokens, into an instrument identifier token for future payments.
Device tokens
store and encrypt card-on-file information which enables
customers to make quick and easy purchases using their mobile device. When
authorizing a credentialed payment with a device token, you must create and store
the device token in a TMS
instrument identifier token. To
do this, include the device token information in the paymentInformation.tokenizedCard
fields and set the token creation
fields to create an instrument identifier token.Follow-on merchant-initiated transactions are performed using the created instrument
identifier as the payment information. For more information about how to request a
merchant-initiated transaction, see Merchant-Initiated Unscheduled COF Payments with TMS.
Device tokens are also known as
digital payments
, digital wallets
, and
tokenized cards
.Network Token Types
In your request, include the
processingInformation.paymentSolution
field to identify the device
token type you are using, and set it to one of these possible values:- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for CIT Unscheduled COF Payment with
Enrollable Network Tokens
- paymentInformation.tokenizedCard.number
- Set the value to1.
- Set the value toTOKEN_CREATE.
- Set the value toinstrumentIdentifier.
- Set the value tointernet,MOTO, or a payer authentication value.
- processingInformation.paymentSolution
- Set to one of these possible values:
- 001: Apple Pay
- 004:CybersourceIn-App Solution
- 005: Masterpass
- 006: Android Pay
- 007: Chase Pay
- 008: Samsung Pay
- 012: Google Pay
- 014: Mastercard credential-on-file (COF) payment network token
- 015: Visa credential-on-file (COF) payment network token
- 027: Click to Pay
- visacheckout:Visa Click to Pay.
REST API Example: CIT Unscheduled COF
Payment with Enrollable Network Tokens
REST API
Example: CIT Unscheduled COF
Payment with Enrollable Network TokensRequest
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "commerceIndicator": "internet", "paymentSolution": "001" }, "paymentInformation": { "tokenizedCard": { "number": "4111111111111111", "expirationMonth": "02", "expirationYear": "2025", "transactionType": "1" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "address1": "123 Happy St", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78757", "country": "US", "email": "test@cybs.com", "phoneNumber": "444-4444-4444" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7094060020036241803954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7094060020036241803954/captures" } }, "clientReferenceInformation": { "code": "1709406002076" }, "id": "7094060020036241803954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60616704ST7Q27K2", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-02T19:00:02Z", "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7010000000016241111" } } }
Merchant-Initiated Unscheduled COF Payments with PAN
After the initial CIT unscheduled COF payment, subsequent unscheduled COF transactions are
merchant-initiated transactions (MITs).
Prerequisites
The first transaction in an unscheduled COF payment is a customer-initiated
transaction (CIT). Before you can perform a subsequent merchant-initiated
transaction (MIT), you must store the customer's credentials for later use. Before
you can store the user's credentials, you must get the customer's consent to store
their private information. This process is also known as establishing a relationship
with the customer.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing Subsequent MIT Unscheduled COF Payments
These fields are required in a subsequent authorization request for a subsequent
unscheduled COF payment:
- processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionID
- American Express: set to the transaction ID from the original transaction.
- Discover: set to the transaction ID from the original transaction.
- Visa: set to the last successful transaction ID.
- Set the value to10.
- Required only forAmerican Express,Discover and Mastercard.
- Set the value totrue.
- Set the value tomerchant.
- Set the value tointernet.
Optional Field for Authorizing Subsequent MIT Unscheduled COF Transactions
You can use these optional fields to include additional information when authorizing
request for an MIT unscheduled COF transaction:
- processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.originalAuthorizedAmount
- Supported only for Discover for subsequent MIT unscheduled COF transactions.
REST Example: Authorizing Subsequent MIT Unscheduled COF Payments
Request
{ "processingInformation": { "commerceIndicator": "internet", "authorizationOptions": { "initiator": { "storedCredentialUsed": "true", "type": "merchant", "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999", "originalAuthorizedAmount": "100" <--Discover Only--> } } } }, "orderInformation": { "billTo": { "firstName": "John", "lastName": "Doe", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "country": "US", "phoneNumber": "5554327113", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111xxxxxxxxxxxx", "expirationMonth": "12" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6530824710046809304002" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6530824710046809304002/captures" } }, "clientReferenceInformation": { "code": "1653082470983" }, "id": "6530824710046809304002", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "card": { "type": "002" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "authIndicator": "1", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "79710341A39WTT5W", "status": "AUTHORIZED", "submitTimeUtc": "2022-05-20T21:34:31Z" }
Merchant-Initiated Unscheduled COF Payments with TMS
TMS
After the customer-initiated unscheduled COF payment, you can send merchant-initiated
unscheduled COF payments using one or more
TMS
token types:- Customer
- Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
- Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } }
- For more information about thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper Guide
- Payment Instrument
- Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token.
- Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID.
- "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } }
- For more information about thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper Guide
- Instrument Identifier
- Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID.
- "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }
- For more information about thisTMStoken type, see Instrument Identifier Token in the.Token Management ServiceDeveloper Guide
Prerequisites
The first transaction in an unscheduled COF payment is a customer-initiated
transaction (CIT). Before you can perform a subsequent merchant-initiated
transaction (MIT), you must store the customer's credentials for later use. Before
you can store the user's credentials, you must get the customer's consent to store
their private information. This process is also known as establishing a relationship
with the customer.
Supported Card Types
These are the supported card types for processing credentialed transactions:
- American Express
- Mastercard
- Visa
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for MIT Unscheduled COF Payments with
TMS
TMS
Include these Required Fields
- paymentInformation.[tokentype].id
- Where[tokentype]is theTMStoken type you are using:
- Set the value to10.
- Required only forAmerican Express,Discover, and Mastercard.
- Set the value tointernet.
Instrument Identifier Required Fields
If you are using the
paymentInformation.instrumentIdentifier.id
token, include these required fields in addition to the required fields listed
above.Card-Specific Field
The listed card type requires an additional field.
- Discover
- processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount
- Provide the original transaction amount.
Example: MIT Unscheduled COF Payment with TMS Instrument Identifier
Request
{ "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "card": { "expirationMonth": "12", "expirationYear": "2031" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976892714556134003954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976892714556134003954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976892714556134003954/captures" } }, "clientReferenceInformation": { "code": "1697689271513" }, "id": "6976892714556134003954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699554NNMR6X7R", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:21:11Z" }
Example: MIT Unscheduled COF Payment with TMS Payment Instrument
Request
{ "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976891300676431103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976891300676431103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976891300676431103955/captures" } }, "clientReferenceInformation": { "code": "1697689130124" }, "id": "6976891300676431103955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE120369A7947E063A2598D0A718F" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699372XNMR85HS", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:18:50Z" }
Example: MIT Unscheduled COF Payment with TMS Customer
Request
{ "processingInformation": { "commerceIndicator": "internet" }, "paymentInformation": { "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976889582016147703955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976889582016147703955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976889582016147703955/captures" } }, "clientReferenceInformation": { "code": "1697688958296" }, "id": "6976889582016147703955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "080AE6DB37B09557E063A2598D0AA4C9" }, "card": { "type": "001" }, "customer": { "id": "080AC9AB60C92AA2E063A2598D0A0C74" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processingInformation": { "paymentSolution": "015" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013022298169667504231315", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62699842BNN13VA0", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T04:15:58Z" }
Token Management Service Processing
Token Management Service
ProcessingThis section provides the information you need in order to process
Token Management Service
authorization and credit transactions.IMPORTANT
Due to mandates from the Reserve Bank of India, Indian merchants cannot
store personal account numbers (PANs). Use network tokens instead. For more information
on network tokens, see the Network Tokenization section of the
Authorizing a Payment with a Customer Token
This section provides the information you need to authorize a payment with a customer
token.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments Test:
POST
https://apitest.cybersource.com
/pts/v2/payments Production in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with a Customer Token
- paymentInformation.customer.id
- Set to the ID of the customer token you want to use.
Related Information
REST Example: Authorizing a Payment with a Customer Token
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
The request response returns the payment instrument and shipping address IDs that are used
as the customer's defaults.
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055928871556818104953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055928871556818104953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055928871556818104953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055928871556818104953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "shippingAddress": { "id": "0F35F0D99AD088B5E063A2598D0AE066" }, "paymentInstrument": { "id": "0F35E9CFEA463E34E063A2598D0A3FC2" }, "card": { "type": "001" }, "customer": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67467352CRIISD1G", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T15:48:07Z" }
REST Example: Authorizing a Payment Using a Customer Token
Linked to a Network Token
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F60328413BAB09A4E053AF598E0A33DB" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } } }
Response to a Successful Request
The request response returns the payment instrument and shipping address IDs that are
used as the customer's defaults.
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6778647071126384904953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6778647071126384904953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6778647071126384904953/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6778647071126384904953", "issuerInformation": { "responseRaw": "0110322000000E100002000....." }, "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "paymentInformation": { "tokenizedCard": { "type": "002" }, "instrumentIdentifier": { "id": "7020000000010603216", "state": "ACTIVE" }, "shippingAddress": { "id": "F60328413BAE09A4E053AF598E0A33DB" }, "paymentInstrument": { "id": "F6032841BE33098EE053AF598E0AB0A5" }, "card": { "type": "002" }, "customer": { "id": "F60328413BAB09A4E053AF598E0A33DB" } }, "pointOfSaleInformation": { "terminalId": "08244117" }, "processingInformation": { "paymentSolution": "014" }, "processorInformation": { "paymentAccountReferenceNumber": "50015OU4U5UYXLV127XTONYN49CL1", "merchantNumber": "000844028303882", "approvalCode": "831000", "networkTransactionId": "0602MCC603474", "transactionId": "0602MCC603474", "responseCode": "00", "avs": { "code": "Y", "codeRaw": "Y" } }, "reconciliationId": "EUHW1EMHIZ3O", "status": "AUTHORIZED", "submitTimeUtc": "2023-03-03T17:31:48Z" }
Authorizing a Payment with a Non-Default Shipping
Address
This section provides the information you need in order to make a payment with a
non-default shipping address.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments Test:
POST
https://apitest.cybersource.com
/pts/v2/payments Production in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with a Non-Default Shipping Address
- paymentInformation.customer.id
- Set to the ID of the customer token you want to use.
- paymentInformation.shippingAddress.id
- Set to the ID of the shipping address token you want to use.
Related Information
REST Example: Authorizing a Payment with a Non-Default Shipping Address
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055949037316786904953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055949037316786904953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055949037316786904953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055949037316786904953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014831523", "state": "ACTIVE" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" }, "paymentInstrument": { "id": "F45FE45E7993C7DBE053A2598D0AED19" }, "card": { "type": "001" }, "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "674679208RIKQ52K", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:21:44Z" }
Authorizing a Payment with a Non-Default Payment
Instrument
This section provides the information you need in order to authorize a payment with a
non-default payment instrument.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments Test:
POST
https://apitest.cybersource.com
/pts/v2/paymentsProduction in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with a Non-Default Payment Instrument
- Set to the ID of the payment instrument token you want to use.
Related Information
Optional Fields for Authorizing a Payment with a Non-Default Payment Instrument
You can use these optional fields to include additional information when authorizing
a payment with a non-default payment instrument.
Related Information
REST Example: Authorizing a Payment with a Non-Default
Payment Instrument
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055952648586653304951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055952648586653304951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055952648586653304951/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055952648586653304951", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67468244CRIL0U0Y", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:27:45Z" }
Authorizing a Payment with a Payment Instrument
This section provides the information you need in order to authorize a payment with a
payment instrument.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments Test:
POST
https://apitest.cybersource.com
/pts/v2/paymentsProduction in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with a Payment Instrument
- Set to the ID of the payment instrument token you want to use.
Related Information
Optional Fields for Authorizing a Payment with a Payment Instrument
You can use these optional fields to include additional information when authorizing
a payment with a payment instrument.
Related Information
REST Example: Authorizing a Payment with a Payment Instrument
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6765713628736138103955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6765713628736138103955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6765713628736138103955/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "6765713628736138103955", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" }, "card": { "type": "001" }, "customer": { "id": "F4D5E715F75E9910E053A2598D0A7278" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "60561224BE37KN5W", "status": "AUTHORIZED", "submitTimeUtc": "2023-02-16T18:16:03Z" }
Authorize a Payment with an Instrument Identifier
This section provides the information you need in order to authorize a payment with an
instrument identifier token.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments Test:
POST
https://apitest.cybersource.com
/pts/v2/paymentsProduction in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with an Instrument Identifier
- paymentInformation.instrumentIdentifier.id
- Set to the ID of the instrument identifier token you want to use.
Related Information
REST Example: Authorizing a Payment with an Instrument
Identifier
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055955288186053404953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055955288186053404953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055955288186053404953/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055955288186053404953", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "1" } }, "reconciliationId": "67468271CRIL0U24", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:32:09Z" }
REST Example: Authorizing a Payment with an Instrument Identifier While Creating
TMS Tokens
TMS
TokensRequest
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer", "paymentInstrument", "shippingAddress" ] }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "4158880000" }, "shipTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7114679840376687203955/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7114679840376687203955" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7114679840376687203955/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "7114679840376687203955", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "623971212U7PN4IU", "status": "AUTHORIZED", "submitTimeUtc": "2024-03-26T15:46:24Z", "tokenInformation": { "shippingAddress": { "id": "14930C904FC4D97BE063A2598D0AE0F1" }, "paymentInstrument": { "id": "149310A4A924E911E063A2598D0A47AD" }, "customer": { "id": "14930C904FC1D97BE063A2598D0AE0F1" } } }
Authorize a Payment While Ignoring Network Token
This section describes how to authorize a payment ignoring a network token.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/paymentsProduction:
POST
https://api.cybersource.com
/pts/v2/payments Production in India:
POST
https://api.in.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment While Ignoring Network Token
- Set value toignore.
Related Information
REST Example: Authorizing a Payment While Ignoring Network Token
Request
{ "clientReferenceInformation": { "code": "RTS-Auth" }, "paymentInformation": { "card": { "expirationYear": "2031", "expirationMonth": "12", "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "1.00" } }, "processingInformation": { "capture": "false", "commerceIndicator": "internet" }, "tokenInformation": { "networkTokenOption": "ignore" } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6769913443166412604951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6769913443166412604951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6769913443166412604951/captures" } }, "clientReferenceInformation": { "code": "RTS-Auth" }, "id": "6769913443166412604951", "orderInformation": { "amountDetails": { "authorizedAmount": "1.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014911515", "state": "ACTIVE" }, "shippingAddress": { "id": "F537CE8DBA2F032CE053AF598E0A64F2" }, "paymentInstrument": { "id": "F537E3D12322416EE053AF598E0AD771" }, "card": { "type": "001" }, "customer": { "id": "F537CE8DBA2C032CE053AF598E0A64F2" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013019326121174070050420", "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "744295942E2LY3F8", "status": "AUTHORIZED", "submitTimeUtc": "2023-02-21T14:55:44Z" }
Authorizing a Payment with a Legacy Token
This section describes how to authorize a payment with a legacy token.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Payment with a Legacy Token
- paymentInformation.legacyToken.id
- Include the ID of the legacy token you want to use to authorize a payment.
Related Information
REST Example: Authorizing a Payment with a Legacy Token
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "legacyToken": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "orderInformation": { "amountDetails": { "totalAmount": "22.00", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/7055956342476789004951/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/7055956342476789004951" }, "capture": { "method": "POST", "href": "/pts/v2/payments/7055956342476789004951/captures" } }, "clientReferenceInformation": { "code": "12345678" }, "id": "7055956342476789004951", "orderInformation": { "amountDetails": { "authorizedAmount": "22.00", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "67468431FRIIS246", "status": "AUTHORIZED", "submitTimeUtc": "2024-01-18T16:33:54Z" }
Making a Credit with a Customer Token
This section describes how to make a credit with a customer token.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits
Production:
POST
https://api.cybersource.com
/pts/v2/credits Production in India:
POST
https://api.in.cybersource.com
/pts/v2/creditsRequired Fields for Making a Credit with a Customer Token
- paymentInformation.customer.id
- Set to the ID of the customer token you want to use.
Related Information
REST Example: Making a Credit with a Customer Token
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055967677826132904951/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055967677826132904951" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055967677826132904951", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7030000000014831523", "state": "ACTIVE" }, "shippingAddress": { "id": "F45FD8DE51B99E9CE053A2598D0AFDFA" }, "paymentInstrument": { "id": "F45FE45E7993C7DBE053A2598D0AED19" }, "card": { "type": "001" }, "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "processorInformation": { "paymentAccountReferenceNumber": "V0010013019326121538313096266", "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67444961BRIL0BB8", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:52:48Z" }
Making a Credit with a Non-Default Payment
Instrument
This section describes how to make a credit with a non-default payment instrument.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits
Production:
POST
https://api.cybersource.com
pts/v2/credits Production in India:
POST
https://api.in.cybersource.com
pts/v2/creditsRequired Fields for Making a Credit with a Non-Default Payment Instrument
- Set to the ID of the payment instrument token that you want to use.
Related Information
Optional Fields for Making a Credit with a Non-Default Payment Instrument
You can use these optional fields to include additional information when making a
credit with a non-default payment instrument.
Related Information
REST Example: Making a Credit with a Non-Default Payment Instrument
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055968581386446104953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055968581386446104953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055968581386446104953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "0F3BB131F8143A58E063A2598D0AB921" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67445196PRILCQCN", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:54:18Z" }
Making a Credit with a Payment Instrument
This section describes how to make a credit with a payment instrument.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits
Production:
POST
https://api.cybersource.com
pts/v2/credits Production in India:
POST
https://api.in.cybersource.com
pts/v2/creditsRequired Fields for Making a Credit with a Payment Instrument
- Set to the ID of the payment instrument token you want to use.
Related Information
REST Example: Making a Credit with a Payment Instrument
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055969586686467104953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055969586686467104953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055969586686467104953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "F4D5E715F7BD9910E053A2598D0A7278" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67446174JRIKXXHB", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:55:59Z" }
Making a Credit with an Instrument Identifier
This section describes how to make a credit with an instrument identifier token.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/credits
Production:
POST
https://api.cybersource.com
pts/v2/credits Production in India:
POST
https://api.in.cybersource.com
pts/v2/creditsRequired Fields for Making a Credit with an Instrument Identifier
- Set to the ID of the payment instrument token you want to use.
Related Information
REST Example: Making a Credit with an Instrument Identifier
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055970261066212404951/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055970261066212404951" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "10.00" }, "id": "7055970261066212404951", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67445198PRILCQCQ", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:57:06Z" }
Making a Credit with a Legacy Token
This section describes how to make a credit with a legacy token.
Endpoint
Test:
POST
https://apitest.cybersource.com
/pts/v2/creditsProduction:
POST
https://api.cybersource.com
/pts/v2/credits Production in India:
POST
https://api.in.cybersource.com
/pts/v2/creditsRequired Fields for Making a Credit with a Legacy Token
- paymentInformation.legacyToken.id
- Include the ID of the legacy token that you want to use to authorize a payment.
Related Information
REST Example: Making a Credit with a Legacy Token
Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "legacyToken": { "id": "B21E6717A6F03479E05341588E0A303F" } }, "orderInformation": { "amountDetails": { "totalAmount": "22.00", "currency": "USD" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/7055970562096509704953/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/7055970562096509704953" } }, "clientReferenceInformation": { "code": "12345678" }, "creditAmountDetails": { "currency": "USD", "creditAmount": "22.00" }, "id": "7055970562096509704953", "orderInformation": { "amountDetails": { "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "responseCode": "100" }, "reconciliationId": "67444779FRILJT84", "status": "PENDING", "submitTimeUtc": "2024-01-18T16:57:36Z" }
Visa Bill Payments Processing
This section shows you how to process a Visa Bill Payment for authorization and credit
transactions.
Requirement
Before you process Visa Bill Payments, you must sign up with Visa to participate in the program.
Related Information
- See Visa Bill Payments for a description of the Visa Bill Payment program.
Visa Bill Payments Authorizations
This section shows you how to process a Visa Bill Payment authorization.
Field Specific to this Use Case
Include this field in a standard authorization request for a Visa Bill Payment:
- processingInformation.authorizationOptions.billPayment—Set the field totrue.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Processing a Visa Bill Payment Authorization
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value totrue.
Related Information
REST Example: Processing a Visa Bill Payment Authorization
Request
{ "orderInformation": { "billTo": { "country": "US", "lastName": "Smith", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Jane", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } }, "processingInformation": { "authorizationOptions": { "billPayment": "true" } } }
Response to a Successful Request
"_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6703681963696557903954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6703681963696557903954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6703681963696557903954/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6703681963696557903954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62246404OAIKS5EN", "status": "AUTHORIZED" }
Response to a Declined Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "errorInformation": { "reason": "PROCESSOR_ERROR", "message": "Invalid account" }, "id": "6583553837826789303954", "paymentInsightsInformation": { "responseInsights": { "categoryCode": "01", "category": "ISSUER_WILL_NEVER_APPROVE" } }, "processorInformation": { "systemTraceAuditNumber": "004544", "merchantNumber": "1231231222", "networkTransactionId": "431736869536459", "transactionId": "431736869536459", "responseCode": "111", "avs": { "code": "Y", "codeRaw": "Y" } }, "status": "DECLINED" }
Visa Bill Payments Captures
This section shows you how to process a Visa Bill Payment capture.
Field Specific to this Use Case
Include this field in a standard capture request for a Visa Bill Payment:
- processingInformation.authorizationOptions.billPayment—Set the field totrue.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/{id}
/capturesTest:
POST
https://apitest.cybersource.com
/pts/v2/payments/{id}
/capturesThe is the transaction ID
returned in the authorization response.
{id}
Required Fields for Capturing a Visa Bill Payment
- Set the value totrue.
Related Information
REST Example: Capturing a Visa Bill Payment
Request
{ "orderInformation": { "amountDetails": { "totalAmount": "100.00" }, "processingInformation": { "authorizationOptions": { "billPayment": "true" } } }
Response to a Successful Request
{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6662994431376681303954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6662994431376681303954" } }, "clientReferenceInformation": { "code": "1666299443215" }, "id": "6662994431376681303954", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }, "reconciliationId": "66535942B9CGT52U", "status": "PENDING", }
Visa Consumer Bill Payment Processing
This section shows you how to process a Visa Consumer Bill Payment.
Fields Specific to this Use Case
Include
this field
in a standard authorization when you request a Visa CBPS
authorization: - processingInformation.businessApplicationId
- Set the value toCB.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequirements
IMPORTANT
As a Visa CBPS provider you must comply with all Visa rules. For the Visa CBPS rules,
see Rule ID# 0030635 of the Visa Rules "Acquirer Responsibilities Related to
Consumer Bill Payment Service Providers" at visa-rules-public.pdf.
Before you process Visa CBPS payments, you must:
- Contact your acquirer to register your account for the Visa Consumer Bill Pay Service.
- ContactCybersourcecustomer support to have your account configured for this feature.
Related Information
- See Basic Authorizations.
Required Fields for Processing a Visa Consumer Bill Payment Service Authorization
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields
in this list are required. It is your responsibility to determine whether your
account is enabled to use this feature and which fields are required. For details
about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
- Set the value toCB.
Related Information
REST Example: Processing a Visa Consumer Bill Payment Service Authorization
Request
{ "orderInformation": { "billTo": { "country": "US", "lastName": "Smith", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Jane", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "usd" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } }, "processingInformation": { "businessApplicationId": "CB" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6703681963696557903954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6703681963696557903954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6703681963696557903954/captures" } }, "clientReferenceInformation": { "code": "MRC987654321" }, "id": "6703681963696557903954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62246404OAIKS5EN", "status": "AUTHORIZED" }
Response to a Declined Request
{ "clientReferenceInformation": { "code": "MRC987654321" }, "errorInformation": { "reason": "PROCESSOR_ERROR", "message": "Invalid account" }, "id": "6583553837826789303954", "paymentInsightsInformation": { "responseInsights": { "categoryCode": "01", "category": "ISSUER_WILL_NEVER_APPROVE" } }, "processorInformation": { "systemTraceAuditNumber": "004544", "merchantNumber": "1231231222", "networkTransactionId": "431736869536459", "transactionId": "431736869536459", "responseCode": "111", "avs": { "code": "Y", "codeRaw": "Y" } }, "status": "DECLINED" }