CyberSource Payer Authentication API
The Payer Authentication API from CyberSource — 3 operation(s) for payer authentication.
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 Payer Authentication API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Payer Authentication
paths:
/risk/v1/authentication-setups:
post:
summary: Setup Payer Auth
description: A new service for Merchants to get reference_id for Digital Wallets to use in place of BIN number in Cardinal. Set up file while authenticating with Cardinal. This service should be called by Merchant when payment instrument chosen or changes. This service has to be called before enrollment check. The availability of API features for a merchant may depend on the portfolio configuration and may need to be enabled at the portfolio level before they can be added to merchant accounts.
operationId: payerAuthSetup
tags:
- Payer Authentication
produces:
- application/hal+json;charset=utf-8
x-devcenter-metaData:
categoryTag: Payer_Authentication
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/payer-authentication/developer/all/rest/payer-auth/pa-about-guide.html
isMLEsupported: true
mleForRequest: optional
parameters:
- name: payerAuthSetupRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
pausedRequestId:
type: string
maxLength: 26
description: 'Used to resume a transaction that was paused for an order modification rule to allow for payer authentication to complete. To resume and continue with the authorization/decision service flow, call the services and include the request id from the prior decision call.
'
comments:
type: string
maxLength: 255
description: 'Brief description of the order or any comment you wish to add to the order.
'
partner:
type: object
properties:
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that helped integrate a partner solution to CyberSource.
Send this value in all requests that are sent through the partner solutions built by that developer.
CyberSource assigns the ID to the developer.
**Note** When you see a developer ID of 999 in reports, the developer ID that was submitted is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that is integrated to CyberSource.
Send this value in all requests that are sent through the partner solution. CyberSource assigns the ID to the partner.
**Note** When you see a solutionId of 999 in reports, the solutionId that was submitted is incorrect.
'
paymentInformation:
type: object
properties:
card:
type: object
required:
- expirationMonth
- expirationYear
- number
properties:
type:
type: string
description: 'Three-digit value that indicates the card type.
**IMPORTANT** It is strongly recommended that you include the card type field in request messages even if it is
optional for your processor and card type. Omitting the card type can cause the transaction to be processed with the wrong card type.
Possible values:
- `001`: Visa. Use card type value `001` for Visa Electron.
- `002`: Mastercard, Eurocard[^1], which is a European regional brand of Mastercard.
- `003`: American Express
- `004`: Discover
- `005`: Diners Club
- `006`: Carte Blanche[^1]
- `007`: JCB[^1]
- `008`: Optima
- `009`: GE Private Label
- `010`: Beneficial Private Label
- `011`: Twinpay Credit Card
- `012`: Twinpay Debit Card
- `013`: WalMart
- `014`: Enroute[^1]
- `015`: Lowe''s Consumer
- `016`: Home Depot Consumer
- `017`: MBNA
- `018`: Dick''s Sportswear
- `019`: Casual Corner
- `020`: Sears
- `021`: JAL[^1]
- `023`: Disney Card
- `024`: Maestro (UK Domestic)[^1]
- `025`: Sam''s Club Consumer
- `026`: Sam''s Club Business
- `027`: Nico''s
- `028`: Paymentech Bill Me Later
- `029`: Bebe
- `030`: Restoration Hardware
- `031`: Delta Online
- `032`: Solo
- `033`: Visa Electron[^1]. Do not use this value. Use `001` for all Visa card types.
- `034`: Dankort[^1]
- `035`: Laser
- `036`: Cartes Bancaires[^1,4]
- `037`: Carta Si[^1]
- `038`: Pinless Debit
- `039`: Encoded account number[^1]
- `040`: UATP[^1]
- `041`: HOUSEHOLD
- `042`: Maestro (International)[^1]
- `043`: GE MONEY
- `044`: Korean Cards
- `045`: Style Cards
- `046`: JCrew
- `047`: Payeasecn eWallet
- `048`: Payeasecn Bank Transfer
- `049`: Meijer
- `050`: Hipercard[^2,3]
- `051`: Aura
- `052`: Redecard
- `053`: Orico card
- `054`: Elo[^3]
- `055`: Capitol One Private Label
- `056`: Carnet
- `057`: Costco Private Label
- `058`: Carnet
- `059`: ValueLink
- `060`: MADA
- `061`: RuPay
- `062`: China UnionPay
- `063`: Falabella Private Label
- `064`: Prompt Card
- `065`: Korean Domestic
- `066`: Banricompras
- `067`: MEEZA
- `068`: PayPak
- `070`: EFTPOS
- `071`: Codensa
- `072`: Olimpica
- `073`: Colsubsidio
- `074`: Tuya
- `075`: Sodexo
- `076`: Naranja
- `077`: Cabal
- `078`: DINELCO
- `079`: PANAL
- `080`: EPM
- `081`: Jaywan
[^1]: For this card type, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in your request for an authorization or a stand-alone credit.
[^2]: For this card type on Cielo 3.0, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit. This card type is not supported on Cielo 1.5.
[^3]: For this card type on Getnet and Rede, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit.
[^4]: For this card type, you must include the `paymentInformation.card.type` in your request for any payer authentication services.
#### Used by
**Authorization**
Required for Carte Blanche and JCB.
Optional for all other card types.
#### Card Present reply
This field is included in the reply message when the client software that is installed on the POS terminal uses
the token management service (TMS) to retrieve tokenized payment details. You must contact customer support to
have your account enabled to receive these fields in the credit reply message.
Returned by the Credit service.
This reply field is only supported by the following processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
#### GPX
This field only supports transactions from the following card types:
- Visa
- Mastercard
- AMEX
- Discover
- Diners
- JCB
- Union Pay International
'
expirationMonth:
type: string
maxLength: 2
description: 'Two-digit month in which the payment card expires.
Format: `MM`.
Valid values: `01` through `12`. Leading 0 is required.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value
(`01` through `12`) but is not required to be a valid expiration date. In other words, an expiration date that is
in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause
the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (_type_=039), if there is no expiration date on the card, use `12`.
#### FDMS Nashville
Required field.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
'
expirationYear:
type: string
maxLength: 4
description: 'Four-digit year in which the payment card expires.
Format: `YYYY`.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value (`1900` through `3000`) but is not required to be a valid expiration date. In other words, an expiration date that is in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (**_type_**`=039`), if there is no expiration date on the card, use `2021`.
#### FDMS Nashville
Required field.
#### FDC Nashville Global and FDMS South
You can send in 2 digits or 4 digits. If you send in 2 digits, they must be the last 2 digits of the year.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
'
number:
type: string
maxLength: 20
description: 'The customer''s payment card number, also known as the Primary Account Number (PAN). You can also use this field
for encoded account numbers.
#### FDMS Nashville
Required. String (19)
#### GPX
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
#### All other processors
Required if `pointOfSaleInformation.entryMode=keyed`. However, this field is optional if your account is configured
for relaxed requirements for address data and expiration date. **Important** It is your responsibility to determine
whether a field is required for the transaction you are requesting.
'
tokenizedCard:
type: object
required:
- transactionType
- type
- expirationMonth
- expirationYear
- number
properties:
transactionType:
type: string
maxLength: 1
description: 'Type of transaction that provided the token data. This value does not specify the token service provider; it specifies the entity that
provided you with information about the token.
Possible value:
- `2`: Near-field communication (NFC) transaction. The customer''s mobile device provided the token data for a contactless EMV transaction. For recurring
transactions, use this value if the original transaction was a contactless EMV transaction.
#### Visa Platform Connect
- `1`: For Rupay and In App tokenization. Example: InApp apple pay.
- `3`: Card/Credential On File Tokenization.
**NOTE** No CyberSource through VisaNet acquirers support EMV at this time.
Required field for PIN debit credit or PIN debit purchase transactions that use payment network tokens; otherwise, not used.
#### Rupay
- `3`: Card/Credential On File Tokenization.
- `4`: Tokenizined Transaction. Should be used for Guest Checkout transactions with token.
'
type:
type: string
description: 'Three-digit value that indicates the card type.
**IMPORTANT** It is strongly recommended that you include the card type field in request messages even if it is
optional for your processor and card type. Omitting the card type can cause the transaction to be processed with the wrong card type.
Possible values:
- `001`: Visa. Use card type value `001` for Visa Electron.
- `002`: Mastercard, Eurocard[^1], which is a European regional brand of Mastercard.
- `003`: American Express
- `004`: Discover
- `005`: Diners Club
- `006`: Carte Blanche[^1]
- `007`: JCB[^1]
- `008`: Optima
- `009`: GE Private Label
- `010`: Beneficial Private Label
- `011`: Twinpay Credit Card
- `012`: Twinpay Debit Card
- `013`: WalMart
- `014`: Enroute[^1]
- `015`: Lowe''s Consumer
- `016`: Home Depot Consumer
- `017`: MBNA
- `018`: Dick''s Sportswear
- `019`: Casual Corner
- `020`: Sears
- `021`: JAL[^1]
- `023`: Disney Card
- `024`: Maestro (UK Domestic)[^1]
- `025`: Sam''s Club Consumer
- `026`: Sam''s Club Business
- `027`: Nico''s
- `028`: Paymentech Bill Me Later
- `029`: Bebe
- `030`: Restoration Hardware
- `031`: Delta Online
- `032`: Solo
- `033`: Visa Electron[^1]. Do not use this value. Use `001` for all Visa card types.
- `034`: Dankort[^1]
- `035`: Laser
- `036`: Cartes Bancaires[^1,4]
- `037`: Carta Si[^1]
- `038`: Pinless Debit
- `039`: Encoded account number[^1]
- `040`: UATP[^1]
- `041`: HOUSEHOLD
- `042`: Maestro (International)[^1]
- `043`: GE MONEY
- `044`: Korean Cards
- `045`: Style Cards
- `046`: JCrew
- `047`: Payeasecn eWallet
- `048`: Payeasecn Bank Transfer
- `049`: Meijer
- `050`: Hipercard[^2,3]
- `051`: Aura
- `052`: Redecard
- `053`: Orico card
- `054`: Elo[^3]
- `055`: Capitol One Private Label
- `056`: Carnet
- `057`: Costco Private Label
- `058`: Carnet
- `059`: ValueLink
- `060`: MADA
- `061`: RuPay
- `062`: China UnionPay
- `063`: Falabella Private Label
- `064`: Prompt Card
- `065`: Korean Domestic
- `066`: Banricompras
- `067`: MEEZA
- `068`: PayPak
- `070`: EFTPOS
- `071`: Codensa
- `072`: Olimpica
- `073`: Colsubsidio
- `074`: Tuya
- `075`: Sodexo
- `076`: Naranja
- `077`: Cabal
- `078`: DINELCO
- `079`: PANAL
- `080`: EPM
- `081`: Jaywan
[^1]: For this card type, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in your request for an authorization or a stand-alone credit.
[^2]: For this card type on Cielo 3.0, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit. This card type is not supported on Cielo 1.5.
[^3]: For this card type on Getnet and Rede, you must include the `paymentInformation.card.type` or `paymentInformation.tokenizedCard.type` field in a request for an authorization or a stand-alone credit.
[^4]: For this card type, you must include the `paymentInformation.card.type` in your request for any payer authentication services.
#### Used by
**Authorization**
Required for Carte Blanche and JCB.
Optional for all other card types.
#### Card Present reply
This field is included in the reply message when the client software that is installed on the POS terminal uses
the token management service (TMS) to retrieve tokenized payment details. You must contact customer support to
have your account enabled to receive these fields in the credit reply message.
Returned by the Credit service.
This reply field is only supported by the following processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
#### Google Pay transactions
For PAN-based Google Pay transactions, this field is returned in the API response.
#### GPX
This field only supports transactions from the following card types:
- Visa
- Mastercard
- AMEX
- Discover
- Diners
- JCB
- Union Pay International
'
expirationMonth:
type: string
maxLength: 2
description: 'One of two possible meanings:
- The two-digit month in which a token expires.
- The two-digit month in which a card expires.
Format: `MM`
Possible values: `01` through `12`
**NOTE** The meaning of this field is dependent on the payment processor that is returning the value in an authorization reply. Please see the processor-specific details below.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value (`01` through `12`) but is not required to be a valid expiration date. In other words, an expiration date that is in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (`card_type=039`), if there is no expiration date on the card, use `12`.\
**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.
#### Samsung Pay and Apple Pay
Month in which the token expires. CyberSource includes this field in the reply message when it decrypts the payment blob for the tokenized transaction.
'
expirationYear:
type: string
maxLength: 4
description: 'One of two possible meanings:
- The four-digit year in which a token expires.
- The four-digit year in which a card expires.
Format: `YYYY`
Possible values: `1900` through `3000`
Data type: Non-negative integer
**NOTE** The meaning of this field is dependent on the payment processor that is returning the value in an authorization reply. Please see the processor-specific details below.
#### Barclays and Streamline
For Maestro (UK Domestic) and Maestro (International) cards on Barclays and Streamline, this must be a valid value (1900 through
3000) but is not required to be a valid expiration date. In other words, an expiration date that is in the past does not cause CyberSource to reject your request. However, an invalid expiration date might cause the issuer to reject your request.
#### Encoded Account Numbers
For encoded account numbers (`card_ type=039`), if there is no expiration date on the card, use `2021`.
#### FDC Nashville Global and FDMS South
You can send in 2 digits or 4 digits. When you send in 2 digits, they must be the last 2 digits of
the year.
#### Samsung Pay and Apple Pay
Year in which the token expires. CyberSource includes this field in the reply message when it decrypts the payment blob for the tokenized transaction.
**Important** It is your responsibility to determine whether a field is required for the transaction
you are requesting.
'
number:
type: string
maxLength: 20
description: 'Customer''s payment network token value.
'
fluidData:
type: object
required:
- value
properties:
value:
type: string
maxLength: 4000
description: 'Represents the encrypted payment data BLOB. The entry for this field is dependent on the payment solution used by the merchant.
Used by Authorization and Standalone Credits. Required for authorizations and standalone credits that use a Cybersource suppored Point-to-Point encryption method.
Card Present processing
This field represents the encrypted payment data generated by the payment terminal/device.
'
keySerialNumber:
type: string
description: 'The encoded or encrypted value that a payment solution returns for an authorization request. For details about the valid values for a key, see [Creating an Online Authorization](https://developer.cybersource.com/api/developer-guides/dita-payments/CreatingOnlineAuth.html)
'
descriptor:
type: string
maxLength: 128
description: 'The identifier for a payment solution, which is sending the encrypted payment data for decryption. Valid values:
Samsung Pay: RklEPUNPTU1PTi5TQU1TVU5HLklOQVBQLlBBWU1FTlQ=
Note: For other payment solutions, the value may be specific to the terminal or device initiatinf the payment. For example, the descriptor for a Bluefin payment encryption would be a device-generated descriptor.
Used by Authorization and Standalone Credits. Required for authorizations and standalone credits.
Card Present processing:
Format of the encrypted payment data.
The value for Bluefin PCI P2PE is `Ymx1ZWZpbg==`. paymentInformation.fluidData.encoding must be `Base64`.
The value for Cybersource P2PE decryption depends on the encoding method used and identified in encoding field.
If paymentInformation.fluidData.encoding is `Base64`, the value is: `RklEPUVNVi5QQVlNRU5ULkFQSQ==`
If paymentInformation.fluidData.encoding is `HEX`, the value is: `4649443D454D562E5041594D454E542E41504`
'
encoding:
type: string
maxLength: 6
description: 'Encoding method used to encrypt the payment data.
Valid values: `Base64`, `HEX`
If no value is provided, `Base64` is taken as the default value. And the `Base64` descriptor is used for paymentInformation.fluidData.encoding
'
customer:
type: object
required:
- customerId
properties:
customerId:
type: string
description: 'Unique identifier for the legacy Secure Storage token used in the transaction.
When you include this value in your request, many of the fields that are normally required for an authorization or credit
become optional.
'
minLength: 1
maxLength: 32
processingInformation:
type: object
properties:
paymentSolution:
type: string
maxLength: 12
description: "Type of digital payment solution for the transaction. Possible Values:\n\n - `visacheckout`: Visa Checkout. This value is required for Visa Checkout transactions. For details, see `payment_solutio
# --- truncated at 32 KB (317 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-payer-authentication-api-openapi.yml