Payments

REST API
Barclays

Developer Guide
Cybersource Contact Information
For general information about our company, products, and services, go to https://www.cybersource.com.

For sales questions about any Cybersource service, email [email protected] or call 650-432-7350 or 888-330-2300 (toll free in
the United States).

For support information about any Cybersource service, visit the Support Center: https://www.cybersource.com/support

Copyright
© 2020. Cybersource Corporation. All rights reserved. Cybersource Corporation (“Cybersource”) furnishes this document and the
software described in this document under the applicable agreement between the reader of this document (“You”) and Cybersource
(“Agreement”). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly
set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not
be interpreted in any way as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability for any errors
that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict
accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the
Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in
any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of Cybersource.

Restricted Rights Legends

For Government or defense agencies:Use,duplication, or disclosure by the Government or defense agencies is subject to restrictions
as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and
NASA FAR Supplement.

For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in suparagraphs (a) through (d) of the
Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in Cybersource Corporation's
standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.

Trademarks
Authorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation. Cybersource,
Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, and Cybersource Connect are trademarks
and/or service marks of Cybersource Corporation. Visa, Visa International, Cybersource, the Visa logo, and the Cybersource logo
are the registered trademarks of Visa International in the United States and other countries. All other trademarks, service marks,
registered marks, or registered service marks are the property of their respective owners.

Condentiality Notice
This document is furnished to you solely in your capacity as a client of Cybersource and as a participant in the Visa payments system.

By accepting this document, you acknowledge that the information contained herein (the “Information”) is condential and subject
to the condentiality restrictions contained in Visa's operating regulations and/or other condentiality agreements, which limity our
use of the Information. You agree to keep the Information condential and not to use the Information for any purpose other than its
intended purpose and in your capacity as a customer of Cybersource or as a participant in the Visa payments system. The Information
may only be disseminated within your organization on a need-to-know basis to enable your participation in the Visa payments system.
Please be advised that the Information may constitute material non-public information under U.S. federal securities laws and that
purchasing or selling securities of Visa Inc. while being aware of material non-public information would constitute a violation of
applicable U.S. federal securities laws.

Revision
Version: 23.01
Contents

Contents

Recent Revisions to This Document............................................................................................... 7

About This Guide................................................................................................................................ 8
Introduction to Payments.................................................................................................................9
Payment Services..................................................................................................................... 9
Financial Institutions and Payment Networks..................................................................... 9
Merchant Financial Institutions (Acquirers).............................................................. 9
Issuing (Customer) Financial Institutions................................................................. 10
Payment Networks........................................................................................................ 10
Payment Processors...................................................................................................... 11
Payment Types.......................................................................................................................... 11
Co-Badged Cards.......................................................................................................... 11
Co-Branded Cards......................................................................................................... 11
Credit Cards....................................................................................................................11
Debit Cards..................................................................................................................... 11
Prepaid Cards................................................................................................................. 11
Private Label Cards.......................................................................................................12
Quasi-Cash..................................................................................................................... 12
Transaction Types................................................................................................................... 12
Card-Not-Present Transactions.................................................................................12
Card-Present Transactions......................................................................................... 12
Authorizations with Card Verication Numbers...................................................... 12
Token Management Service........................................................................................ 13
Payment Processing............................................................................................................... 14
Authorizations................................................................................................................14
Sales.................................................................................................................................16
Authorization Reversals................................................................................................17
Credits............................................................................................................................. 17
Capture or Credit Voids...............................................................................................19
Capture........................................................................................................................... 19
Basic Processing............................................................................................................................... 21
Captures................................................................................................................................... 21
Required Fields for Capturing a Payment Using the REST API............................... 21

Cybersource Contents 3
Contents

REST Interactive Example: Capturing a Payment..................................................... 21

REST Example: Capturing an Authorization.............................................................. 21
Multiple Partial Captures...................................................................................................... 22
Required Fields for Multiple Partial Captures..........................................................22
Basic Authorizations.............................................................................................................. 24
Required Fields for Processing Basic Authorizations Using the REST API.......... 24
Declined Authorizations.............................................................................................. 25
REST Interactive Example: Processing an Authorization....................................... 25
REST Example: Processing a Basic Authorization................................................... 25
Authorization with Line Itemization.................................................................................... 28
Required Fields............................................................................................................. 29
REST Example: Processing a Basic Authorization with Line Items....................... 29
Processing an Authorization with a Card Verication Number.......................................31
Required Fields for Processing Basic Authorizations with a Card
Verication Number Using the REST API.......................................................... 32
Optional Fields for an Authorization with a Card Verication Number............... 33
REST Example: Processing an Authorization with a CVN....................................... 33
Zero Amount Authorizations................................................................................................ 35
Required Fields for Processing Zero Amount Authorizations Using the REST
API............................................................................................................................35
REST Example: Processing a Zero Amount Authorization..................................... 36
Authorization with an SCA Exemption................................................................................ 37
Required Fields for an Authorization with an SCA Exemption Using the REST
API............................................................................................................................39
REST Example: Authorization with an SCA Exemption for Low Value
Transactions.......................................................................................................... 39
Sales.......................................................................................................................................... 41
Required Fields for Processing a Sale Using the REST API.................................... 41
REST Example: Requesting a Sale.............................................................................. 42
Authorization Reversals........................................................................................................ 44
Required Fields for Processing Authorization Reversals Using REST API........... 44
Example: Processing an Authorization Reversal Using the REST API................... 45
Refunds.................................................................................................................................... 46
Required Fields for Processing Refunds Using the REST API................................46
REST Interactive Example: Processing a Refund.....................................................46
Example: Processing a Refund Using the REST API................................................ 46
Credits......................................................................................................................................48
Required Fields for Processing a Credit Using the REST API................................ 48
REST Interactive Example: Processing a Credit...................................................... 49
REST Example: Processing a Credit.......................................................................... 49
Voids......................................................................................................................................... 50
Required Fields for Processing Voids Using REST APIs......................................... 50
REST Example: Processing a Void............................................................................... 51
Card-Present Authorizations.........................................................................................................52
Payer Authentication Processing..................................................................................................53
Visa Secure..............................................................................................................................53

Cybersource Contents 4
Contents

Required Fields for an Authorization with Visa Secure Using REST APIs............ 54
Example: Authorization with Visa Secure Using the REST API.............................. 55
JCB J/Secure.......................................................................................................................... 57
Required Fields for an Authorization using JCB J/Secure Authentication
with the REST API..................................................................................................57
Authorizing a JCB J/Secure Transaction Using REST APIs................................... 58
Example: Authorization with JCB J/Secure Using the REST API.......................... 58
Mastercard Identity Check.................................................................................................. 60
Required Fields for an Authorization with Mastercard Identity Check Using
REST APIs................................................................................................................ 61
Authorizing a Mastercard Identity Check Transaction Using REST APIs............. 62
Example: Authorizing Mastercard Identity Check Using the REST API................ 62
ProtectBuy...............................................................................................................................64
Authorizing a ProtectBuy Transaction..................................................................... 65
Example: Authorization with ProtectBuy Using the REST API............................... 65
Authorization with an SCA Exemption................................................................................ 67
Required Fields for an Authorization with an SCA Exemption Using the REST
API............................................................................................................................68
REST Example: Authorization with an SCA Exemption for Low Value
Transactions.......................................................................................................... 69
Credentialed Transactions............................................................................................................. 72
Customer-Initiated Transactions with Credentials on File............................................. 72
Storing Customer Credentials with a Customer-Initiated Transaction.............. 72
Using Stored Customer Credentials During a Customer-Initiated
Transaction.............................................................................................................75
Merchant-Initiated Transactions......................................................................................... 78
Debit and Prepaid Card Processing..............................................................................................79
Processing Debit and Prepaid Authorizations...................................................................79
Required Fields for Debit and Prepaid Authorizations Using REST APIs.............. 79
Optional Field for Debit and Prepaid Authorizations Using REST APIs................ 80
REST Example: Debit and Prepaid Authorizations...................................................80
Enabling Debit and Prepaid Partial Authorizations...........................................................82
Required Field for Enabling Debit and Prepaid Partial Authorizations Using
REST APIs................................................................................................................82
Optional Field for Enabling Debit and Prepaid Partial Authorizations Using
REST APIs................................................................................................................83
Enabling Partial Authorizations.................................................................................. 83
Example: Enabling Debit and Prepaid Partial Authorizations Using the REST
API............................................................................................................................83
Disabling Debit and Prepaid Partial Authorizations..........................................................85
Required Field for Disabling Debit and Prepaid Partial Authorizations Using
REST APIs............................................................................................................... 85
Optional Field for Disabling Debit and Prepaid Partial Authorizations Using
REST APIs............................................................................................................... 85
Disabling Partial Authorizations................................................................................. 85

Cybersource Contents 5
Example: Disabling Debit and Prepaid Partial Authorizations Using the REST
API............................................................................................................................86
Recent Revisions to This Document

Recent Revisions to This

Document

23.01
Multiple Partial Captures Added the section Multiple Partial
Captures on page 22.

Authorizations with a Card Verication Added the section Authorizations with Card
Number Verication Numbers on page 12.

22.02
Authorization with an SCA Exemption Use Added an Authorization with an SCA
Case exemption use case to the Basic
Authorization section of the Payment
Guide. See Authorization with an SCA
Exemption on page 37.

Basic Authorization Reversals Use Case Added a basic authorization reversal use
case. SeeAuthorization Reversals on page
44.

22.01
New Payment Guide This new payment guide, replaces the now
deprecated Credit Card Guide is re-written
to better align with customer requirements.

Cybersource Recent Revisions to This Document 7

About This Guide

About This Guide

This section describes the audience and purpose of this guide as well as conventions and
related documentation. See below for information about how to use this guide and where
to nd further information.

Audience and Purpose

This guide is written for application developers who want to use the REST API to integrate
payment card processing into an order management system.
Implementing the credit card services requires software development skills. You must
write code that uses the API request and response elds to integrate the credit card
services into your existing order management system.

Conventions
These special statements are used in this document:

Important
An Important statement contains information essential to successfully completing
a task or learning a concept.

Warning
A Warning contains information or instructions, which, if not heeded, can result in a
security risk, irreversible loss of data, or signicant cost in time or revenue or both.

Related Documentation
Refer to the Technical Documentation Portal for complete technical documentation:
https://docs.cybersource.com/en/index.html

Customer Support
For support information about any service, visit the Support Center:
http://www.cybersource.com/support

Cybersource About This Guide 8

Introduction to Payments

Introduction to Payments

This introduction provides the basic information that you will need to successfully process
payment transactions. It also provides an overview of the payments industry and provides
workows for each process.

Payment Services
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 nancial institutions, all through one connection.

Financial Institutions and Payment Networks

Financial institutions and payment networks enables payment services. These entities
work together and complete the full payment cycle.

Merchant Financial Institutions (Acquirers)

A merchant nancial 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 congured 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 the discount rate.

Cybersource Introduction to Payments 9

Introduction to Payments

These charges can be bundled (combined into a single charge) or unbundled (charged
separately).
• Interchange fees—payment networks, such as Visa or Mastercard, each have a base
fee, called the interchange fee, for each type of transaction. Your acquirer and
processor can show you ways to reduce this fee.
• Chargebacks—when cardholders dispute charges, you can incur chargebacks. A
chargeback occurs when a charge on a customer’s account is reversed. Your acquirer
removes the money from your account and could charge you a fee for processing the
chargeback.
Take these precautions to prevent chargebacks:
• Use accurate merchant descriptors, so that customers can recognize the transactions
on their statements.
• Provide good customer support.
• Ensure rapid problem resolution.
• Maintain a high level of customer satisfaction.
• Minimize fraudulent transactions.
If excessive chargebacks or fraudulant changes occur, these actions may be taken:
• You may be required to change your business processes to reduce the number
chargebacks and/or fraud.
• 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.

Issuing (Customer) Financial Institutions

An issuing (customer) nancial 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 acquiring nancial institutions and
issuing nancial institutions. 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.

Cybersource Introduction to Payments 10

Introduction to Payments

Payment Processors
Payment processors connect with acquirers. Before you can accept payments, you
must register with a payment processor.An acquirer may 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.

Payment Types
You can make payments with these payment types:
• Co-badged cards
• Co-branded cards
• Credit cards
• Debit cards
• Prepaid cards
• Private label cards
• Quasi-cash

Co-Badged Cards
Co-badged cards are credit 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 identier 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 linked cardholder's account.

Prepaid Cards
Prepaid cards allow cardholders to pay for goods and services using money stored directly
on the card.

Cybersource Introduction to Payments 11

Introduction to Payments

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.

Quasi-Cash
Quasi-cash transactions involve instruments that are directly convertible to cash such as
web wallets, travelers checks, cryptocurrency, and lottery tickets.

Transaction Types
This topic provides information about 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 is 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 identication cannot be veried. You can reduce that risk by using
features such as, the Address Verication System (AVS) and Card Verication Numbers
(CVNs). The AVS and CVNs provide additional protection from fraud. AVS validates the
cardholder’s entered address in relation to the known customer's address. CVN requires
the cardholder to include the card's CVN number during a transaction.

Card-Present Transactions
When a customer uses a card that is physically present in a retail environment, the
purchase is known as a card-present transaction.

Authorizations with Card Verication Numbers

Card verication 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 verication 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.

Cybersource Introduction to Payments 12

Introduction to Payments

Endpoint
POST https://api.cybersource.com/pts/v2/payments

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 eld. For American Express, the CVN is a four-digit number printed
on the front of the card above the card number.

CVN Locations

Each payment card company has its own name for the CVN value:
• American Express and Discover call it the Card Identication Number (CID).
• JCB calls it the Card Authentication Value (CAV2).
• Mastercard calls it the Card Validation Code (CVC2).
• Visa calls it the Card Verication Value (CVV2).

International Transactions
Consider these issues when processing international transactions.
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 a mark-up for the foreign exchange risk,
sales commissions, and handling costs.

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.

Cybersource Introduction to Payments 13

Introduction to Payments

TMS simplies 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 elds.
• Shipping Address — Stores a shipping address for a specic customer.
• Instrument Identier — An Instrument Identier object stores either:
• Payment card number
• [or] ACH bank account and routing number
This resource creates either:
• An Instrument Identier 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 elds.
• Payment Instrument — Stores a Payment Instrument using an Instrument Identier
token. It does not store the card number and cannot exist without an associated
Instrument Identier. It stores:
• Card expiration date
• Billing address
You can also choose to store this information yourself instead and store only the card
number or bank account and routing number in an Instrument Identier object.
• Customer Payment Instrument — Creates and stores a payment instrument for a
specic customer ID and an Instrument Identier 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.

Payment Processing
The various services used to process payments are at the heart of payment processing.
These services enable customers to purchase goods and services, merchants receive
payments from the customer's accounts, merchants to provide refunds, and merchants to
void transactions.

Authorizations
An authorization conrms that a payment card account holds enough funds to pay for a
purchase. Authorizations fall into two categories: online and ofine.

Cybersource Introduction to Payments 14

Introduction to Payments

Online Authorizations
Online authorizations provide immediate funds availability conrmations. The customer's
nancial institution also reduces the amount of credit available in the customer's
account, setting aside the authorized funds for the merchant to capture a later time.
Authorizations for most payment cards are processed online. Typically, it is safe to start
fullling the order once you receive an authorization conrmation.
An online authorization conrmation and the subsequent hold on funds expires after a
specic length of time. Thus it is important to capture funds in a timely manner. The issuing
bank sets the expiration time interval but most authorizations expire within ve to seven
days.
The issuing bank does not inform Cybersource when an authorization conrmation
expires. By default, the authorization information for each transaction remains in
the Cybersource database for 60 days after the authorization date. To capture an
authorization that expired with the issuing bank, you can resubmit the authorization
request.

Ofine 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 ofine transactions. An ofine authorization is an authorization request
for which you do not receive an immediate conrmation about the availability of funds.
Ofine authorizations have a higher level of risk than online transactions because they do
not provide fund availability conrmations or set aside the funds for later capture. Further,
it can take up to ve days to receive payment conrmations for ofine transactions. To
mitigate this risk, merchants may choose to fulll orders only after receiving payment
conrmations.

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.
Example

1. 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.
2. The customer orders dinner through room service the rst night. You request an
incremental authorization of 50.00 for the dinner.
3. The customer decides to stay an extra night. You request an incremental authorization
of 200.00 for the additional night.
4. 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.
5. When the customer checks out, they sign a receipt for 700.00, which is the total of all
costs incurred.

Cybersource Introduction to Payments 15

Introduction to Payments

6. You request a capture for 700.00.

Payment Network Tokens 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 elds in the authorization request because Cybersource
obtains the payment network tokenization information from the original authorization
request.

Authorization Workow

1. The customer purchases goods or service from the merchant using a payment card.
2. The merchant sends an authorization request to the acquiring (merchant) bank.
3. The acquiring (merchant) bank forwards the authorization request to the payment
network.
4. The payment network forwards the authorization request to the issuer (customer)
bank.
5. If funds are available, the issuer (customer) bank reserves the amount of the
authorization request and returns an authorization approval to the payment network. If
the issuer (customer) bank denies the request, it returns an authorization denial.
6. The payment network forwards the message to the acquiring (merchant) bank.
7. The acquiring (merchant) bank forwards the message to the merchant.

Sales
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, as the name indicates, is a two-step process. The authorization
is processed rst. 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 only
includes 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 using dual message processing.

Cybersource Introduction to Payments 16

Introduction to Payments

When partial authorization is enabled, the issuing nancial 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. This enables the merchant to use a
second card to cover the balance, adjust the total cost, or void the transaction.

Single Message Processing

Single message processing, as the name implies, treats the authorization and capture as a
single transaction. There are important differences for single message processing:
• Single message processing treats the request as a full-nancial 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
An authorization reversal releases the hold that an authorization placed on the customer’s
payment card funds.
Each card-issuing nancial institution has its own rules for deciding whether an
authorization reversal succeeds or fails. When a reversal fails, contact the card-issuing
nancial 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 elds 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, authorization reversal 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.

Credits
Credits are cash 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 issuing bank transfers funds from the merchant bank (acquirers)

Cybersource Introduction to Payments 17

Introduction to Payments

account to the customer's account. It typically takes two to four days for your acquiring
bank to transfer funds from your merchant's 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
• Stand-Alone Credits

Refunds
Refunds, also known as follow-on credits, use the capture request ID to link the refund
to a specic transaction. This request ID is returned during the capture request (also
known as a settlement) and is used in all subsequent refunds associated with the original
capture. The request ID links the transaction to the customer’s billing and account
information, so you are not required to include those elds in the credit request. 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 specied, refunds must be requested within 60 days of a settlement.
You can request multiple refunds against a single capture. To perform multiple refunds,
use the same request ID in each request.

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

Credit Workow
A credit does not happen in real time. All of the credit requests for a day are typically
placed in a batch le and sent to the processor as a single batch transaction. In most
cases, the batch transaction is settled overnight.

1. The merchant requests a credit.

2. The order information is validated.
3. The credit request is sent to the acquirer.

Cybersource Introduction to Payments 18

Introduction to Payments

4. The acquirer transfers the requested funds to the issuer.

Capture or Credit 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, so the window for voiding a
capture or credit request is relatively short. 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, you should request an
authorization reversal to release the hold on the unused credit card 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, thus there is
no need to include those elds in the void request. You cannot perform a follow-on credit
against a capture that has been voided.

Capture
A capture is a follow-on transaction to an authorization. It is used to transfer the
authorized funds from the customer's account to the merchant account. To link the
authentication transaction to the capture transaction, you include a request ID in your
capture request. This request ID is returned to you during the authentication response.
Capture are typically not performed in real time. They are placed in a batch le and sent
to the processor and the processor settles all of the captures at one time. In most cases,
these batch les are sent and processed outside of the merchant's business hours. It
usually takes two to four days for the acquiring nancial institution to deposit the funds
into the merchant account.
When fullling 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.

Cybersource Introduction to Payments 19

Introduction to Payments

Capture Workow

1. The merchant sends one or more transaction capture requests to the merchant bank
(acquirer).
2. The merchant bank sends the capture package to the payment network.
3. The payment network forwards the capture package to correct the customer bank
(issuer).
4. The customer bank settles the transactions and transfers the money to the merchant
bank (acquirer).

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.

Cybersource Introduction to Payments 20

Basic Processing

Basic Processing

This section provides the minimum requirements for successfully processing the standard
payment services.

Captures
This section shows you how to capture an authorized transaction.

Endpoint
POST https://api.cybersource.com/pts/v2/payments/{id}/captures
id is the transaction ID returned in the authorization response.

Required Fields for Capturing a Payment Using the REST API

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

REST Interactive Example: Capturing a Payment

Capture a Payment

Live Console URL: https://developer.cybersource.com/api-reference-assets/

index.html#payments_capture_capture-a-payment

REST Example: Capturing an Authorization

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments/{id}/captures

{
"orderInformation": {
"amountDetails": {

Cybersource Basic Processing 21

Basic Processing

"totalAmount": "100.00"
}
}

Response

{
"_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 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.

Endpoint
POST https://api.cybersource.com/pts/v2/payments/{id}/captures
id is the transaction ID returned in the authorization response.

Required Fields for Multiple Partial Captures

These elds are required in a request for a capture when you are requesting multiple
partial captures:

processingInformation.captureOptions.captureSequenceNumber

Cybersource Basic Processing 22

Basic Processing

processingInformation.captureOptions.totalCaptureCount
When you do not know the total number
of captures that you are going to request,
set the capture total count to an estimated
value or 99 for all capture requests except
the nal one. For the nal capture request,
set the capture total count and the capture
sequence to the same value.

Related information
API Field Reference for the REST API

REST Example: Processing Multiple Partial Captures

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments/{id}/captures
id is the transaction ID returned in the authorization response.

{
{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"captureOptions": {
"captureSequenceNumber": null,
"totalCaptureCount": null
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "102.21",
"currency": "USD"
}
}
}

Response

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/captures/6742496815656503003954/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/captures/6742496815656503003954"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},

Cybersource Basic Processing 23

Basic Processing

"id": "6742496815656503003954",
"orderInformation": {
"amountDetails": {
"totalAmount": "102.21",
"currency": "USD"
}
},
"reconciliationId": "67332020GD2G1OO1",
"status": "PENDING",
"submitTimeUtc": "2023-01-20T21:21:21Z"
}

Basic Authorizations
This section provides the minimal set of information required to perform a successful
authorization.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for Processing Basic Authorizations Using the REST

API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type

Cybersource Basic Processing 24

Basic Processing

Declined Authorizations
If an authorization is declined, you can use response categories to help decide if you
should retry or block a declined transaction. These response elds provide additional
information:
• paymentInsightsInformation.responseInsights.category
• paymentInsightsInformation.responseInsights.categoryCode
Category codes have possible values (such as 01) that correspond to a category, which
contains a description. These are the possible values:
• You cannot retry the following category code and category:
• 01 ISSUER_WILL_NEVER_APPROVE
• For the following values, you can retry the transaction a maximum of 15 times over a
period of 30 days:
• 02 ISSUER_CANNOT_APPROVE_AT_THIS_TIME
• 03 ISSUER_CANNOT_APPROVE_WITH_THESE_DETAILS: Data quality issue. Revalidate data
prior to retrying the transaction.
• 04 GENERIC_ERROR
• 97 PAYMENT_INSIGHTS_INTERNAL_ERROR
• 98 OTHERS
• 99 PAYMENT_INSIGHTS_RESPONSE_CATEGORY_MATCH_NOT_FOUND

REST Interactive Example: Processing an Authorization

Simple Authorization(Internet)

Live Console URL: https://developer.cybersource.com/api-reference-assets/

index.html#payments_payments_process-a-payment

REST Example: Processing a Basic Authorization

Endpoint: POST https://api.cybersource.com/pts/v2/payments
Request with Minimum Required Fields

{
"orderInformation": {
"billTo": {
"country": "US",
"lastName": "Kim",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"rstName": "Kyong-Jin",
"email": "[email protected]"
},
"amountDetails": {

Cybersource Basic Processing 25

Basic Processing

"totalAmount": "100.00",
"currency": "usd"
}
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"number": "4111111111111111",
"expirationMonth": "12",
"type": "001"
}
}
}

Response: Successful Authorization

{
"_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" : {

Cybersource Basic Processing 26

Basic Processing

"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: Declined Authorization

{
"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",

Cybersource Basic Processing 27

Basic Processing

"codeRaw": "Y"
}
},
"status": "DECLINED"
}

Authorization with Line Itemization

This section shows you how to process an authorization request with line items.

Fields Specic to this Use Case

Remove the orderInformation.amountDetails.totalAmount eld used in a basic
authorization and include one or more line items in the lineItem[] array.

Using Line Items

These elds are required for each line item that you use:
• orderInformation.lineItems[].unitPrice
• orderInformation.lineItems[].quantity
• orderInformation.lineItems[].productCode
• orderInformation.lineItems[].productSku (optional when item_#_productCode is set to
default, shipping_only, handling_only, or shipping_and_handling)
• orderInformation.lineItems[].productName (optional when item_#_productCode is set
to default, shipping_only, handling_only, or shipping_and_handling)
At a minimum, you must include the item_#_unitPrice eld in order to include a line item in
an authorization. When this eld is the only eld 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",

Cybersource Basic Processing 28

Basic Processing

"productSku": "12384569",
"productName": "receiver"
}
]
}

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number

REST Example: Processing a Basic Authorization with Line Items

Endpoint: POST https://api.cybersource.com/pts/v2/payments
Request

{
"currencyConversion": {
"indicator": "Y"
},
"paymentInformation": {
"card": {
"number": "4111111111111111",
"expirationMonth": "12",
"expirationYear": "2031"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",

Cybersource Basic Processing 29

Basic Processing

"exchangeRate": ".91",
"originalAmount": "107.33",
"originalCurrency": "eur"
},
"billTo": {
"rstName": "John",
"lastName": "Doe",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]"
},
"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

{
"_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",

Cybersource Basic Processing 30

Basic Processing

"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"
}

Processing an Authorization with a Card

Verication Number
This section provides the minimum information required to perform a successful
authorization with a card verication number (CVN).

Cybersource Basic Processing 31

Basic Processing

Fields Specic to This Use Case

Include this eld in a standard authorization request with a CVN:
• paymentInformation.card.securityCode

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
the processorInformation.cardVerication.resultCodeRaw eld. Use this value only for
debugging purposes; do not use it to determine the card verication response.
• The mapped response code is the pre-dened value that
corresponds to the raw response code. This value is returned in the
processorInformation.cardVerication.resultCode eld.
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 verication 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 eld to true.
CVN Results for American Express
A value of 1 in the processorInformation.cardVerication.resultCode eld indicates that
your account is not congured to use card verication. Contact customer support to
have your account enabled for this feature.
CVN Results for Discover
CVN Results for Visa and Mastercard
A CVN code of D or N causes the request to be declined with a reason code value of 230.
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
POST https://api.cybersource.com/pts/v2/payments

Required Fields for Processing Basic Authorizations with a Card

Verication Number Using the REST API
These elds are required in an authorization request with a CVN:

Cybersource Basic Processing 32

Basic Processing

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
paymentInformation.card.securityCode

Optional Fields for an Authorization with a Card Verication

Number
You can include these optional elds in an authorization request with a card verication
number:
paymentInformation.card.securityCodeIndicator
processingInformation.authorizationOptions.ignoreCvResult

REST Example: Processing an Authorization with a CVN

Request

{
"paymentInformation": {
"card": {
"number": "4111111111111111",
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001",
"securityCode": "999"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "49.95",

Cybersource Basic Processing 33

Basic Processing

"currency": "USD"
},
"billTo": {
"rstName": "John",
"lastName": "Doe",
"address1": "1295 Charleston Rd.",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"country": "US",
"email": "[email protected]",
"phoneNumber": "650-965-6000"
}
}
}

Response

{
"_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"
}
},

Cybersource Basic Processing 34

Basic Processing

"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"
}

Zero Amount Authorizations

This section shows you how to process zero amount authorizations.
Zero amount authorizations enable you to validate a card without charging the account.

Processor Specic Information

Barclays
Do not set the commerce indicator to recurring.
Visa Elecron cards are not supported.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for Processing Zero Amount Authorizations Using

the REST API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality

Cybersource Basic Processing 35

Basic Processing

orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number

REST Example: Processing a Zero Amount Authorization

Endpoint: POST https://api.cybersource.com/pts/v2/payments
Request

{
"orderInformation" : {
"billTo" : {
"country" : "US",
"lastName" : "Kim",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "Kyong-Jin",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "0.00",
"currency" : "usd"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12"
}
}
}

Response

{
"_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"
}

Cybersource Basic Processing 36

Basic Processing

},
"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"
}

Authorization with an SCA Exemption

This section shows you how to process an authorization with an SCA exemption.

Cybersource Basic Processing 37

Basic Processing

A strong customer authentication (SCA) exemption enables you to remain in compliance

with the EU's second Payment Services Directive. Depending on your processor, use one
of the following exemption elds:

Important
If you send more than one SCA exemption eld with a single authentication, the
transaction will be denied.
• Authentication Outage: Payer authentication is not available for this transaction due to
a system outage.
• B2B Corporate Card: Payment cards specically for business-to-business transactions
are exempt.
• Delegated Authentication: Payer authentication was performed outside of the
authorization workow.
• Follow-On Installment Payment: Installment payments of a xed amount are exempt
after the rst transaction.
• Follow-On Recurring Payment: Recurring payments of a xed amount are exempt after
the rst 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 beneciaries.

Fields Specic to This Use Case

Use these elds to request an SCA exemption:
Exemption Type Field Value

Follow-On Recurring processingInformation. commerceIndicator recurring

Payment
Low-Risk Transaction consumerAuthenticationInformation. 1
strongAuthentication.
riskAnalysisExemptionIndicator
Low-Value Transaction consumerAuthenticationInformation. 1
strongAuthentication.
lowValueExemptionIndicator
Merchant-Initiated processingInformation. authorizationOptions.
Transaction initiator. merchantInitiatedTransaction.reason

Cybersource Basic Processing 38

Basic Processing

Exemption Type Field Value

Stored Credential processingInformation. 1

Transaction authorizationOptions.initiator.
storedCredentialUsed

Country-Specic Requirements
These elds are specic to certain countries and regions.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for an Authorization with an SCA Exemption Using

the REST API
You must also include one SCA exemption eld from the SCA Exemption Fields list.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type

REST Example: Authorization with an SCA Exemption for Low Value

Transactions
Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"consumerAutenticationInformation" : {
"strongAuthentication" : {

Cybersource Basic Processing 39

Basic Processing

"lowValueExemptionIndicator" : "1"
}
},
"orderInformation" : {
"billTo" : {
"country" : "US",
"lastName" : "Kim",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "Kyong-Jin",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "eur"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12"
}
}
}

Response

{
"_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": {

Cybersource Basic Processing 40

Basic Processing

"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"
}

Sales
This section shows you how to process a sale transaction.
A sale transaction combines and authorization and a capture into a single transaction.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for Processing a Sale Using the REST API

The following elds are required in a request for a sale:

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country

Cybersource Basic Processing 41

Basic Processing

orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.LastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type

REST Example: Requesting a Sale

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"processingInformation": {
"capture": true
},
"orderInformation" : {
"billTo" : {
"country" : "US",
"lastName" : "VDP",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "RTS",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "usd"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12",
"type" : "001"

}
}
}

Cybersource Basic Processing 42

Basic Processing

Response
Most processors do not return all of the elds 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" : {

Cybersource Basic Processing 43

Basic Processing

"code" : "Y",
"codeRaw" : "Y"
}
},
"reconciliationId" : "6485004068966546103093",
"status" : "AUTHORIZED",
"submitTimeUtc" : "2022-03-28T20:46:47Z"
}

Authorization Reversals
Reversing an authorization releases the hold on the customer’s payment card funds that
the issuing bank placed when processing the authorization.
Each card-issuing nancial institution has its own rules for deciding whether an
authorization reversal succeeds or fails. When a reversal fails, contact the card-issuing
nancial 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 full 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 transaction to link the transactions together. 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 elds 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.

Endpoint
POST https://api.cybersource.com/pts/v2/payments/{id}/reversals

Required Fields for Processing Authorization Reversals Using REST

API
These elds are required in a request for an authorization reversal:

id Set the id URL parameter to the request

ID that was included in the authorization
response message.
reversalInformation.amountDetails.totalAmount
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

Cybersource Basic Processing 44

Basic Processing

requested in the authorization request

message.

Related information
API Field Reference for the REST API

Example: Processing an Authorization Reversal Using the REST API

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments/{id}/reversals

{
"reversalInformation" : {
"amountDetails" : {
"totalAmount" : "100.00"
}
}
}

Response

{
"_links" : {
"self" : {
"method" : "GET",
"href" : "/pts/v2/reversals/6522010713906068903093"
}
},
"authorizationInformation" : {
"approvalCode" : "100"
},
"clientReferenceInformation" : {
"code" : "1652201071257"
},
"id" : "6522010713906068903093",
"orderInformation" : {
"amountDetails" : {
"currency" : "USD"
}
},
"processorInformation" : {
"responseCode" : "0"
},
"reversalAmountDetails" : {
"reversedAmount" : "100.00",
"currency" : "USD"
},
"status" : "REVERSED",
"submitTimeUtc" : "2022-05-10T16:44:31Z"
}

Cybersource Basic Processing 45

Basic Processing

Refunds
This section shows you how to process a refund. You must request a refund within 60 days
of the authorization.

Endpoint
POST https://api.cybersource.com/pts/v2/payments/{id}/refunds
id is the transaction ID returned during the authorization request.

Required Fields for Processing Refunds Using the REST API

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrationArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number

REST Interactive Example: Processing a Refund

Refund a Payment

Live Console URL: https://developer.cybersource.com/api-reference-assets/

index.html#payments_refund_refund-a-payment

Example: Processing a Refund Using the REST API

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments/{id}/refunds

{
"orderInformation" : {
"billTo" : {

Cybersource Basic Processing 46

Basic Processing

"country" : "US",
"lastName" : "Kim",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "Kyong-Jin",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "eur"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12"
}
}
}

Response

{
"_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": {

Cybersource Basic Processing 47

Basic Processing

"type": "001"
},
"card": {
"type": "001"
}
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100"
},
"reconciliationId": "61873329OAILG3Q6",
"status": "PENDING",
"submitTimeUtc": "2022-12-02T15:54:18Z"
}

Credits
This topic shows you how to process a credit.

Endpoint
POST https://api.cybersource.com/pts/v2/credits/

Required Fields for Processing a Credit Using the REST API

These elds are required in a credit request:

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrationArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number

Cybersource Basic Processing 48

Basic Processing

REST Interactive Example: Processing a Credit

Credit

Live Console URL: https://developer.cybersource.com/api-reference-assets/

index.html#payments_credit_process-a-credit

REST Example: Processing a Credit

Request
Endpoint: POST https://api.cybersource.com/pts/v2/credits/

{
"orderInformation" : {
"billTo" : {
"country" : "US",
"lastName" : "Kim",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "Kyong-Jin",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "eur"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12"
}
}
}

Response

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/6663069906146706403954/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/6663069906146706403954"
}
},
"clientReferenceInformation": {
"code": "1666306990717"
},

Cybersource Basic Processing 49

Basic Processing

"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",
"responseCode": "100"
},
"reconciliationId": "66490108K9CLFJPN",
"status": "PENDING",
"submitTimeUtc": "2022-10-20T23:03:10Z"
}

Voids
This section shows you how to successfully process a void.

Endpoint
POST https://api.cybersource.com/pts/v2/captures/{id}/voids
POST https://api.cybersource.com/pts/v2/credits/{id}/voids
id is the transaction ID returned during the request to void.

Required Fields for Processing Voids Using REST APIs

This following elds are required in a request for a void:

id Set the id URL parameter to the request

ID that was included in the authorization
response message.

Cybersource Basic Processing 50

Basic Processing

REST Example: Processing a Void

Request
Endpoint: POST https://api.cybersource.com/pts/v2/captures/{id}/voids

Important
POST requests for voids require a body. If you have no elds to pass, use empty
braces as shown below.

{
}

Response

{
"_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"
}
}

Cybersource Basic Processing 51

Card-Present Authorizations

Card-Present
Authorizations

This section describes the types of card-present transactions.

The presence of a card is determined during the card authorization. Thus, the main
difference between a card present transaction and a card not-present transaction is in
the authorization service. There are three basic types of card-present authorizations:
• EMV Authorizations: Authorizations using the EMV chip embedded in the user's card
• Magnetic Stripe Authorization: Authorizations based on the magnetic stripe on the
user's card
• Hand-Keyed Authorizations: Authorizations based on the merchant manually entering
the card information into the terminal
This section will guide you through the various types of card present transactions
available to you.

Cybersource Card-Present Authorizations 52

Payer Authentication Processing

Payer Authentication
Processing

Payer Authorization uses a two-step verication process to add an extra layer of fraud
protection during the payment process. This two-step process uses customer data from
two of the 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 ngerprint
Each payment card company has its own payer authentication product.
• American Express: SafeKey
• Discover: ProtectBuy
• JCB: J/Secure
• Mastercard: Identity Check
• Visa: 3D 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. It requires banks to perform additional
checks when consumers make payments to conrm their identity.
For more information on Payer Authentication, see: Payer Authentication Feature Guide.

Visa Secure
Visa Secure enables the exchange of data between the merchant, card issuer and, when
necessary, the consumer, to validate that the transaction is being initiated by the rightful
owner of the account. It is a two-step process. First the cardholder is authenticated
by 3D Secure. Then the transaction is authorized based on the 3D-Secure evaluation.
In this section, you will learn how to authorize a card payment based on the 3D-Secure
evaluation.

Cybersource Payer Authentication Processing 53

Payer Authentication Processing

Prerequisite
Before you implement Visa Secure, you must contact customer support to have your
account congured for this feature.

Fields Specic to this Use Case

consumerAuthenticationInformation.cavv: The cardholder authentication verication
value (CAVV). This transaction identier is generated by the issuing bank and returned
during the Visa Secure cardholder authentication.
consumerAuthenticationInformation.xid: The transaction ID returned during the Visa
Secure cardholder authentication.
processingInformation.commerceIndicator: The transaction type.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for an Authorization with Visa Secure Using REST

APIs
The following elds are required in a request for an authorization with Visa Secure:

clientReferenceInformation.code
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.xid
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
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 eld to vbv for a successful
authentication or vbv_attempted if

Cybersource Payer Authentication Processing 54

Payer Authentication Processing

authentication was attempted but did not

succeed.

Related information
API Field Reference for the REST API

Example: Authorization with Visa Secure Using the REST API

Request
Endpoint:

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "vbv"
},
"paymentInformation": {
"card": {
"number": "4111111111111111",
"expirationMonth": "01",
"expirationYear": "2023"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "100",
"currency": "USD"
},
"billTo": {
"rstName": "John",
"lastName": "Smith",
"address1": "201 S. Division St._1",
"locality": "Foster City",
"administrativeArea": "CA",
"postalCode": "94404",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"
}
},
"consumerAuthenticationInformation": {
"cavv": "AceY+igABPs3jdwNaDg3MAACAAA=",
"xid": "1234567890987654321ABCDEFabcdefABCDEF123"
}
}

Response

{
"_links" : {
"authReversal" : {

Cybersource Payer Authentication Processing 55

Payer Authentication Processing

"method" : "POST",
"href" : "/pts/v2/payments/6510049442466278803211/reversals"
},
"self" : {
"method" : "GET",
"href" : "/pts/v2/payments/6510049442466278803211"
},
"capture" : {
"method" : "POST",
"href" : "/pts/v2/payments/6510049442466278803211/captures"
}
},
"clientReferenceInformation" : {
"code" : "TC50171_3"
},
"id" : "6510049442466278803211",
"orderInformation" : {
"amountDetails" : {
"authorizedAmount" : "100.00",
"currency" : "USD"
}
},
"paymentAccountInformation" : {
"card" : {
"brandName" : "VISA",
"type" : "001"
}
},
"paymentInformation" : {
"tokenizedCard" : {
"type" : "001"
},
"card" : {
"type" : "001"
}
},
"processorInformation" : {
"systemTraceAuditNumber" : "819194",
"approvalCode" : "831000",
"merchantAdvice" : {
"code" : "01",
"codeRaw" : "M001"
},
"responseDetails" : "ABC",
"networkTransactionId" : "016153570198200",
"retrievalReferenceNumber" : "211620819194",
"consumerAuthenticationResponse" : {
"code" : "2",
"codeRaw" : "2"
},
"transactionId" : "016153570198200",
"responseCode" : "00",
"avs" : {
"code" : "Y",
"codeRaw" : "Y"
}

Cybersource Payer Authentication Processing 56

Payer Authentication Processing

},
"reconciliationId" : "6510049442466278803211",
"status" : "AUTHORIZED",
"submitTimeUtc" : "2022-04-26T20:29:04Z"
}

JCB J/Secure
JCB J/Secure reduces the risk of unauthorized use of a payment card account by adding a
password identication step to the online shopping process.

Prerequisite
Before you implement payer authentication for JCB J/Secure, you must contact customer
support to have your account congured for this feature.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Related information
Payer Authentication Using the REST API

Required Fields for an Authorization using JCB J/Secure

Authentication with the REST API
The following elds are required in a request for an authorization with JCB J/Secure:

clientReferenceInformation.code
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.xid
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode

Cybersource Payer Authentication Processing 57

Payer Authentication Processing

paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type
processingInformation.commerceIndicator Set this eld to js for a successful
authentication or js_attempted if
authentication was attempted but did not
succeed.

Authorizing a JCB J/Secure Transaction Using REST APIs

To authorize a payment:
1. Send the service request to:
https://api.cybersource.com/pts/v2/payments
2. Check the response message to make sure that the request was successful. A 200-
level HTTP response code indicates success. For information about response codes,
see Transaction Response Codes.
3. Examine the response codes.
The authorization service returns 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 the processorInformation.consumerAuthenticationResponse.codeRaw eld.
• The mapped response code is the predened value that
corresponds to the raw response code. This value is returned in the
processorInformation.consumerAuthenticationResponse.code eld.

Example: Authorization with JCB J/Secure Using the REST API

Request

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "js"
},
"paymentInformation": {
"card": {
"number": "3566111111111113",
"expirationMonth": "01",
"expirationYear": "2023"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "100",

Cybersource Payer Authentication Processing 58

Payer Authentication Processing

"currency": "USD"
},
"billTo": {
"rstName": "John",
"lastName": "Smith",
"address1": "201 S. Division St._1",
"address2": "",
"locality": "Foster City",
"administrativeArea": "CA",
"postalCode": "94404",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"
}
},
"consumerAuthenticationInformation": {
"cavv": "AceY+igABPs3jdwNaDg3MAACAAA=",
"xid": "1234567890987654321ABCDEFabcdefABCDEF123"
}
}

Response

{
"_links" : {
"authReversal" : {
"method" : "POST",
"href" : "/pts/v2/payments/6510052001736280203211/reversals"
},
"self" : {
"method" : "GET",
"href" : "/pts/v2/payments/6510052001736280203211"
},
"capture" : {
"method" : "POST",
"href" : "/pts/v2/payments/6510052001736280203211/captures"
}
},
"clientReferenceInformation" : {
"code" : "TC50171_3"
},
"id" : "6510052001736280203211",
"orderInformation" : {
"amountDetails" : {
"authorizedAmount" : "100.00",
"currency" : "USD"
}
},
"paymentAccountInformation" : {
"card" : {
"brandName" : "JCB",
"type" : "007"
}
},
"paymentInformation" : {
"tokenizedCard" : {

Cybersource Payer Authentication Processing 59

Payer Authentication Processing

"type" : "007"
},
"card" : {
"type" : "007"
}
},
"processorInformation" : {
"systemTraceAuditNumber" : "819199",
"approvalCode" : "831000",
"merchantAdvice" : {
"code" : "01",
"codeRaw" : "M001"
},
"responseDetails" : "ABC",
"networkTransactionId" : "016153570198200",
"retrievalReferenceNumber" : "211620819199",
"consumerAuthenticationResponse" : {
"code" : "2",
"codeRaw" : "2"
},
"transactionId" : "016153570198200",
"responseCode" : "00",
"avs" : {
"code" : "Y",
"codeRaw" : "Y"
}
},
"reconciliationId" : "6510052001736280203211",
"status" : "AUTHORIZED",
"submitTimeUtc" : "2022-04-26T20:33:20Z"
}

Mastercard Identity Check

Mastercard Identity Check adds security to online transactions by authenticating Identity
Check account holders for specic transactions. Identity Check generates a unique, 32-
character transaction token, called the account authentication value (AAV), each time
an Identity Check-enabled account holder makes an online purchase. The AAV binds the
account holder to a specic transaction. Identity Check transactions use the universal
cardholder authentication eld (UCAF) as a standard to collect and pass AAV data. For
details about signing up for and using Identity Check or UCAF, contact your acquiring bank
or go to the Mastercard website.

Fields Specic to this Use Case

Include these elds with a standard authorization:
• consumerAuthenticationInformation.authenticationTransactionId-Set this eld to the
transaction ID returned by Identity Check during the authentication process.
• consumerAuthenticationInformation.paSpecicationVersion-Set this eld to the
Identity Check version returned by Identity Check during the authentication process.

Cybersource Payer Authentication Processing 60

Payer Authentication Processing

• consumerAuthenticationInformation.ucafCollectionIndicator-Set this value to the

Collection Indicator returned by Identity Check during the authentication process.
• processingInformation.commerceIndicator-Set this value to spa for an authentication
that was successful or was attempted but did not process.

Prerequisite
Before you implement payer authentication for Mastercard Identity Check, you must
contact customer support to have your account congured for this feature.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for an Authorization with Mastercard Identity

Check Using REST APIs
The following elds are required in a request for an authorization with Mastercard Identity
Check:

consumerAuthenticationInformation.authenticationTransactionId
consumerAuthenticationInformation.paSpecicationVersion
consumerAuthenticationInformation.ucafCollectionIndicator
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
processingInformation.commerceIndicator Set this eld to spa for an authentication
that was successful or was attempted but
did not succeed.

Cybersource Payer Authentication Processing 61

Payer Authentication Processing

Related information
API Field Reference for the REST API

Authorizing a Mastercard Identity Check Transaction Using REST

APIs
To authorize a payment:
1. Send the service request to:
https://api.cybersource.com/pts/v2/payments
2. Check the response message to make sure that the request was successful. A 200-
level HTTP response code indicates success. For information about response codes,
see Transaction Response Codes.
3. Examine the consumerAuthenticationInformation.ucafCollectionIndicator response
eld.

Important
A value of 0 for the UCAF collection indicator response eld for a Mastercard
transaction indicates that Mastercard downgraded the transaction. When
Mastercard approves an authorization and downgrades it, you are responsible
for the transaction. To conrm the downgrade, look at the e-commerce
indicator for the transaction in the Business Center. You can proceed with
the transaction if you want to accept responsibility. If you do not want to
accept responsibility, reverse the authorization, attempt to authenticate the
customer again, and request another authorization.

Example: Authorizing Mastercard Identity Check Using the REST API

Request

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "spa"
},
"paymentInformation": {
"card": {
"number": "5555555555554444",
"expirationMonth": "01",
"expirationYear": "2023"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "100",

Cybersource Payer Authentication Processing 62

Payer Authentication Processing

"currency": "USD"
},
"billTo": {
"rstName": "John",
"lastName": "Smith",
"address1": "201 S. Division St._1",
"locality": "Foster City",
"administrativeArea": "CA",
"postalCode": "94404",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"
}
},
"consumerAuthenticationInformation": {
"ucafCollectionIndicator": "1",
"paSpecicationVersion": "1",
"authenticationTransactionId": "OiCtXA1j1AxtSNDh5lt1"
}
}

Response

{
"_links" : {
"authReversal" : {
"method" : "POST",
"href" : "/pts/v2/payments/6506578204516496503211/reversals"
},
"self" : {
"method" : "GET",
"href" : "/pts/v2/payments/6506578204516496503211"
},
"capture" : {
"method" : "POST",
"href" : "/pts/v2/payments/6506578204516496503211/captures"
}
},
"clientReferenceInformation" : {
"code" : "TC50171_3"
},
"id" : "6506578204516496503211",
"orderInformation" : {
"amountDetails" : {
"authorizedAmount" : "100.00",
"currency" : "USD"
}
},
"paymentAccountInformation" : {
"card" : {
"type" : "002"
}
},
"paymentInformation" : {
"tokenizedCard" : {
"type" : "002"

Cybersource Payer Authentication Processing 63

Payer Authentication Processing

},
"card" : {
"type" : "002"
}
},
"processorInformation" : {
"approvalCode" : "100",
"responseCode" : "0",
"avs" : {
"code" : "U",
"codeRaw" : "00"
}
},
"status" : "AUTHORIZED",
"submitTimeUtc" : "2022-04-22T20:03:40Z"
}

ProtectBuy
Discover provides ProtectBuy to reduce the risk of unauthorized use of a payment card
account.
When you request an authorization using a supported card type and a supported
processor, you can include payer authentication data in the request. The payer
authentication services enable you to add payer authentication support to your website
without running additional software on your server.
ProtectBuy authenticates the customer by adding a password identication step to the
online shopping process. For details about signing up for and using ProtectBuy, contact
your acquiring bank or see the security and authentication information on the Discover
website.

Supported Service
Authorization

Supported Card Types

• Diners Club
• Discover

Prerequisite
Before you implement payer authentication for ProtectBuy, you must contact customer
support to have your account congured for this feature.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Cybersource Payer Authentication Processing 64

Payer Authentication Processing

Related information
www.discoverglobalnetwork.com/solutions/fraud-security/security-and-
authentication
Payer Authentication Using the REST API

Authorizing a ProtectBuy Transaction

Follow these steps to authorize a payment:
1. Send the service request to:
https://api.cybersource.com/pts/v2/payments
2. Include the required elds in the request.
3. Include optional elds in the request as needed.
4. Check the response message to make sure that the request was successful. A 200-
level HTTP response code indicates success. For information about response codes,
see Transaction Response Codes.
5. Examine the response codes.
The authorization service returns 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 the processorInformation.consumerAuthenticationResponse.codeRaw eld.
• The mapped response code is the predened value that
corresponds to the raw response code. This value is returned in the
processorInformation.consumerAuthenticationResponse.code eld.

Example: Authorization with ProtectBuy Using the REST API

Request
Endpoint:

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "vbv"
},
"paymentInformation": {
"card": {
"number": "4111111111111111",
"expirationMonth": "01",
"expirationYear": "2023"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "100",
"currency": "USD"

Cybersource Payer Authentication Processing 65

Payer Authentication Processing

},
"billTo": {
"rstName": "John",
"lastName": "Smith",
"address1": "201 S. Division St._1",
"locality": "Foster City",
"administrativeArea": "CA",
"postalCode": "94404",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"
}
},
"consumerAuthenticationInformation": {
"cavv": "AceY+igABPs3jdwNaDg3MAACAAA=",
"xid": "1234567890987654321ABCDEFabcdefABCDEF123"
}
}

Response

{
"_links" : {
"authReversal" : {
"method" : "POST",
"href" : "/pts/v2/payments/6510049442466278803211/reversals"
},
"self" : {
"method" : "GET",
"href" : "/pts/v2/payments/6510049442466278803211"
},
"capture" : {
"method" : "POST",
"href" : "/pts/v2/payments/6510049442466278803211/captures"
}
},
"clientReferenceInformation" : {
"code" : "TC50171_3"
},
"id" : "6510049442466278803211",
"orderInformation" : {
"amountDetails" : {
"authorizedAmount" : "100.00",
"currency" : "USD"
}
},
"paymentAccountInformation" : {
"card" : {
"brandName" : "VISA",
"type" : "001"
}
},
"paymentInformation" : {
"tokenizedCard" : {
"type" : "001"
},

Cybersource Payer Authentication Processing 66

Payer Authentication Processing

"card" : {
"type" : "001"
}
},
"processorInformation" : {
"systemTraceAuditNumber" : "819194",
"approvalCode" : "831000",
"merchantAdvice" : {
"code" : "01",
"codeRaw" : "M001"
},
"responseDetails" : "ABC",
"networkTransactionId" : "016153570198200",
"retrievalReferenceNumber" : "211620819194",
"consumerAuthenticationResponse" : {
"code" : "2",
"codeRaw" : "2"
},
"transactionId" : "016153570198200",
"responseCode" : "00",
"avs" : {
"code" : "Y",
"codeRaw" : "Y"
}
},
"reconciliationId" : "6510049442466278803211",
"status" : "AUTHORIZED",
"submitTimeUtc" : "2022-04-26T20:29:04Z"
}

Authorization with an SCA Exemption

This section shows you how to process an authorization with an SCA exemption.
A strong customer authentication (SCA) exemption enables you to remain in compliance
with the EU's second Payment Services Directive. Depending on your processor, use one
of the following exemption elds:

Important
If you send more than one SCA exemption eld with a single authentication, the
transaction will be denied.
• Authentication Outage: Payer authentication is not available for this transaction due to
a system outage.
• B2B Corporate Card: Payment cards specically for business-to-business transactions
are exempt.
• Delegated Authentication: Payer authentication was performed outside of the
authorization workow.
• Follow-On Installment Payment: Installment payments of a xed amount are exempt
after the rst transaction.

Cybersource Payer Authentication Processing 67

Payer Authentication Processing

• Follow-On Recurring Payment: Recurring payments of a xed amount are exempt after
the rst 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 beneciaries.

Fields Specic to This Use Case

Use these elds to request an SCA exemption:
Exemption Type Field Value

Follow-On Recurring processingInformation. commerceIndicator recurring

Payment
Low-Risk Transaction consumerAuthenticationInformation. 1
strongAuthentication.
riskAnalysisExemptionIndicator
Low-Value Transaction consumerAuthenticationInformation. 1
strongAuthentication.
lowValueExemptionIndicator
Merchant-Initiated processingInformation. authorizationOptions.
Transaction initiator. merchantInitiatedTransaction.reason
Stored Credential processingInformation. 1
Transaction authorizationOptions.initiator.
storedCredentialUsed

Country-Specic Requirements
These elds are specic to certain countries and regions.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for an Authorization with an SCA Exemption Using

the REST API
You must also include one SCA exemption eld from the SCA Exemption Fields list.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1

Cybersource Payer Authentication Processing 68

Payer Authentication Processing

orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type

REST Example: Authorization with an SCA Exemption for Low Value

Transactions
Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"consumerAutenticationInformation" : {
"strongAuthentication" : {
"lowValueExemptionIndicator" : "1"
}
},
"orderInformation" : {
"billTo" : {
"country" : "US",
"lastName" : "Kim",
"address1" : "201 S. Division St.",
"postalCode" : "48104-2201",
"locality" : "Ann Arbor",
"administrativeArea" : "MI",
"rstName" : "Kyong-Jin",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "eur"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"expirationMonth" : "12"
}
}

Cybersource Payer Authentication Processing 69

Payer Authentication Processing

Response

{
"_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",

Cybersource Payer Authentication Processing 70

Payer Authentication Processing

"status": "AUTHORIZED",
"submitTimeUtc": "2022-12-14T00:33:42Z"
}

Cybersource Payer Authentication Processing 71

Credentialed Transactions

Credentialed Transactions

There are several types of credentialed transactions:

• Customer-Initiated Transactions: Ad hoc customer-initiated transactions that use
stored credentials.
• Merchant-Initiated Transactions:
• Industry Practice Transactions: Merchant-initiated transactions that do not require
stored credentials.
• Standing Instruction Transactions: Merchant-initiated transactions that require
stored credentials and customer consent to execute.

Customer-Initiated Transactions with

Credentials on File
A customer-initiated transaction (CIT) is a transaction initiated by the cardholder. There
are two types of CIT transactions:
• Customer transactions for which the credentials are stored for future use
• Customer transactions for which stored credentials are used
Cardholders can initiate a CIT at a merchant payment terminal, through an online purchase
transaction, or by making a purchase using a previously stored credential.

Storing Customer Credentials with a Customer-Initiated

Transaction
Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated
transaction (CIT) with credentials-on-le (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.

Cybersource Credentialed Transactions 72

Credentialed Transactions

Fields Specic to this Use Case

Include this eld with a standard authorization request when storing customer
credentials:
• processingInformation.authorizationOptions.initiator.credentialStoredOnFile–Set this
eld to true to indicate that the customer credentials will be stored for future use.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.phoneNumber
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
processingInformation.authorizationOptions.initiator.credentialStoredOnFile
Set to true.

REST Example: Storing Customer Credentials During a Customer-Initiated

Transaction
Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"processingInformation": {
"authorizationOptions": {
"initiator": {
"credentialStoredOnFile": "true"
}
}
},
"orderInformation": {

Cybersource Credentialed Transactions 73

Credentialed Transactions

"billTo": {
"rstName": "John",
"lastName": "Deo",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"
},
"amountDetails": {
"totalAmount": "100.00",
"currency": "USD"
}
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"number": "4111xxxxxxxxxxxx",
"expirationMonth": "12"
}
}
}

Response

{
"_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"
}

Cybersource Credentialed Transactions 74

Credentialed Transactions

},
"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"
}

Using Stored Customer Credentials During a Customer-Initiated

Transaction
After customers store their credentials on le, they can recall these credentials to use
with subsequent transactions.

Fields Specic to this Use Case

When a customer-initiated transaction (CIT) uses stored credentials, the transaction
must include the following information in the authorization request:
• processingInformation.authorizationOptions.initiator.storedCredentialUsed–Set the
eld to true to indicate that the previously stored customer credentials were used.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Card-Specic Requirements
Some card companies require additional information when making authorizations with
stored credentials.

Discover
Discover requires the authorization amount from the original transaction when sending a
request:

Cybersource Credentialed Transactions 75

Credentialed Transactions

• processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.
originalAuthorizedAmount

Required Fields

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.phoneNumber
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
processingInformation.authorizationOptions.initiator.storedCredentialUsed
Set eld to true.

REST Example: Retrieving Customer Credentials During a Customer-Initiated

Transaction
Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"processingInformation": {
"authorizationOptions": {
"initiator": {
"storedCredentialUsed": "true"
}
}
},
"orderInformation": {
"billTo": {
"rstName": "John",
"lastName": "Deo",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"country": "US",
"email": "[email protected]",
"phoneNumber": "6504327113"

Cybersource Credentialed Transactions 76

Credentialed Transactions

},
"amountDetails": {
"totalAmount": "100.00",
"currency": "USD",
"originalAmount": "100"
// Discover card Only
}
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"number": "4111xxxxxxxxxxxx",
"expirationMonth": "12"
}
},
"processorInformation": {
"transactionId": "12345678961000"
}
}

Response

},
"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"
}

Cybersource Credentialed Transactions 77

Credentialed Transactions

Merchant-Initiated Transactions
Merchants can initiate a payment on the behalf of a customer. This type of transaction is
called a merchant-initiated transaction (MIT). When initiating a MIT, the customer is not
present. However, customers must authorize the storage of their credentials and the use
of these credentials for future payments.
There are two types of MITs:
• Industry Practice transactions: Follow-on transactions to a customer-initiated
transaction.
• Standing Instruction transactions: Agreed upon standing instructions from the
cardholder for the provision of goods or services. For example, a subscription to an
internet music service may involve an agreed upon standing instruction allowing the
merchant to bill a customer monthly for their subscription.

Cybersource Credentialed Transactions 78

Debit and Prepaid Card Processing

Debit and Prepaid Card

Processing

A Debit cards is 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
In Canada, to process domestic debit transactions on Visa Platform Connect with
Mastercard, you must contact customer support to have your account congured for this
feature.

Processing Debit and Prepaid Authorizations

This section provides the minimum set of information required to perform a successful
authorization using debit and prepaid cards.

Endpoint
POST https://api.cybersource.com/pts/v2/payments

Required Fields for Debit and Prepaid Authorizations Using REST

APIs
clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea

Cybersource Debit and Prepaid Card Processing 79

Debit and Prepaid Card Processing

orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type

Optional Field for Debit and Prepaid Authorizations Using REST APIs

processingInformation.linkId Set this eld to the request ID that was

returned in the response message from the
original authorization request.

REST Example: Debit and Prepaid Authorizations

Request
Endpoint: POST https://api.cybersource.com/pts/v2/payments

{
"orderInformation" : {
"billTo" : {
"country" : "US",
"rstName" : "John",
"lastName" : "Deo",
"address1" : "901 Metro Center Blvd",
"postalCode" : "40500",
"locality" : "Foster City",
"administrativeArea" : "CA",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "100.00",
"currency" : "USD"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "4111111111111111",
"securityCode" : "123",
"expirationMonth" : "12",
"type" : "001"

Cybersource Debit and Prepaid Card Processing 80

Debit and Prepaid Card Processing

}
}
}

Response

{
"_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
+JbKAU0qB8S2VpA6cQIp4ZNvG2YbC9eM4E5NlirUyEkEx8yYAAA4A1c"
},
"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",
"cardVerication" : {
"resultCodeRaw" : "M",
"resultCode" : "M"
},
"merchantAdvice" : {

Cybersource Debit and Prepaid Card Processing 81

Debit and Prepaid Card Processing

"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 provides the minimum set of information
required to enable partial authorizations for a specic transaction.

Fields Specic to this Use Case

Include the following elds in addition to the elds required for a standard authorization
request:
• Indicate that this request is a partial authorization.
Set the processingInformation.authorizationOptions.partialAuthIndicator to true.

Required Field for Enabling Debit and Prepaid Partial Authorizations

Using REST APIs
clientReferenceInformation.code
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email

Cybersource Debit and Prepaid Card Processing 82

Debit and Prepaid Card Processing

orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type
processingInformation.authorizationOptions.partialAuthIndicator
Set this eld to true.

Optional Field for Enabling Debit and Prepaid Partial Authorizations

Using REST APIs
processingInformation.linkId Set this eld to the request ID that was
returned in the response message from the
original authorization request.

Enabling Partial Authorizations

1. Enable partial authorizations for the transaction by setting the
processingInformation.authorizationOptions.partialAuthIndicator eld to true in a
request.
2. Send the service request to this endpoint:
https://api.cybersource.com/pts/v2/payments

Example: Enabling Debit and Prepaid Partial Authorizations Using

the REST API
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",
"rstName" : "John",
"phoneNumber" : "999999999",

Cybersource Debit and Prepaid Card Processing 83

Debit and Prepaid Card Processing

"district" : "MI",
"buildingNumber" : "123",
"company" : "Visa",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "1000.00",
"currency" : "USD"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "5555555555554444",
"securityCode" : "123",
"expirationMonth" : "12",
"type" : "002"
}
},
"processingInformation" : {
"authorizationOptions" : {
"partialAuthIndicator" : "true"
}
}
}

Response

{
"_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" : {

Cybersource Debit and Prepaid Card Processing 84

Debit and Prepaid Card Processing

"merchantNumber" : "000000092345678",
"approvalCode" : "888888",
"cardVerication" : {
"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 the minimum set of information required to enable partial authorizations
for specic transactions. To disable all authorization and capture requests for partial
authorizations, call customer support.

Required Field for Disabling Debit and Prepaid Partial Authorizations

Using REST APIs
processingInformation.authorizationOptions.partialAuthIndicator
Set this eld to false in an authorization
or sale request. When you do so, only that
specic transaction is disabled for partial
authorization.

Optional Field for Disabling Debit and Prepaid Partial Authorizations

Using REST APIs
processingInformation.linkId Set this eld to the request ID that was
returned in the response message from the
original authorization request.

Disabling Partial Authorizations

1. Enable partial authorizations for the transaction by setting the
processingInformation.authorizationOptions.partialAuthIndicator eld to true in a
request.

Cybersource Debit and Prepaid Card Processing 85

Debit and Prepaid Card Processing

2. Send the service request to this endpoint:

https://api.cybersource.com/pts/v2/payments

Example: Disabling Debit and Prepaid Partial Authorizations Using

the REST API
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",
"rstName" : "John",
"phoneNumber" : "999999999",
"district" : "MI",
"buildingNumber" : "123",
"company" : "Visa",
"email" : "[email protected]"
},
"amountDetails" : {
"totalAmount" : "501.00",
"currency" : "USD"
}
},
"paymentInformation" : {
"card" : {
"expirationYear" : "2031",
"number" : "5555555555554444",
"securityCode" : "123",
"expirationMonth" : "12",
"type" : "002"
}
}
}

Response

{
"_links": {
"self": {
"method": "GET",

Cybersource Debit and Prepaid Card Processing 86

Debit and Prepaid Card Processing

"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"
}

Cybersource Debit and Prepaid Card Processing 87