CyberSource payment-tokens API
A payment-tokens is a service that is used for retrieving vault details or deleting vault id/payment method.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation payment-tokens API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: payment-tokens
description: 'A payment-tokens is a service that is used for retrieving vault details or deleting vault id/payment method.
'
paths:
/pts/v2/payment-tokens:
post:
summary: Retrieve or Delete Payment Token
description: 'This API can be used in two flavours - for retrieval or deletion of vault id.
'
tags:
- payment-tokens
operationId: retrieveOrDeletePaymentToken
x-devcenter-metaData:
categoryTag: Payments
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html
parameters:
- name: request
in: body
required: true
schema:
type: object
properties:
processingInformation:
type: object
properties:
actionList:
type: array
description: "Array of actions (one or more) to be included in the payment to invoke bundled services.\nPossible values are one or more of follows:\n\n - `TOKEN_RETRIEVE`: Use this when Alternative Payment token retrieval is requested.\n - `TOKEN_DELETE`: Use this when Alternative Payment token deletion is requested.\n"
items:
type: string
paymentInformation:
type: object
properties:
paymentType:
type: object
properties:
name:
type: string
description: 'A Payment Type is an agreed means for a payee to receive legal tender from a payer. The way one pays for a commercial financial transaction. Examples: Card, Bank Transfer, Digital, Direct Debit.
Possible values:
- `CARD` (use this for a PIN debit transaction)
- `CHECK` (use this for all eCheck payment transactions - ECP Debit, ECP Follow-on Credit, ECP StandAlone Credit)
- `bankTransfer` (use for Online Bank Transafer for methods such as P24, iDeal, Estonia Bank, KCP)
- `localCard` (KCP Local card via Altpay)
- `carrierBilling` (KCP Carrier Billing via Altpay)
'
method:
type: object
properties:
name:
type: string
description: 'A Payment Type is enabled through a Method. Examples: Visa, Master Card, ApplePay, iDeal, 7Eleven, alfamart, bofaPayByBank, payToPayByBank, etc
For Japan Payment Processing Valid Values:
- 1 Banking Data
- 2 Authorization Data
#### Via KCP
- `KCP` : Local Card, Bank Transfer and Carrier Billing.
- `PAYCO`
- `KAKAOPAY`
- `NAVERPAY`
'
tokenizedPaymentMethod:
type: object
properties:
id:
type: string
maxLength: 255
description: 'The PayPal-generated ID for the token.
'
responses:
'201':
description: Successful response.
schema:
type: object
properties:
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
status:
type: string
description: "The status of the request.\n\nPossible values:\n - COMPLETED\n"
paymentInformation:
type: object
properties:
tokenizedPaymentMethod:
type: object
properties:
id:
type: string
maxLength: 255
description: 'The PayPal-generated ID for the token.
'
usageType:
type: string
maxLength: 255
description: 'Indicates the type of vaulting relationship. Valid values:
- "MERCHANT": Single merchant relationship.
- "PLATFORM": Platform hosting multiple merchants.
'
eWallet:
type: object
properties:
accountId:
type: string
maxLength: 26
description: The unique ID for a customer generated by PayPal.
orderInformation:
type: object
properties:
shipTo:
type: object
properties:
firstName:
type: string
maxLength: 60
description: 'First name of the recipient.
#### Litle
Maximum length: 25
#### All other processors
Maximum length: 60
Optional field.
'
lastName:
type: string
maxLength: 60
description: 'Last name of the recipient.
#### Litle
Maximum length: 25
#### All other processors
Maximum length: 60
Optional field.
'
address1:
type: string
maxLength: 60
description: 'First line of the shipping address.
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address2:
type: string
maxLength: 60
description: 'Second line of the shipping address.
Optional field.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
administrativeArea:
type: string
maxLength: 50
description: "State or province of the shipping address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf) (maximum length: 2) \n\nRequired field for authorization if any shipping address information is included in the request and shipping to the U.S.\nor Canada; otherwise, optional.\n\n#### Tax Calculation\nOptional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.\nBilling address objects will be used to determine the cardholder's location when shipTo objects are not present.\n"
locality:
type: string
maxLength: 50
description: 'City of the shipping address.
Required field for authorization if any shipping address information is included in the request and shipping to the U.S. or
Canada; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
postalCode:
type: string
maxLength: 32
description: 'Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
Required field for authorization if any shipping address information is included in the request and
shipping to the U.S. or Canada; otherwise, optional.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
Example A1B 2C3
#### American Express Direct
Before sending the postal code to the processor, all nonalphanumeric characters are removed and, if the
remaining value is longer than nine characters, the value is truncated starting from the right side.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
country:
type: string
description: 'Country of the shipping address. Use the two-character [ISO Standard Country Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf)
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
maxLength: 3
'400':
description: Invalid request.
schema:
type: object
title: ptsV2RetrievePaymentTokenGet400Response
properties:
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - INVALID_REQUEST\n"
reason:
type: string
description: "The reason of the status. \n\nPossible values:\n - INVALID_DATA\n - RESOURCE_NOT_FOUND\n"
message:
type: string
description: The detail message related to the status and reason listed above.
details:
type: array
items:
type: object
properties:
field:
type: string
description: This is the flattened JSON object field name/path that is either missing or invalid.
reason:
type: string
description: "Possible reasons for the error.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n"
'502':
description: Internal server error.
schema:
title: ptsV2RetrievePaymentTokenGet502Response
type: object
properties:
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - SERVER_ERROR\n"
reason:
type: string
description: "The reason of the status.\n\nPossible values:\n - INTERNAL_SERVER_ERROR\n"
message:
type: string
description: The detail message related to the status and reason listed above.
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
x-devcenter-metaData:
categoryTagArray:
- name: Payments
description: For more information about Payments transactions, see the [Payments Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html).
- name: Transaction_Batches
description: For more information about Transaction Batches, see the [Transaction Batches Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-transaction-batch-api/txn_batch_api_intro.html).
- name: eCheck_AVS
description: For more information about eCheck Account Validation, see the [Account Validation Developer Guides Page](https://...).
- name: Token_Management
description: For more information about the Token Management Service (TMS) see the [Token Management Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-overview.html)
- name: Flex_Microform
description: Microform Integration is a lightweight acceptance solution designed to safely and securely accept payment information within your web page. Microform is designed to a be embedded seamlessly within your existing webpage experience, blending in with your existing acceptance form. This solution allows for the replacement of sensitive payment date with a transient token (a short lived reference to the sensitive payment data). For more information about Flex Microform transactions, see the [Flex Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-flex/SAFlexibleToken.html). For examples on how to integrate Flex Microform within your webpage please see our [GitHub Flex Samples](https://github.com/CyberSource?q=flex&type=&language=)
- name: Flex_API
description: For more information about Flex API, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/da-flex-api-intro.html).
- name: Risk_Management
- name: Payouts
description: 'For more information about Payouts, see the [Payouts Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-payouts/Introduction.html).
'
- name: Installments
description: For more information about Installment contact Cybersource Support. For Visa installments contact VISthroughCYBS@visa.com
- name: Recurring_Billing_Subscriptions
description: For more information about Recurring Billing, see the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-developer/recur-bill-services-intro.html).
- name: BIN_Lookup
description: 'The BIN Lookup Service is a versatile business tool that provides card network agnostic solution designed to ensure frictionless transaction experience by utilizing up-to-date Bank Identification Number (BIN) attributes sourced from multiple global and regional data sources.
This service helps to improve authorization rates by helping to route transactions to the best-suited card network, minimizes fraud through card detail verification and aids in regulatory compliance by identifying card properties. The service is flexible and provides businesses with a flexible choice of inputs such as primary account number (PAN), network token from major networks (such as Visa, American Express, Discover and regional networks) which includes device PAN (DPAN), and all types of tokens generated via CyberSource Token Management Service (TMS).
Currently, the range of available credentials is contingent on the networks enabled for the business entity. Therefore, the network information specified in this documentation is illustrative and subject to personalized offerings for each reseller or merchant.
'
- name: Transaction_Details
description: For more information about Transaction Details, see the [Transaction Details Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_details_api.html).
- name: Transaction_Search
description: For more information about Transaction Search, see the [Transaction Search Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_search_api.html).
- name: Reporting
description: 'For more information about Reporting, see the [Reporting Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-reporting-rest-api-dev-guide-102718/reporting_api.html).
'
- name: Secure_File_Share
description: For more information about Secure File Share, see the [Secure File Share Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-secure-file-share-api-102718/secure_file_share_api_intro.html).
- name: Invoices
description: For more information about Invoicing, see the [Invoicing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/Introduction.html).
- name: Pay_By_Link
description: For more information about PayByLink, see the [PBL Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/boarding/user/all/rest/boarding/templates-matrix-intro/templates-matrix-pay-by-link.html).
- name: User_Management
description: For more information about User Management, see the [User Managment Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-user-management-api-102718/user_management_api_intro.html).
- name: Value_Added_Service
- name: Fee Service
- name: Merchant_Boarding
description: For more information about Merchant Boarding, please see [Developer Guides Page](https://developer.cybersource.com/api/developer-guides/Merchant-Boarding-API_ditamap/Merchant-Boarding-API.html).
- name: Webhooks
description: For more information about Webhooks, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html).
- name: Unified_Checkout
description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html).
- name: Unified_Checkoutv1
description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-about-guide.html).
- name: Account_Updater
description: For more information about Account Updater, see the [Account Updater Developer Guides Page:](https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html).
- name: Visa_Bank_Account_Validation
description: 'The Visa Bank Account Validation Service is a new standalone product designed to validate customer''s routing and bank account number combination for ACH transactions. Merchant''s can use this standalone product to validate their customer''s account prior to processing an ACH transaction against the customer''s account to comply with Nacha''s account validation mandate for Web-debit transactions.
'
- name: Currency Conversion
description: 'Empower global transactions with transparency and choice. Our Dynamic Currency Conversion API lets merchants offer customers the option to pay in their home currency at checkout, delivering real-time exchange rates and clear cost disclosure.
**Key Benefits:**
- **Enhanced Customer Experience:** Provide clarity and convenience for international shoppers.
- **Real-Time Rates:** Accurate currency conversion with all the data required for acquirers and their merchants to maintain compliance with card network rules.
- **Seamless Integration:** Flexible API endpoints for rate lookup, authorization, and capture.
- **Regulatory Compliance:** Provides the data required for acquirers and merchants to meet and maintain card scheme requirements for disclosure and consent.
Ideal for merchants and payment partners seeking to boost trust and conversion in cross-border commerce.
**Key Features:**
- **Rate Lookup:** Retrieves the most up-to-date exchange rate for eligible cards before authorization.
- **Currency Choice:** Enables the merchant to offer customers the option to select between the merchant''s local currency and their card''s billing currency.
- **Compliance:** Ensures merchants have the data required to adhere to card network regulations; exchange rates, markups, etc.
**Supported Scenarios:**
- Dynamic Currency Conversion when cardholder''s billing currency differs from merchant''s pricing currency.
- Merchant and acquirer must support the cardholder''s billing currency.
**Core API Endpoints:**
**Currency Conversion API**
Returns eligibility and exchange rate details, including:
- exchangeRate
- marginRate
- reconciliationId and Id (for subsequent payment requests)
**Payment Authorization with DCC***
POST /pts/v2/payments
Required fields include:
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.originalCurrency
- orderInformation.amountDetails.originalAmount
- orderInformation.amountDetails.exchangeRate
- currencyConversion.indicator (e.g., 1 = Converted, 2 = Nonconvertible, 3 = Declined)
**Capture with DCC***
POST /pts/v2/payments/{id}/captures
Maps from original authorization and includes original and converted amounts.
**Refund with DCC***
POST /pts/v2/captures/{id}/refunds
Maps from original authorization and includes original and converted amounts.
*Note: DCC is only supported on select processors. Contact your acquirer or account manager for more information.
**Compliance & Disclosure:**
Merchants must:
- Adhere to card network rules for Dynamic Currency Conversion (DCC) transactions.
- Display the converted amount, exchange rate, and markup percentage and other required disclosures.
- Obtain explicit cardholder consent before applying DCC.
- Work with your acquirer to obtain full set of compliance requirements.
For more information, see the [Currency Conversion Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/currency-conversion/developer/all/rest/currency-conversion/cc-intro.html).
'
- name: Intelligent_Commerce_Connect
description: For more information about Intelligent Commerce Cross Network Service API, please see [Developer Guides](https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-about-guide.html).