Payment Credentials API

This section contains the information you need to retrieve the full payment credentials collected by the Unified Checkout tool using the payment credentials API. The payment information is returned in a redundantly signed and encrypted payment object. It uses the JSON Web Tokens (JWTs) as the data standard for communicating this sensitive data.

IMPORTANT

Payment information returned by the

payment-credentials

endpoint will contain Personal Identifiable Information (PII). Retrieving this sensitive information requires your system to comply with PCI security standards. For more information on PCI security standards, see: https://www.pcisecuritystandards.org/

The response is returned using a JWE data object that is encrypted with your public key created during the Unified Checkout tool's integration. For more information, see Upload Your Encryption Key.

To decrypt the JWE response, use your private key created during the Unified Checkout tool's integration. The decrypted content is a JWS data object containing a JSON payload. This payload can be validated with the Unified Checkout public signature key.

IMPORTANT

When integrating with Cybersource APIs, Cybersource recommends that you dynamically parse the response for the fields that you are looking for. Additional fields may be added in the future.

You must ensure that your integration can handle new fields that are returned in the response. While the underlying data structures will not change, you must also ensure that your integration can handle changes to the order in which the data is returned. Cybersource uses semantic versioning practices, which enables you to retain backwards compatibility as new fields are introduced in minor version updates.

Returned Credentials

A payment account number (PAN) or network token is returned on your request depending on your payment method and Click to Pay account status:

Payment Credentials Returned by Card Type and `Click to Pay` Account Status
`Click to Pay` Account Status	American Express	Mastercard	Visa
New card not saved in `Click to Pay`	PAN	PAN	PAN
New card saved in `Click to Pay`	PAN	Network Token	Network Token
Existing card stored in `Click to Pay`	PAN	Network Token	Network Token

When you retrieve PAN information from the Payment Credentials API, the response includes the PAN, card expiration date, and the card verification value (CVV). When you retrieve network token information, the response includes the network token and network token cryptogram.

IMPORTANT

Visa and Mastercard always attempt to provision a network token. When a network token is not provisioned, the default payment method is the PAN. When there is a PAN transaction, the PAN is not stored in the consumers wallet and it is treated as a single transaction.

Network tokens are generated in the wallet of the Click to Pay token requestor ID (TRID). When tokenization is successful, Visa attempts to complete authentication during the Click to Pay experience. For information on authentication, see Customer Authentication.

You must meet these requirements for tokenization to be successfully configured for your merchant ID (MID):

Click to Pay is enabled as a digital payment in the Business Center.

The transacting MID is configured for tokenization with Click to Pay. Contact your Implementation Consultant or Technical Account Manager to configure tokenization with Click to Pay.

The

allowedPaymentTypes

field value is set to

CLICKTOPAY

in the capture context. For information on the capture context, see Capture Context API.

Endpoint

Production:

GET https://api.cybersource.com/flex/v2/payment-credentials/{ReferenceID}

Test:

GET https://apitest.cybersource.com/flex/v2/payment-credentials/{ReferenceID}

The

{ReferenceID}

is the reference ID returned in the

field when you created the payment credentials.

Required Field for Retrieving Payment Credentials

Your payment credentials request must include this field:

ReferenceID: The reference ID that is returned in the
id
field when you created the payment credentials.

REST Example: Retrieving Payment Credentials

Request

1
https://api.cybersource.com/flex/v2/payment-credentials/E-firqlLk7GiziQwXxAsq

Encrypted Response to Successful Request

1234567891011121314151617181920212223
eyJhdWQiOiJwc3AiLCJzdWIiOiJwc19ocGEiLCJraWQiOiIyMDIzMDUxNC1kcmFmdC1wc3AtZW5jcnlwdCIsIIsImp0aSI6IjA0NDUwNWNiLTM1ZDYtNDU2ZS05OTBlLWRkZjQwYzI5NzlhNCJ9.enhUfZJOjbMX-wZPIOb1zj
8sFZiix6JSJyNw2i9QJ4k_hd7Iy_UMYvOmS-X1FJwjH0IQxMIblSV8XqMegIOm5dYBYdqouUfC8zq4Zm_dsMo
Tp3m9T6z-A_eJ8MGaxqTHSf2vWiXB-EMrww2eCXPyVTBkI1OdmYIX-s85vsqYpW-s0ThlCKaGI7B4_rJKNa7m
ou9VMBtBnfzhHLtnHDW8vsX8rLmTT76Ct2jMdIoQnlQRgEOi-zYu0Jm0gHERavUtq_7lDw9Ta73_TFw3KA2fs
G13CURyR7ZXoZy9_nRifwHjwNVbaFRceAzXoVtvM8H8F-ZzIC8AdA1FRye7RqcK9Q.OlrMxOMDkVDU6goS.TP
fBhm1eBfRjCSSvuT6SxFeZ3SGwOC6qX2Z4rlAEY9lOor2Q2E1CMqB6o-q6DNkGtASFONBzKtoB0yAgXBpx3S7
2FltR8bd40qmRnPyTOAscXa3eWbP45EqZqHW58lwUtMwcBORcfSjxPnWUo-OGmKCtIgiUO4MTlBsl9HdCLx7R
Wpwslo0pKQAuFrURHJyhdE1JUArgjNQMdQwPvCjoZ2RxTzECEqE1l0KmBGM-w8suowrnTNZl8cwVUZKzHQEJV
-twAGykQIIRCI3ydHfCupyUuA-5-Wvlk6nhcL3qND4JF-E3EIRpzm7WH8pCV5nzByUue-grHejg774c7fi1eh
fTBUZ8v6X7rTZUBLL0V5343X3zQQy_G-vq5qcaJZ8AS2XWSi17r8UEHoU5emYu5QAuXy1AhL32nDRZuXzOzQ1
9JsrTN2CD8qxU7tDpkUCEmY2GEMp4sd-rfu_2qBZDdr74tjYNgMsTIXSpgGDiwjLMJu4r460YencO6-JweGCT
8woIySjBRYpX1_axxcO6I9RUTSopPbslZwq_zpy3UuDa9InlSexM--fatYfAehY857F7bFVXlnXeqr7X0_Lri
bJsx6CWJU1ihjMVtnF-SxeE3IdpJxyFYBb7D1iL3ywFooxcGqarXU-3_CBuDHvnJFDC_iQPaeH7csb-EMeNqF
TmFf8dWNQYG7IJDfEnrnRW_XtnczH-ZS67iVuGzGwJZDQfJZ-KLhnWr6FE1EnT1VLyXPM78WeocT7cnLXmr9B
gevNmU3q_SV5nxlDLPuCqF0PmFNxaTjqfF2Qw_zOCvazwFWuBdUDdHilPqhj3gfsOesAJVA7VoTDw2U3zte3V
09KcJLaHygwPomopWOODinKzcZeWfJ39984pQa5cOMSEToGegkRZyvSxpf5PTht30uB3F3qC4cVLOu4qukYsr
jXqOtxg3icde7lXywfAtEZgf54jAP2Cl8JFmGWL5YnIY44-zj-GVz2C8iCN1CCUP3U4eVxz2GtxNNSXuwY8OR
Udino4rF-OpqqdjX5F0Uw6J2D3uR9cWB4Ee3v8TIA3-tRkG4ScAcclEwjkwsILPgVLU57HOm0AnaEsznyHrd9
-Qfz_p-UjbsaD3e-_sr56-x2UZVVL6TAMmJqmS2C55CHgkkhtHBCu-vb0KOmssopIvaQA5jK6ZoCftewE8-98
816ZmoU8Sty05PSeK0yBlxFwTIeJxt-moszRawFuBrLAbOu72y_eeUtk1tHpHV2Db7T6XvaRD4NvOFZg8ianY
Y6uHidoTl1ApjCp8VG9oTJ-uKWAEp9TU6qEHUswZZUIBeGTKjzBkRAQ20cZs5POb-qtjteoWo9QdnczipZ8de
my-FSZwNRFPkeedl3oHLepeTgwVnmij9ovk0e5Wqq2GVUMe8sLa-4eEnjliIjAVUQ9YNJBeqLf6_wo3HF8o2k
4ZgSJTuPHAuP41-.TaLt6G8QyRykbrxb0iV9Jg

Decrypted Response to Successful Request

123456789101112131415161718192021222324252627282930313233343536373839404142
{// header
  kid = "zu"
  cty = "json+pc"
}.
{
  // registered claims
  iss = "https://flex.visa.com"            
  sub = "ps_hpa"                                  // Merchant ID 
  aud = "https://online.MyBank.com"              
  exp = 1683105553                                // expiry of payment credentials
  iat = 1683104035                                // timestamp when JWT was created
  jti = "ae798686-a849-4dfa-836d-43e09cb183a4"    // transaction id
  
  "paymentInformation": {    
    "tokenizedCard": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "type": "001",
      "cryptogram": "",
      "transactionType": "1"
    }    
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "102.21",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1 Market St",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@cybs.com",
      "phoneNumber": "4158880000"
    }
  }
}
.