VISA Platform Connect: Specifications and Conditions for
Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner enabling
its merchants through
Cybersource for Visa Platform Connect
(“VPC”) processing
. Failure to meet any of the specifications and conditions
below is subject to the liability provisions and indemnification obligations under
Reseller/Partner’s contract with Visa/Cybersource.
Before boarding merchants for payment processing on a VPC acquirer’s connection,
Reseller/Partner and the VPC acquirer must have a contract or other legal agreement
that permits Reseller/Partner to enable its merchants to process payments with the
acquirer through the dedicated VPC connection and/or traditional connection with
such VPC acquirer.
Reseller/Partner is responsible for boarding and enabling its merchants in
accordance with the terms of the contract or other legal agreement with the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that all considerations and fees associated
with chargebacks, interchange downgrades, settlement issues, funding delays, and
other processing related activities are strictly between Reseller and the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is
responsible for payment processing issues, including but not limited to, transaction
declines by network/issuer, decline rates, and interchange qualification, as may be
agreed to or outlined in the contract or other legal agreement between
Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR
OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA
NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR
ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE
RELEVANT VISA PLATFORM CONNECT ACQUIRER.
Introduction to the Boarding Registration Service
Boarding Registration streamlines and automates the boarding of merchant accounts using
the
Cybersource
REST API
. You can create a simple or complex hierarchy of accounts that
represents merchant business units, and configure payment products for those accounts.
To understand accounts, organizations, their hierarchy, and status, see these
topics:
Before boarding organizations, you must complete these requirements:
You must have a portfolio account on our platform. Contact your representative to have a
portfolio account set up for you.
Set up users, roles, and permissions. You must have at least one administrator
account.
Understanding Accounts and Organizations
You are assigned a
portfolio
account when you sign up. All merchant accounts are
subordinate to the portfolio account. A merchant account consists of a
merchant
organization and its subordinate organizations, which always includes at least one
transacting
organization. You can use
structural
organizations to extend the
hierarchy of merchant accounts.
The
portfolio
account is always the top node in the hierarchy.
A
merchant
organization represents a business entity. For example, a brand or
company. There can only be one merchant in any branch of the hierarchy.
A
transacting
organization represents an entity that processes payment
transactions. For example, a physical store or a payment form on a web page or app. No other
organization can be directly subordinate to a transacting organization.
A
structural
organization represents a conceptual entity that enables you to build an
expansive hierarchy between merchant and transacting nodes. For more information on
using structural organizations to extend the hierarchy, see Extending the Hierarchy.
The image below shows a simple
merchant account. The merchant organization is directly beneath the portfolio
organization, and contains one transacting organization.
Figure:
Sample Merchant Account
Understanding Organization IDs
Organizations relate to each other using IDs. Every organization is assigned an
organization ID. When an organization has a subordinate, it is assigned a child ID that
identifies the subordinate. The subordinate is assigned a parent ID that identifies the
parent organization. Organization IDs must be unique, not just within the portfolio or
account, but across the system.
In the illustration below, merchant's ID is
Merchant Account 1
. The
merchant's child IDs are
Transacting MID1
and
Transacting
MID2
. The merchant's parent ID is
Portfolio
.
Figure:
Understanding Organization IDs
IMPORTANT
Do not include sensitive information in the
Org ID field. A security validation check is in place to ensure that the unique Org
ID field (e.g., Cybersource MID) does not contain PAN or other sensitive information
to provide an additional layer of protection for your data during the onboarding
process.
Configure a Single Merchant
Figure:
Merchant Boarding with a Single MID
Follow these steps to configure a merchant hierarchy with a single merchant:
Contact your representative to have a portfolio account set up for you.
A product template enables and configures a product and is applied to more transacting
organizations. Product templates are created in the
Business Center
by an
administrator user. Before you board a transacting organization, you must create a
product template for each product that you will assign to it. Not every product support
templates.
You will apply product templates to a transacting organization when you create it. You
can also create multiple templates for a product, configured differently, and decide
which one to apply to a transacting organization, depending on the organization's needs.
Templates can be modified at any time; however, organizations that already have the
template applied do not inherit the modifications. Modifying a template only affects new
organizations that you apply to it.
Partners can use various boarding templates to customize merchant onboarding and meet the
business needs of each merchant.
A boarding template is a collection of predefined attributes and rules that an acquirer
(bank), technical partner, or merchant uses to board merchants onto their platform.
Boarding templates help automate the entire boarding process by packaging all of the
required information needed to board merchants. You can use templates to reduce the
manual steps and time it takes for merchant accounts to start processing payments.
Templates also allow an acquirer or partner to make configuration changes to individual
and multiple merchants in the portfolio.
You can use a boarding template to initialize or make changes to any of the
following:
Accounts
Transacting nodes
Structural nodes
Template Components
The boarding template combines these essential components:
Products and Product Bundles
Partners can offer a list of products and
product bundles to merchants. All products and bundles are available in a
partner's catalog.
Billing Template
A combination of BUY and SELL rates that is associated with a product (or
product bundle). A billing template is required for products sold by OBO
partners. Non-OBO partners can choose to set a value on billing templates for
tracking purposes.
Product Configuration Templates
A collection of pre-configured product settings that partners can use for
boarding activities. When applied along with a merchant-specific configuration,
the product is fully enabled for the merchant.
Boarding Workflow
A boarding workflow is a sequence of steps controlled by partner-specific business rules to
board merchants.
Additional Metadata
These include mandatory, optional, and self-provisioned products, token IDs, and other
attributes.
IMPORTANT
You can see templates only for enabled products on your
account.
Products
You can use boarding templates to configure these products in merchant accounts.
Account Updater
Card Processing
Echeck/ACH
Fraud Management Essentials
Gift Cards
Payer Authentication
Secure Acceptance
Token Management Service
Virtual Terminal
Using Templates
This section describes the template tasks you can perform.
Retrieving Templates
You can retrieve merchant boarding templates for a specified product. The default
template is the first template listed when you retrieve a template.
Next to the template you want to modify, click the
Make Default (...)
icon.
Product Boarding Template Reference
Use this information as a guide to configure the boarding templates. We update this
reference as existing templates are updated and new templates are added.
Account Updater Templates
Select configuration options for these fields:
Account Updater Template Configuration Options
Field
Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Visa/Mastercard Mode
Pan Upload
Token API
Monthly Harvest
AMEX Mode
Token API
Monthly Harvest
Request Updates from AMEX
Yes
No
AMEX SE Number
INPUT SE #
AMEX Subscriber ID
INPUT ID #
Request Updates from Mastercard
Yes
No
Mastercard ICA Number
10426
10427
1835
1836
4845
8773
Mastercard Merchant ID
INPUT MID #
Request Updates from Visa
Yes
No
VISA Segment ID
0040
0043
0044
0048
0057
0088
VISA Merchant ID
INPUT Visa MID #
Card Processing Templates
Create a card-processing template for each payment processor you use. Each card-processing template is specific to a single payment
processor. Apply the appropriate template when you are boarding new merchants.
Configuring a Card Processing Template
Follow these steps to configure a template for card processing:
Enter a unique name for the new card-processing template, and then click
Next
.
Select the type of card processing: Card Present, Card Not Present, or
Both.
Click the
Processor
field, and then choose the payment processor
name.
If an Acceptance Type field appears, click the field, and then choose the
acceptance type.
In the processor tab (labeled with the name of the processor you selected),
configure the required and optional fields available for the selected payment
processor.
In the Common Settings tab, you can configure fields that are common for the
merchant but that could potentially be used across multiple payment processors.
Processor-Specific Fields
These processor-specific fields are frequently
configured in a card-processing template.
For more information about
these and other fields in the template, see the
Select all of the card types that the merchant accepts. The card types listed
in this field depend on the payment processor selected.
Depending on your payment processor, these are some of the card types you
can expect to see listed:
Visa
Mastercard
American Express
Diners Club
For more information about the specific card types that your processor
supports, log in to the
Business Center
and go to
Template
Management for Card Processing
.
Batch Group
The Batch Group groups all of the capture (bill and credit) requests into a batch bound for your payment processor.
Choose the batch group for processing capture requests.
The name of a batch group identifies the time of day that capture requests
are grouped into a batch and sent to your payment processor. The last two
digits of the batch group name identify the hour (in 24-hour time) of the
processor cutoff time for that batch group.
As an example, if you are creating a card processing template for the
American Express Direct processor, the list of batch group names you can
select includes the following:
amexdirect_2 (processor cutoff time is 2:00 a.m. PST daily)
amexdirect_17 (processor cutoff time is 5:00 p.m. PST daily)
amexdirect_21 (processor cutoff time is 9:00 p.m. PST daily)
IMPORTANT
Processor cutoff times identified in the batch group
names are in Pacific Standard Time (PST).
Merchant ID
Enter the merchant's acquirer processing ID assigned by the acquiring bank.
Note that it is unlikely that you would specify this field in a card-processing
template. Typically, the merchant ID is merchant specific. Also, many merchants
have more than one merchant ID to support processing in multiple currencies or
to process both card present (in store) transactions and card-not-present
(e-commerce) transactions.
Terminal ID
Enter the terminal ID assigned by the acquirer or the processor. This value
should not be overridden by any other party.
Enter the merchant's processing terminal ID assigned by the acquiring bank or
payment processor.
Note that it is unlikely that you would specify this field in a card-processing
template. Typically, the terminal ID is merchant specific. Also, many merchants
have more than one terminal ID to support processing in multiple currencies or
to process both card-present (in store) transactions and card-not-present
(e-commerce) transactions.
Customer Invoicing
Customer Invoicing allows merchants to create and manage invoices, send customers links to invoices, securely collect payments for
invoices.
Prerequisites
Unified Checkout
must be enabled for the merchant. Before
Unified Checkout
can be enabled for a merchant, it must be enabled at the
portfolio level.
When you attempt to enable
Pay by Link
without
enabling
Unified Checkout
, the boarding calls will fail with the error
<>
.
To enable
Unified Checkout
at the portfolio level, talk to your sales
representative.
Customer Invoicing must be enabled at the portfolio level before in can be added to merchant
accounts. To enable at Customer Invoicing at the portfolio level, contact your sales
representative.
Enabling Customer Invoicing on the Business Center
Before you can add Customer Invoicing, Unified Checkout must be added to the merchant account. To add Unified Checkout, see: Unified Checkout.
Navigate to the Merchant Details Page within Portfolio Management.
Click the
Add products
button.
Select
Customer Invoicing
, and click the
Add
button.
Customer Invoicing should appear on the Merchant's product list.
Select a batch group. Batch time is identified by the last two digits in military time.
Example:
<processor>_16
means the cut-off time is 4:00 p.m. PST. Convert the time to your local time as
needed.
Auto Set to Completed State
Select
Yes
to automatically update transactions to "Completed" status a number of days
after the transaction is processed.
Company ID
Merchant's ID assigned by the acquiring bank.
ACH Entry Description
Merchant-defined description. Example: Payroll, Gas Bill, Insurance Premium.
Fraud Management Essentials
Templates
On the General Settings page, select options for each of the following:
Fraud Management Essentials
Template General Settings Options
Section Name
Field Name
Available Options / Details
Payment Processing
Settlement
Disable Settlement
Enable Settlement
Enable with settlement selected by default
Decision Reject
Authorization Reversal
Disable authorization reversal option
Enable authorization reversal option
Enable with authorization reversal option selected by default
Local Currency
Local Currency
Select the local currency from the list.
On the Rule Configuration page, configure the options for each of the following:
Fraud Management Essentials
Template Rule Configuration Options
Tab Name
Field Name
Available Options / Details
Score Threshold
Score Threshold
Score between 50-69
Score between 70-94
Score between 95-100
Each threshold has an enable/disable check box. Each score can be adjusted to user specifications.
Standard Rules
AVS Mismatch
Monitor, Review, Reject, Disable
Standard Rules
AVS Partial Match
Monitor, Review, Reject, Disable
Standard Rules
AVS Not Verifiable
Monitor, Review, Reject, Disable
Standard Rules
CVV Mismatch
Monitor, Review, Reject, Disable
Standard Rules
CVV Not Verifiable
Monitor, Review, Reject, Disable
Standard Rules
Invalid Address
Monitor, Review, Reject, Disable
Standard Rules
Billing-Shipping Mismatch
Monitor, Review, Reject, Disable
Standard Rules
Billing-IP Mismatch
Monitor, Review, Reject, Disable
Standard Rules
Shipping-IP Country Mismatch
Monitor, Review, Reject, Disable
Regional & Country IP Address Rules
Decision
Review, Reject, Monitor
Regional & Country IP Address Rules
Region
Regions include: Asia, Europe, Africa, Oceania, Central America/Caribbean,
Arctic/Antarctica, South America, North America, Middle East
Regional & Country IP Address Rules
Countries
Check the
All
box for all countries in a region or select individually listed
countries.
Velocity Rules
Decision
Monitor, Review, Reject
Velocity Rules
Field
Email, Total count, Device, Shipping Address, Account Number, IP Address
Velocity Rules
Value
Input Value for Transactions in Field
Velocity Rules
Time Range
Range of time the rule is valid for.
Threshold Rules
Decision
Monitor, Review, Reject, Disable
Threshold Rules
Rule - Min Order Amount
Order Amount minimum amount
Threshold Rules
Value
Input order dollar amount
Threshold Rules
Decision
Monitor, Review, Reject, Disable
Threshold Rules
Rule - Max Order Amount
Order Amount Maximum amount
Threshold Rules
Value
Input order dollar amount
Gift Card Templates
Select configuration options for these fields:
Gift Card Template Configuration Options
Field
Value or Option
Gift Card MID
The Valuelink Gift card assigned merchant number which includes the plan, root, merchant
location, and check digit.
Merchant SIC Code
Merchant Category Code.
Merchant Store ID
Store ID number.
Enable PIN encryption?
Select
Yes
to encrypt the PIN before sending it to the processor.
Enable Merchant defined Transaction Reference Number?
Select
Yes
to allow the merchant to define the transaction reference number.
Otherwise, it is auto-generated.
Payer Authentication Templates
Payer Authentication
templates specify the payer authentication services that a merchant account will accept. To
specify a payer authentication service, enter the acquirer ID in the associated field.
This template supports the following payer authentication services:
Visa Secure with EMV
The Visa card type uses Visa Secure with EMV as the authentication service. The acquirer ID is a text string that consists of 6 to
20 digits and starts with the number 4.
Mastercard/Meeza Identity Check
The Mastercard card type uses Mastercard Identity Check as the authentication service. The acquirer ID is a text string that
consists of 6 to 20 digits and starts with the number 5 or 2.
American Express SafeKey
The American Express card type uses American Express SafeKey as the authentication service. The acquirer ID is a text string that
consists of 11 to 20 digits and starts with the number 1.
Cartes Bancaires Fast'R
The Cartes Bancaires card type uses Fast’R as the authentication service. The acquirer ID is a text string that consists of 6 to
20 digits and starts with the number 4, 5, or 2.
Discover / Diners Club ProtectBuy
The Discover / Diners Club card type uses ProtectBuy as the authentication service. The acquirer ID is a text string that consists
of 6 to 20 digits and starts with the number 3 or 6.
Elo Compra Segura
The Elo card type uses Elo Compra Segura as the authentication service. The acquirer ID is a text string that consists of 4
digits. The acquirer ID is a text string that consists of 8 digits and starts with the number 1.
JCB J/Secure
The JCB card type uses J/Secure as the authentication service.
UnionPay 3D Secure
3D Secure is a protocol designed to be an additional security layer for online credit and debit card transactions. The acquirer ID
is a text string that consists of 6 to 20 digits and begins with the number 4, 5, 2, or 6.
Pay By Link
Pay by Link
provides merchants an easy and fast way to sell products or accept donations without any coding.
Prerequisites
Unified Checkout
must be enabled for the merchant. Before
Unified Checkout
can be enabled for a merchant, it must be enabled at the
portfolio level.
When you attempt to enable
Pay by Link
without enabling
Unified Checkout
, the boarding calls will fail with the error
<>
.
To enable
Unified Checkout
at the portfolio level, talk to your sales
representative.
Pay by Link
must be enabled at the portfolio level before in can be added to
merchant accounts. To enable at
Pay by Link
the portfolio level,
contact your sales representative.
Enabling
Pay by Link
on the Business Center
Before you can add
Pay by Link
, Unified Checkout must be added to the merchant account. To add Unified Checkout, see: Unified Checkout.
Navigate to the Merchant Details Page within Portfolio Management.
If you use the API, keep in mind these considerations:
The organization registration is done once using the
/registrations
endpoint. Modifications to existing organizations are done using the
/organizations
endpoint. Modifications to the product setups of an
organization are done using the
/product-setups
endpoint. Examples of these
endpoints are shown in the sections for those operations.
The
boardingFlow
field has two values:
ENTERPRISE
and
SMB
. Enterprise creates one organization at a time. SMB (Small Business)
creates a combination of one merchant organization and one transacting organization.
Enterprise requires two requests, but defines an organization ID for the transacting
organization instead of an automatically generated one. Enterprise is recommended. When you
create a structural organization, you must set the value of
boardingFlow
to
ENTERPRISE
.
The
mode
field is not currently supported.
The
configurable
field must be set to
true
for
merchant organizations and
false
for transacting and structural
organizations.
Create a Merchant Organization
Use these instructions to create a merchant account using the API.
Endpoint
Production:
POST
https://api.cybersource.com
/boarding/v1/registrations
Test:
POST
https://apitest.cybersource.com
/boarding/v1/registrations
Required Fields for Boarding a Merchant Organization
This feature is in pilot phase. You have early access to
this feature even though it might contain bugs or unfinished work. Please consider
the risk when using this feature.
Endpoint
Production:
POST
https://api.cybersource.com
/boarding/v1/registrations
Test:
POST
https://apitest.cybersource.com
/boarding/v1/registrations
Required Fields for Adding a Transacting Organization to an Existing Organization
You can send a GET request to retrieve a list of all your organizations. You can use the GET
request without parameters to retrieve the full list or use query parameters to limit
the results. You can retrieve up to 1000 rows of organizations. To retrieve a list of
organizations:
Endpoint
Production:
GET
https://api.cybersource.com
/oms/v1/organizations
Test:
GET
https://apitest.cybersource.com
/oms/v1/organizations
Using Query Parameters to Filter Results
When you request the list of organizations for your account, you can use URL-encoded query
parameters to narrow the list.
The number specified in this parameter excludes that many items from the response. The
default is
0
limit
The number specified in this parameter limits how many items to include in the response.
When combined with offset, limits the items returned to a specific number of items
starting from a specific item. The default is
10
.
sort
The order in which you would like your results sorted. For example,
type:desc,entityName:asc
.
Using the hierarchyQuery Parameter
The hierarchy query allows you to query relationships and explore your parents and
children. This is a type of graph, so there is a defined language syntax that is flexible
enough for you to explore this hierarchy in a natural way. The structure of the query
is:
organizationId.direction.distance
organizationId
indicates the organizationId.
direction
specifies hierarchical relationships. Values can be
descendents
or
ancestors
.
distance
indicates levels of hierarchy. You can provide a whole number
to specify the number levels of hierarchy to return. You can also use the asterisk
You can send a GET request to retrieve the details of an organization. You can use the
GET request without parameters to retrieve the full details or use the
is the ID that returned in the organization's boarding API response. Include
only the fields you want to update.
REST Example: Retrieving an Organization
Request
GET
https://api.cybersource.com
/oms/v1/organizations/org1
Response
200 OK
Update an Organization's Information
Use these instructions to update an organization's information using the API.
Although
organizationId
is the only required field, any other field that
contains organization information can be added to the API request to update the
information in that field.
Endpoint
Production:
GET
https://api.cybersource.com
/oms/v1/organizations/{organizationId}
Test:
GET
https://apitest.cybersource.com
/oms/v1/organizations/{organizationId}
Where
{organizationId}
is the ID that returned in the organization's boarding API response. Include
only the fields you want to update.
REST Example: Updating an Organization's Information
You can change the status of organization by sending a GET request and including only the
fields that you want to update in your request.
Endpoint
Production:
GET
https://api.cybersource.com
/oms/v1/organizations/{organizationId}
Test:
GET
https://apitest.cybersource.com
/oms/v1/organizations/{organizationId}
Where
{organizationId}
is the ID that returned in the organization's boarding API response. Include
only the fields you want to update.
REST Example: Changing an Organization's Status
Request
{}
Response to a Successful Request
200 OK
Product Enablement and Configuration Using the BRS API
You can enable and configure different products for merchants in the
Business Center
and the Product Enablement and Configuration Service (PECS) API.
You can use the PECS API to enable, subscribe, and configure products for a merchant. The
PECS API is used during merchant onboarding and after merchant onboarding:
Merchant onboarding
: PECS is invoked by the Boarding Registration Service
(BRS) API.
Post-merchant onboarding
: PECS is called to update the merchant's product
subscriptions or configurations.
During merchant onboarding, products can be enabled and configured. PECS supports
multiple products that can be assigned to a merchant. Some products are available only
for enablement and there is no capability to update configurations for these products.
Some products are available for both enablement and configuration:
Enablement-only products:
Acceptance Devices
Card Present Connect
Checkout API
Customer Invoicing
Digital Payment Suite
Installments
Pay by Link
Receivables Manager
Recurring Billing
Reporting
Tax Calculation
Transaction Search
Unified Checkout
Enablement and configuration products:
Account Updater
Advanced Billing
Alternative Payment Methods
Card Processing
Decision Manager
eCheck
Fraud Management Essentials
Gift Cards
Payer Authentication
Service Orchestration
Payouts
Secure Acceptance
Token Management Service
Virtual Terminal
Payer Authentication
Payer Authentication
uses the 3-D Secure protocol in
online transactions to verify that payment is coming from the legitimate cardholder.
Authenticating the payer before the transaction is authorized benefits the merchant by
shifting chargeback liability from the merchant to the card issuer.
Prerequisites
You must meet these requirements to enable and configure
Payer Authentication
for your merchants:
You must include a merchant website URL. 3-D Secure protocol requires that
the website URL must be in the format
https://www.example.com
.
You must include a merchant category code for your merchant.
At least one 3-D Secure template must be available. For information on
creating product templates, see Product Templates.
Status
When you add Payer Authentication to a merchant account, one of these statuses is
assigned:
Boarded: The Payer Authentication configuration was successfully saved and
the merchant can proceed to transact the card network using the specified
currency.
Pending: The Payer Authentication configuration is partially saved or
incomplete. Raise a ticket with customer support.
) links
tokens across service providers, payment types, and channels for sellers, acquirers, and
technology partners.
TMS
tokenizes, securely stores, and
manages the primary account number (PAN), the payment card expiration date, electronic
check details, and customer data.
TMS
also enables merchants to
create a network token of a customer's payment card.
IMPORTANT
When you board a merchant and enable
TMS
and
network tokenization, the token requestor ID is enrolled at the merchant account
organization level where the token vault is configured. You must include the merchant
business information during token requestor ID enrollment and when you create the
TMS
token vault. This ensures that the network tokens that
are provisioned are assigned to the merchant that owns the tokens.
Token vaults are where merchants store their customer and payment data. A
Business Center
internal user can enable the
TMS
vault.
Vaults are assigned to an owner, and all data within the vault belongs to the owner. You
can grant permission to individual MIDs to create, retrieve, update, and delete tokens
within a vault. Created tokens belong to the owner of the vault, not the creator of the
token. If you remove a MID from a vault, it can no longer access any tokens within that
vault, including tokens created under that MID.
IMPORTANT
It is not currently possible to merge vaults, so ensure that
merchants are set up with the correct vault by creating a new vault or granting access
to an existing vault.
Token Requestor IDs
A token requestor ID (TRID) is a unique identifier that entities such as merchants use to
request network tokens from token providers. Having a TRID is a prerequisite for
enabling network tokenization.
Each entity must register with the token provider to get a TRID. Contact a
Cybersource
representative to enroll a merchant as a token requestor.
Visa and Mastercard TRIDs
An internal user can enroll a merchant as a VISA or Mastercard token requestor
through the
Business Center
.
Follow these steps to enroll a merchant as a token requestor in the
Business Center
:
Navigate to
Token Management
.
Click
Vault Management
.
Use the Vault Owner filter to search for the merchant account that has
TMS
enabled.
Choose the merchant account to view the
TMS
vaults
that are configured for the merchant.
Click
Network Tokenization
.
Click
Enroll to VISA/Mastercard token services
.
Enter the required information for each card type:
Mastercard
Business entity name
Visa
Merchant name
Merchant website URL
Merchant country code
Click
Onboard with Acquirer ID
.
Enter the required information:
Acquirer ID
Set the value to
40010052242
. It is a static
acquirer ID that is used for
TMS
.
Acquirer Merchant ID
Enter your organization ID.
Click
Enroll to Network Token Services
to complete
enrollment.
When the enrollment is submitted, the relationship ID and token requestor ID
appear on the page for Visa Token Service (VTS) and the token requestor ID appears
for Mastercard.
In order to request a TRID from the token provider,
Cybersource
uses
merchant business details already stored. If any of the details are not present, a
dialog form should appear prompting you to complete the missing information.
American Express TRIDs
Enrollment as a token requestor for American Express is a manual process. Contact
your
Cybersource
representative to request the TRID for American
Express.
Allow 2 to 3 days for the completion of your request.
IMPORTANT
Service establishment (SE) Numbers
are required in order
to process American Express card transactions.
Configure the Token Vault Settings Using the
Business Center
Follow these steps to configure your merchant token vault settings:
Log in to the
Business Center
test environment or production
environment.
Test:
https://businesscentertest.cybersource.com
Production:
https://businesscenter.cybersource.com
In the left navigation panel, click the
Token Management
icon (
).
Click
Vault Management New
. The Vault Management page
appears.
From the Vault Owner drop-down list, select the vault owner..
In the Details column, click
Vault Settings
. The Edit
Vault page appears.
Click
Edit
.
A dialog box appears with a message to warn you that changing your vault
settings could result in your merchants being unable to access tokens, which
could result in failing transactions. Click
Yes
if you
want to continue.
Enter the vault name, supported payment methods, supported token types and
formats, card number masking format, payment instrument storing configuration,
and the webhook URL.
For each token type, you can choose from these token formats:
32 Character Hex
22 Digits
19 Digits Luhn Check Passing
16 Digits Luhn Check Passing
IMPORTANT
Account Updater is incompatible with instrument
identifier tokens in the 22-digit format.
Click
SAVE
.
To return to the vault management page, click
VAULT
MANAGEMENT
.
Configure the Token Vault Access Using the
Business Center
Follow these steps to configure your merchant token vault access settings:
Log in to the
Business Center
test environment or production
environment.
Test:
https://businesscentertest.cybersource.com
Production:
https://businesscenter.cybersource.com
In the left navigation panel, click the
Token Management
icon (
).
Click
Vault Management New
. The Vault Management page
appears.
Select the vault owner that you want to configure from the Vault Owner
drop-down list.
In the Details column, click
Access Settings
. The MID
Access page appears.
Check the box for the vault settings you want to enable for each merchant you
want to configure:
Product Enablement and Configuration Using the PECS API
You can enable and configure different products for merchants in the
Business Center
and the Product Enablement and Configuration Service (PECS) API.
You can use the PECS API to enable, subscribe, and configure products for a merchant. The
PECS API is used during merchant onboading and after merchant onboarding:
Merchant onboarding
: PECS is invoked by the Boarding Registration Service
(BRS) API.
Post-merchant onboarding
: PECS is called to update the merchant's product
subscriptions or configurations.
During merchant onboarding, products can be enabled and configured. PECS supports
multiple products that can be assigned to a merchant. Some products are available only
for enablement and there is no capability to update configurations for these products.
Some products are available for both enablement and configuration:
Enablement-only products:
Acceptance Devices
Card Present Connect
Checkout API
Customer Invoicing
Digital Payment Suite
Installments
Pay by Link
Receivables Manager
Recurring Billing
Reporting
Tax Calculation
Transaction Search
Unified Checkout
Enablement and configuration products:
Account Updater
Advanced Billing
Alternative Payment Methods
Card Processing
Decision Manager
eCheck
Fraud Management Essentials
Gift Cards
Payer Authentication
Service Orchestration
Payouts
Secure Acceptance
Token Management Service
Virtual Terminal
Add a New Product to an Existing Organization
To add a product, you must subscribe to it, and if there are configurations available,
configure it.
Endpoint
Production:
POST
https://api.cybersource.com
/products/v1/product-setups
Test:
POST
https://apitest.cybersource.com
/products/v1/product-setups
Subscribing to a Product
Product fields are in the
selectedProducts
object. Include the field for
the product you are adding, and set
subscriptionInformation.enabled
field
for that product to
true
Product Features
Some products also have a
features
block within the
subscriptionInformation
object that gives you the ability to enable
features of a product.
This section shows you how to soft-delete a processor. All configuration settings are
preserved but the processor is no longer visible in the API or the
Business Center
.
Endpoint
Production:
POST
https://api.cybersource.com
/products/v1/product-setups
Test:
POST
https://apitest.cybersource.com
/products/v1/product-setups
Required Fields for Deleting a Processor Using the PECS API
This section shows you how to soft-delete a processor and add a new processor. All
configuration settings are preserved but the processor is no longer visible in the API
or the
Business Center
.
Endpoint
Production:
POST
https://api.cybersource.com
/products/v1/product-setups
Test:
POST
https://apitest.cybersource.com
/products/v1/product-setups
Required Fields for Adding and Deleting a Processor Using the PECS API
uses the 3-D Secure protocol in
online transactions to verify that payment is coming from the legitimate cardholder.
Authenticating the payer before the transaction is authorized benefits the merchant by
shifting chargeback liability from the merchant to the card issuer.
Prerequisites
You must meet these requirements to enable and configure
Payer Authentication
for your merchants:
You must include a merchant website URL. 3-D Secure protocol requires that
the website URL must be in the format
https://www.example.com
.
You must include a merchant category code for your merchant.
At least one 3-D Secure template must be available. For information on
creating product templates, see Product Templates.
Status
When you add Payer Authentication to a merchant account, one of these statuses is
assigned:
Boarded: The Payer Authentication configuration was successfully saved and
the merchant can proceed to transact the card network using the specified
currency.
Pending: The Payer Authentication configuration is partially saved or
incomplete. Raise a ticket with customer support.
Configure
Payer Authentication
Using the PECS API
This section shows you how to configure
Payer Authentication
.
Endpoint
Production:
POST
https://api.cybersource.com
/products/v1/product-setups
Test:
POST
https://apitest.cybersource.com
/products/v1/product-setups
Required Fields for Configuring
Payer Authentication
Using the PECS API
Use these required fields to configure
Payer Authentication
for these card
types.
American Express SafeKey-Specific Fields
Include these fields in addition to the required fields to enable and configure
American Express SafeKey:
For more information on response reason codes, see Reason Codes.
Token Management Service
The
Token Management Service
(
TMS
) links
tokens across service providers, payment types, and channels for sellers, acquirers, and
technology partners.
TMS
tokenizes, securely stores, and
manages the primary account number (PAN), the payment card expiration date, electronic
check details, and customer data.
TMS
also enables merchants to
create a network token of a customer's payment card.
IMPORTANT
When you board a merchant and enable
TMS
and
network tokenization, the token requestor ID is enrolled at the merchant account
organization level where the token vault is configured. You must include the merchant
business information during token requestor ID enrollment and when you create the
TMS
token vault. This ensures that the network tokens that
are provisioned are assigned to the merchant that owns the tokens.
The Boarding service enables you to build a hierarchy to model your actual business structure
or the business structures of your merchants if you are a reseller. You can board a small
hierarchy of organizations using only merchant and transacting organizations. You can also use
structural organizations to extend the hierarchy. Extending the hierarchy is optional.
Structural organizations can be placed under merchant organizations to represent things like
different types of payment systems, different geographical regions, or any other distinction
that your business needs. Transacting organizations are then placed under the structural
organizations.
Hierarchy Example
In this diagram of a relatively simple hierarchy, a merchant organization has two structural
organizations: one for eCommerce, and one for physical store locations. Transacting
organizations are added under the structural organizations. This is an example of using
structural organizations to represent card-not-present transactions (online transactions) and
card-present transactions (physical store locations). The Stores node has two physical
locations that process payments. The eCommerce node has one transacting organization, which
represents a payment form on a website.
Figure:
Hierarchy Example
Add a Structural Organization to a Merchant Organization
Use these instructions to create a structural account using the API.
Endpoint
Production:
POST
https://api.cybersource.com
/boarding/v1/registrations
Test:
POST
https://apitest.cybersource.com
/boarding/v1/registrations
Required Fields for Boarding a Structural Organization
organizationInformation.businessInformation.name
organizationInformation.configurable
Set the value to
false
.
organizationInformation.parentOrganizationId
Set to the ID of the organization that you want to be above this one in the
hierarchy.
Not all currencies are supported for all processors.
Currency Code
Numerical Currency Code
Currency Name
Decimal Places
AED
784
United Arab Emirates dirham
2
AFN
971
Afghanistan afghani
2
ALL
008
Albanian lek
2
AMD
051
Armenian dram
2
ANG
532
Netherlands Antillean
guilder
2
AOA
973
Angola kwanza
2
ARS
032
Argentine peso
2
AUD
036
Australian dollar
2
AWG
533
Aruban guilder
2
AZN
944
Azerbaijanian manat
2
BAM
977
Bosnia and Herzegovina convertible
mark
2
BBD
052
Barbados dollar
2
BDT
050
Bangladeshi taka
2
BGN
975
Bulgarian lev
2
BHD
048
Bahraini dinar
3
BIF
108
Burundian franc
0
BMD
060
Bermuda dollar
2
BND
096
Brunei dollar
2
BOB
068
Bolivian boliviano
2
BOV
984
Bolivian mvdol
2
BRL
986
Brazilian real
2
BSD
044
Bahamian dollar
2
BTN
064
Bhutani ngultrum
2
BWP
072
Botswana pula
2
BYR
933
Belarussian ruble
BYR has been
replaced by BYN as the Belarussian ruble currency.
0
BYN
933
Belarussian ruble
2
BZD
084
Belize dollar
2
CAD
124
Canadian dollar
2
CDF
976
Congolese franc
2
CHF
756
Swiss franc
2
CLF
990
Chilean unidad de fomento
4
CLP
152
Chilean peso
0
CNY
156
Chinese yuan renminbi
2
COP
170
Columbian peso
2
COU
970
Columbian unidad de valor
real
2
CRC
188
Costa Rican colon
2
CSK
203
Czech koruna
2
CUC
931
Cuban peso, convertible
2
CUP
192
Cuban peso
2
CVE
132
Cape Verde escudo
2
CZK
203
Czech koruna
2
DJF
262
Djiboutian franc
0
DKK
208
Danish krone
2
DOP
214
Dominican peso
2
DZD
012
Algerian dinar
2
EGP
818
Egyptian pound
2
ERN
232
Eritrean nakfa
2
ETB
230
Ethiopian birr
2
EUR
978
Euro
2
FJD
242
Fiji dollar
2
FKP
238
Falkland Islands pound
2
GBP
826
British pound sterling
2
GEL
981
Georgian lari
2
GHS
936
Ghana cedi
2
GIP
292
Gibraltar pound
2
GMD
270
Gambian dalasi
2
GNF
324
Guinean franc
0
GTQ
320
Guatemalan quetzal
2
GWP
Guinea-Bissau peso
0
GYD
328
Guyanese dollar
2
HKD
344
Hong Kong dollar
2
HNL
340
Hunduran Lempira
2
HTG
332
Haitian gourde
2
HUF
348
Hungarian forint
2
IDR
360
Indonesian rupiah
2
ILS
376
Israeli sheqel
2
INR
356
Indian rupee
2
IQD
368
Iraqi dinar
3
IRR
364
Iranian rial
2
ISK
352
Icelandic krona
0
JMD
388
Jamaican dollar
2
JOD
400
Jordanian dinar
3
JPY
392
Japanese yen
0
KES
404
Kenyan shilling
2
KGS
417
Kyrgyzstani som
2
KHR
116
Cambodian riel
2
KMF
174
Comoro franc
0
KPW
408
North Korean won
2
KRW
410
South Korean won
0
KWD
414
Kuwaiti dinar
3
KYD
136
Cayman Islands dollar
2
KZT
398
Kazakhstani tenge
2
LAK
418
Lao kip
2
LBP
422
Lebanese pound
2
LKR
144
Sri Lanka rupee
2
LRD
430
Liberian dollar
2
LSL
426
Lesotho loti
2
LTL
Lithuanian litas
2
LVL
Latvian lats
2
LYD
434
Libyan dinar
3
MAD
504
Moroccan dirham
2
MDL
498
Moldovan leu
2
MGA
969
Malagasy ariary
2
MKD
807
Macedonian denar
2
MMK
104
Myanmar kyat
2
MNT
496
Mongolian tugrik
2
MOP
446
Macanese pataca
2
MRO
Mauritanian ouguiya
2
MUR
480
Mauritius rupee
2
MVR
462
Maldivian rufiyaa
2
MWK
454
Malawian kwacha
2
MXN
484
Mexican peso
2
MYR
458
Malaysian ringgit
2
MZN
943
Mozambican metical
2
NAD
516
Namibian dollar
2
NGN
566
Nigerian naira
2
NIO
558
Cordoba oro
2
NOK
578
Norwegian krone
2
NPR
524
Nepalese rupee
2
NZD
554
New Zealand dollar
2
OMR
512
Omani rial
3
PAB
590
Panamanian balboa
2
PEN
604
Peruvian nuevo sol
2
PGK
598
Papua New Guinean kina
2
PHP
608
Philippine peso
2
PKR
586
Pakistan rupee
2
PLN
985
Polish zloty
2
PYG
600
Paraguayan guarani
0
QAR
634
Qatari rial
2
RON
946
Romanian leu
2
RSD
941
Serbian dinar
2
RUB
643
Russian ruble
2
RWF
646
Rwanda franc
0
SAR
682
Saudi Arabian riyal
2
SBD
090
Solomon Islands dollar
2
SCR
690
Seychelles rupee
2
SDG
938
Sudanese pound
2
SEK
752
Swedish krona
2
SGD
702
Singapore dollar
2
SHP
654
Saint Helena pound
2
SLE
925
Sierra Leonean leone
IMPORTANT
Effective
October 1, 2022
, the
SLL
currency code is valid only for
exemption processing.
2
SOS
706
Somali shilling
2
SRD
968
Surinamese dollar
2
SSP
728
South Sudanese pound
2
STD
Sao Tome and Principe dobra
2
SVC
222
El Salvadorean colon
2
SYP
760
Syrian pound
2
SZL
784
Swaziland lilangeni
2
THB
764
Thai baht
2
TJS
972
Tajikistani somoni
2
TMT
934
Turkmenistan new manat
2
TND
788
Tunisian dinar
3
TOP
776
Tongan pa’anga
2
TRY
949
Turkish lira
2
TTD
780
Trinidad and Tobago dollar
2
TWD
901
Taiwan dollar
2
TZS
834
Tanzanian shilling
2
UAH
980
Ukrainian hryvnia
2
UGX
800
Ugandan shilling
2
USD
840
United States dollar
2
UYU
858
Uruguayan peso
2
UZS
860
Uzbekistan som
2
VEF
937
Venezuelan bolivar fuerte
2
VND
704
Vietnamese dong
0
VUV
548
Vanuatu vatu
0
WST
882
Samoan tala
2
XAF
950
CFA franc BEAC (Central African CFA
franc)
0
XCD
951
East Caribbean dollar
2
XOF
952
CFA Franc BCEAO (West African CFA franc)
0
XPF
953
CFP franc
0
YER
886
Yemeni rial
2
ZAR
710
South African rand
2
ZMK
Zambian kwacha
2
ZMW
967
Zambian kwacha
2
ZWD
Zimbabwean dollar
2
ZWL
932
Zimbabwean dollar
2
Reason Codes
These tables list the reason codes and the possible status and reason
values that are returned with the response from the Boarding Registration Service
(BRS) API and the Product Enablement and Configuration Service (PECS) API.
Cybersource
reserves the right to add new reason codes at any time. If
your error handler receives a reason code that it does not recognize, it should use
the decision field to determine the result.
BRS API Reason Codes
Reason Codes
Reason Code
Description
200
Successful.
Possible
status
values:
PROCESSING
: The registration is still
in progress. You can get the latest status by calling
the
GET
endpoint using the registration
ID.
SUCCESS
: The request was
successful.
FAILURE
: The registration failed before
the organization was created. Refer to the details
section in the response for more information.
PARTIAL
: The registration created the
organization successfully but failed in at least on step
while configuring it. Refer to the details section in
the response for more information.
400
Bad request.
Possible
reason
values:
INVALID_DATA
SYSTEM_ERROR
RESOURCE_NOT_FOUND
422
Business validations failed.
Possible
reason
values:
INVALID_DATA
500
Internal server error.
Possible
reason
values:
SYSTEM_ERROR
Example: Partial Processed Response from the BRS API
Follow these steps to add merchant account information:
In Basic Information, enter the merchant account name and the organization ID in the
provided text fields.
ADDITIONAL INFORMATION
The merchant account name is the name of the business.
The organization ID is the name or identifier of the account that you are creating.
It must be unique, not just in the portfolio or account, but in the system.
Enter the merchant information in the provided text fields. Required fields are noted
with an asterisk (*).
Click
Save
. You are returned to the Add Merchant page. You can
skip the optional hierarchy step by clicking
Skip
.
REST Example: Creating a Transacting Organization with
Integration Information
A product template enables and configures a product and is applied to more transacting
organizations. Product templates are created in the
Business Center
by an
administrator user. Before you board a transacting organization, you must create a
product template for each product that you will assign to it. Not every product support
templates.
You will apply product templates to a transacting organization when you create it. You
can also create multiple templates for a product, configured differently, and decide
which one to apply to a transacting organization, depending on the organization's needs.
Templates can be modified at any time; however, organizations that already have the
template applied do not inherit the modifications. Modifying a template only affects new
organizations that you apply to it.
Partners can use various boarding templates to customize merchant onboarding and meet the
business needs of each merchant.
A boarding template is a collection of predefined attributes and rules that an acquirer
(bank), technical partner, or merchant uses to board merchants onto their platform.
Boarding templates help automate the entire boarding process by packaging all of the
required information needed to board merchants. You can use templates to reduce the
manual steps and time it takes for merchant accounts to start processing payments.
Templates also allow an acquirer or partner to make configuration changes to individual
and multiple merchants in the portfolio.
You can use a boarding template to initialize or make changes to any of the
following: