OAuth 2.0

This document is for technology partners who want to register their OAuth application with Cybersource. Merchants can then delegate access to a technology partner to take actions on their behalf without sharing security keys. Actions can include accessing customer data and processing transactions.

OAuth is an industry-standard authorization protocol that enables an application to delegate limited access to another application. You can find out more about the OAuth open technical standard at OAuth.

OAuth is currently in the pilot phase. To join our pilot program, and to understand which API requests are OAuth-enabled, contact us.

Workflow Overview

The following overview provides the steps that you and the merchant must take to implement OAuth.

You enable mutual authentication by obtaining a Certificate Signing Request from Entrust and submitting your common name details to Cybersource. The certificate
must
be from Entrust.

You register your application in the Cybersource Business Center. During registration, you must provide a scope of permissions and a redirect URL. The product is still changing, so contact us to understand which APIs and scopes are enabled for OAuth.

The merchant visits your application, enters form information, and clicks a link or button to continue the process.

Your application redirects the merchant to Cybersource.

The merchant signs into their Cybersource account and grants or denies permissions to your application within the scopes that you provided in Step 2. Remind the merchant that the Cybersource account that they use must have sufficient account permissions to grant or deny these OAuth permissions.

Cybersource redirects the merchant to your application using the redirect URL that you provided during registration. If the merchant grants the permissions, an authorization code is appended to the redirect URL.

Your application calls Cybersource and exchanges the authorization code for an access token that you can use to authenticate transactions with Cybersource, as well as a refresh token that you can use to request additional access tokens.

You can view a sample of these workflow steps by using our demo application. You can also view the code for that sample application.

You must obtain test merchant credentials to emulate the access delegation. Your test account must contain at least one card-based transaction from within the past 7 days.

To test your own application, you can use the certificate that is available with the Cybersource sample application code, hosted on Github.

To change the scopes that you set in Step 2, you must repeat Steps 2 through 7.

Enabling Mutual Authentication

OAuth uses mutual authentication to provide an additional layer of security. Mutual authentication occurs when two parties authenticate each other at the same time. A server-to-server certificate from Entrust must be used for mutual authentication. Before registering your application, follow these steps. To complete Steps 1-3, contact Entrust support.

Create a new key pair and Certificate Signing Request, using a server-to-server certificate from Entrust.

Submit the Certificate Signing Request (CSR) to Entrust Certificate Support and provide the required details.

Entrust verifies your request, and if they approve it, they issue the certificate in an email to the technical contact for your account.

Share the certificate's common name with your Cybersource technical contact, and the contact will java.io.PrintWriter@7cc582d1 add it to the Cybersource whitelist.

To test your own application, you can use the certificate that is available with the Cybersource sample application code, hosted on Github.

Registering Your Application

Before you can use OAuth credentials to connect to Cybersource, you must register your application in the Business Center. Test and Production environments have separate interfaces. To obtain credentials, contact us .

ADDITIONAL INFORMATION

Test:
https://businesscentertest.cybersource.com

Production:
https://businesscenter.cybersource.com

Click

Account Management

in the left-navigation menu and choose

Authorized Applications

. The OAuth Authorized Applications page appears.

Click

Add Application

. You must use an administrator account to add or change an application.

Enter the following information:

Name of the application that you are registering.

Description of the application.

URL to redirect the merchant to your system after they grant permissions. For more information about the redirect, see Redirecting the Merchant to Cybersource.

Choose permissions for individual APIs or for all listed APIs.

Click

Save

. Your application is registered, and your application’s client ID and client secret are shown. You will need them in order to redirect the merchant. Treat the client ID and client secret as confidential information and store them securely. You can regenerate your client secret if you misplace it or if its security is compromised.

Click

Done

to return to the previous page.

Integrating OAuth into Your System

When your application is registered and you have received the client ID and client secret, you can begin integrating OAuth into your system.

Requesting the Access and Refresh Tokens

Use the authorization code from the redirect response to request an initial access token, as well as a refresh token, from the

/oauth/v3/token

endpoint. While a header is not required, we recommend including the header

v-c-client-correlation-id

with a unique value for every request to the

/oauth/v3/token

endpoint. For security, all parameters must be sent in the body and use the HTTPS protocol. Do not place any parameters in the URL.

Test URL
:

api-matest.cybersource.com

Production URL
:

api-ma.cybersource.com

Sample Token Request

    POST 
      https://api-ma.cybersource.com
      /oauth2/v3/token
Content-Type: application/x-www-form-urlencoded

client_id=8l57hYffFb&grant_type=refresh_token&code=eyJraK&client_secret=yourClientSecret

Access Token Request Parameters
Parameter Name	Value	Description
grant_type	authorization_code	Required. Determines which type of flow the Authorization Server uses to acquire user authorization.
code	The authorization code received from the redirect response.	Required. The value passed in this parameter must exactly match the value supplied by the OAuth server during the authorization step.
client_id	The client ID obtained during client registration.	Required. Indicates the client that is making the request.
client_secret	The client secret value obtained during client registration.	Required. You received this value when you registered your application with `Cybersource`.

Sample Response for Access Token Request

    HTTP/1.1 200 OK 

Content-Type: application/json;charset=UTF-8 

Cache-Control: no-store 

Pragma: no-cache 

{ 

"access_token": "eyJraWQiOiIxMGM2MTYxNzg2MzE2ZWMzMGJjZmI5ZDcyZGU4MzFjOSIsImFsZyI6IlJTMjU2In0.
 eyJqdGkiOiI5YTM0MWVkZC0zY2ViLTRiMzYtYjQyMy05MDg4ZTliYWQ1YTAiLCJzY29wZXMiOlsiYWx0ZXJuYXRlX3B
 heW1lbnRzIiwiYmFua190cmFuc2ZlcnMiLCJib2FyZGluZyIsImNvbW1lcmNlX3NlcnZpY2VzIiwiZnJhdWRfbWFuYW
 dlbWVudCIsImludm9pY2luZyIsImtleXMiLCJtYW5hZ2Vfc2VjdXJlX2FjY2VwdGFuY2UiLCJwYXltZW50c193aXRoX
 3N0YW5kYWxvbmVfY3JlZGl0IiwicGF5bWVudHNfd2l0aG91dF9zdGFuZGFsb25lX2NyZWRpdCIsInBheW91dHMiLCJy
 ZXBvcnRpbmciLCJ0b2tlbml6YXRpb25fc2VydmljZXMiLCJ0cmFuc2FjdGlvbnMiLCJ1c2VycyJdLCJpYXQiOjE2MTk
 1MTg3MzY4OTUsImFzc29jaWF0ZWRfaWQiOiJzYW1wbGVwYXJ0bmVyIiwiY2xpZW50X2lkIjoidjZUSkgxSXFoTSIsIm1
 lcmNoYW50X2lkIjoicmFodWxyYW1hIiwiZXhwaXJlc19pbiI6MTYxOTUxOTYzNjg5NSwiZ3JhbnRfdHlwZSI6ImF1dGh
 vcml6YXRpb25fY29kZSIsImdyYW50X3RpbWUiOiIyMDIxMDQyNzAzMTgifQ.jhjH9_xxleoNKgidD9oduVuUqDGov2X6
 22gzh99_QeocFc-7KsndsdaaUqglRpfY8juCbtRIe8RhLa5_hIoKF3ZU3XJ4WnQeAXdbznjf0SfK2SHpih-Tl2u_Ufsl
 Q7WjJM3OVDRcV3udMKfe6ACX0_uH81vRobRK43kk1RjrKuQSWz6KRRmSGrHJWl2sbo0gdEQEZpnGQwVcJuGKYalOk6Xq
 vglu2nD7iNyZpaaXOJHVDqxNdQdz8vfkofBPFVcTMjx8cHge3gDOFWDce5-TIU2EGdD_nUUfh8OfXaMrvv6nBriKzG96
 j7SQm3BXfwfm6SzSIyBpiti3sgwGJs-vGA", 

"token_type": "bearer", 

"refresh_token": "eyJraWQiOiIxMGM2MTYxNzg2MzE2ZWMzMGJjZmI5ZDcyZGU4MzFjOSIsImFsZyI6IlJTMjU2In0.
 eyJqdGkiOiJmMTA2YjU1Yy00MjA1LTRjZDctOTkzNy04MzM3YTdjNmZmYWMiLCJzY29wZXMiOlsiYWx0ZXJuYXRlX3Bhe
 W1lbnRzIiwiYmFua190cmFuc2ZlcnMiLCJib2FyZGluZyIsImNvbW1lcmNlX3NlcnZpY2VzIiwiZnJhdWRfbWFuYWdlbW
 VudCIsImludm9pY2luZyIsImtleXMiLCJtYW5hZ2Vfc2VjdXJlX2FjY2VwdGFuY2UiLCJwYXltZW50c193aXRoX3N0YW5
 kYWxvbmVfY3JlZGl0IiwicGF5bWVudHNfd2l0aG91dF9zdGFuZGFsb25lX2NyZWRpdCIsInBheW91dHMiLCJyZXBvcnRp
 bmciLCJ0b2tlbml6YXRpb25fc2VydmljZXMiLCJ0cmFuc2FjdGlvbnMiLCJ1c2VycyJdLCJpYXQiOjE2MTk1MTg3MzY4O
 DksImFzc29jaWF0ZWRfaWQiOiJzYW1wbGVwYXJ0bmVyIiwiY2xpZW50X2lkIjoidjZUSkgxSXFoTSIsIm1lcmNoYW50X2
 lkIjoicmFodWxyYW1hIiwiZXhwaXJlc19pbiI6MTY1MTA1NDczNjg4OCwidG9rZW5fdHlwZSI6InJlZnJlc2hfdG9rZW4
 iLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbl9jb2RlIiwiZ3JhbnRfdGltZSI6IjIwMjEwNDI3MDMxOCJ9.Sj5y5ld
 pM4-ie5YT6_ARu6H0Ikd7jOhNvKsWgDB5NTxHvbyS5ciMidAIvxoxOXS_0vPpf1u865w8Qu8yT82iHHbNxyjjBXy03wbS
 utJBen_5roFUi6XE7KFgZPKL2hixmRVgivTrA8uAZ798Griv0PUOPnm6y6AzmK1ffmwdSNejKBdvz3_38TLLJk_0ylkRp
 D9akM8bSpDMSJJLNd3_eER5jdOQWRlqgaC030crrksS7o-vFJxXsK3MN0-_qnVqV5-l-8vhjJ0VUzg66eUgIyphIzU2c0
 M2J9d5tJVncHqOFz8N8HUZ800xKxMKH1MlB7F3L8alJJ04Jk6edT0KXA", 

"expires_in": 899, 

"scope": "transactions", 

"refresh_token_expires_in": 31535999, 

"client_status": "active" 

}

Error Responses for Token Request
Error Code	Description
access_denied	The resource owner or authorization server denied the request.
server_error	The authorization server encountered an unexpected condition that prevented it from fulfilling the request. This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client by an HTTP redirect.
invalid_scope	The requested scope is invalid, unknown, or malformed.
invalid_client	The requested client ID is invalid, unknown, or malformed.
invalid_request	The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client	The client is not authorized to request an authorization code.
invalid_redirect_uri	The requested redirect URI is invalid, unknown, or malformed.
client_not_found	The requested client ID is not found in the system.
invalid_client_type	The requested client ID is registered with an invalid client type (only confidential clients are supported).
merchant_not_active	The authorization could not be completed because the merchant's `Cybersource` account is inactive.
client_not_active	The authorization could not be completed because your `Cybersource` Partner Account is not currently listed as active. Contact customer support for assistance.

Submitting API Requests Using OAuth

You can submit API requests on behalf of the merchant using the access token. The access token expires after fifteen minutes.

Place the access token in an

Authorization

header as shown below.

Not all API endpoints are currently enabled for OAuth. For a list of OAuth-enabled endpoints, contact us .

    Authorization: Bearer eyJraWQiOiIyNmRjfjVkZTdlMmYwYTI0ODg0MjU1YjIwZWJjMGY0MSIsImFs

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN""
      https://api-ma.cybersource.com
      /pts/v2/payments"

Refreshing the Access Token

Access tokens expire after 15 minutes and refresh tokens expire after a year. To refresh the access token using the refresh token, follow the example below. We recommend including the header

v-c-client-correlation-id

with a unique value for every request to

/token

Request to Refresh the Access Token

    POST 
      https://api-ma.cybersource.com
      /oauth2/v3/token 
Content-Type: application/x-www-form-urlencoded
 
      client_id
      =8l57hYffFb&
      client_secret
      =yourClientSecret&
      grant_type
      =refresh_token&
      refresh_token
      
  =eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI0N2E4OGY0
   MS04ZTI5LTRhMTQtOWZlYi0wZjM0OTM2ZDk0M2QiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6
   MTQ3MTU3MDEyODQ5OCwiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19p
   biI6MTQ3MTU5ODkyODQ5OH0.lDvGlZvjkgY5pcJEG5Y1d6o7mOiZA-up2MsGm6zVhZdZxiSDt7md7Ih4_Lkko63_-Fz6UXMg
   7SLt6ypVJqn3u2iqKRy8aiuSxhQCwAuenoqFFdsFEEqlqkEtDZeo6B3_YrrTeCdjyP_cpLf7vr9GKJS3k5snYGhL8sZrEQMx
   JaQsyz6F_IPrxajmMiLt4nJUJJgRTjF-krt8p-BBLGxOYCBXe8UPrpsmLnxlEPiwJcFYREimEMSkeD2uDShWXe-ociLWFtoX
   mYx50TDk_fx2hKRaOVHtnaQJdsgtnQrlc0UkFAOzp9fU45O2Vei7x8SPNA47NdoR1XmPK2ZnXm_TIA

Response from Refresh Request

    HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZy
I6IlJTMjU2In0.eyJqdGkiOiI0Y2E5NGUyNy04NzkzLTRmOGQtYjY4YS01OWM0MjMwODlhZDAiLCJzY
29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjM0MiwiY2xpZW50
X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU
5ODk5NjM0Mn0.cmYor7iW6lxRCiM3kWPKauMsiKNGwRrrRFKowcTdkRQewqbQ0Mn9As1RhZwDKL4dux
CzAzLw4e8aV8PUyd2-_eCUsqbPMWLWjGo75eU8GI9rrvSGTxEP-fr6jPAr-jBJekQTzMLgkKVtSGaJg
tz08dHqrJnrejR8rZs4h1GpPMk6i99cOVMHjuTV7ZzognvkLKj_OR01H4XK5M8TWH5uoAXWrII3K-JJ
V1YkzjpVkpS0tVXTIXJI-pk_eNeBaJ7Q6in9X3xQKXnIqA8I8zxZt3LNnxR-aui2yufzP5BDh2kfwU0
B1Uq8fEuqNmbj4HN1NrmnTHkRJTZ4ooYoqAQtnQ",

"token_type": "bearer",

"refresh_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZ
yI6IlJTMjU2In0.eyJqdGkiOiI4N2IxNDg2MC03YzI0LTQ0NmQtOWJlYS05Mzk2ZDI3MmNmOWQiLCJz
Y29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjMyMywiY2xpZW5
0X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MT
U5ODk5NjMyM30.Fn8ZlXgvGBr-uvDi6e7-72g8tP-u42T5FNW5NW4YQ7GkrMqUEthexGc9NOcf6uWYf
SD4EiSbDVO8EIojZzIUgyXmG3tYDgSejFcDSPcMrF11m9WkOcapbIFTnFk2OyPVi48BVZ6vNb7j2184
pJ3KHKoq9E7qlaKrEbvBn2HRVdtvb1yj1Xv1tH38I6Qong8xMAEMCcIfzTinEOFIbENYzgxBsSNVrS1
5CYtDRFEDPGmAVPzd4I7HN_ed-pzOET3YbUBBQUbrAuZSrSrBcgfBCtT9C5szd7tYXmi-1AMVdFybnV
XArAXsDX0nZzm-PuCi_DGKMJET0sY2QNyesyKv8w",

"expires_in": 28798,

"scope": "payments_with_standalone_credit",

"refresh_token_expires_in": 28799,

"client_status": "active"

Any token request failure results in an HTTP status code of

500 Server error

. Correct any errors and resend.

Refreshing the Refresh Token

Access tokens expire after 15 minutes and refresh tokens expire after a year. Merchants are not required to reapprove access after a year; the refresh token's expiration resets to one year after the last successful access token request. You are not required to use an authorization code to make this call.

Below is an example of a request to obtain a new refresh token. We recommend including the header 

v-c-client-correlation-id

 with a unique value for every request to the 

/token

endpoint.

Any token request failure results in an HTTP status code of 500 - Server error. Correct any errors and resend. 

We provide a 6-month grace period to request a new refresh token. The new refresh token will expire one year from the last refresh token request. If the merchant has not had any activity within that grace period, they must be prompted to grant authorization and delegate access.

Request to Refresh the Refresh Token

    
POST 
      https://api-ma.cybersource.com
      /oauth2/v3/token 

Content-Type: application/x-www-form-urlencoded 

client_id 
=8l57hYffFb& 

client_secret 
=yourClientSecret& 

grant_type 
=refresh_token& 

refresh_token 
=eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.
 eyJqdGkiOiI0N2E4OGY0MS04ZTI5LTRhMTQtOWZlYi0wZjM0OTM2ZDk0M2QiLCJzY29wZXMiOlsi
 cmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDEyODQ5OCwiY2xpZW50X2lkIjoi
 OGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODky
 ODQ5OH0.lDvGlZvjkgY5pcJEG5Y1d6o7mOiZA-up2MsGm6zVhZdZxiSDt7md7Ih4_Lkko63_
 -Fz6UXMg7SLt6ypVJqn3u2iqKRy8aiuSxhQCwAuenoqFFdsFEEqlqkEtDZeo6B3_YrrTeCdjyP_
 cpLf7vr9GKJS3k5snYGhL8sZrEQMxJaQsyz6F_IPrxajmMiLt4nJUJJgRTjF-krt8p-BBLGxOYCB
 Xe8UPrpsmLnxlEPiwJcFYREimEMSkeD2uDShWXe-ociLWFtoXmYx50TDk_fx2hKRaOVHtnaQJdsg
 tnQrlc0UkFAOzp9fU45O2Vei7x8SPNA47NdoR1XmPK2ZnXm_TIA

Response from Refreshing the Refresh Request

    
HTTP/1.1 200 OK 

Content-Type: application/json;charset=UTF-8 

Cache-Control: no-store 

Pragma: no-cache 

{ 

"access_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCI
 sImFsZyI6IlJTMjU2In0.eyJqdGkiOiI0Y2E5NGUyNy04NzkzLTRmOGQtYjY4YS01OWM0Mj
 MwODlhZDAiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3M
 TU3MDE5NjM0MiwiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1
 MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjM0Mn0.cmYor7iW6lxRCiM3kWPKauMsiKN
 GwRrrRFKowcTdkRQewqbQ0Mn9As1RhZwDKL4duxCzAzLw4e8aV8PUyd2-_eCUsqbPMWLWjG
 o75eU8GI9rrvSGTxEP-fr6jPAr-jBJekQTzMLgkKVtSGaJgtz08dHqrJnrejR8rZs4h1GpP
 Mk6i99cOVMHjuTV7ZzognvkLKj_OR01H4XK5M8TWH5uoAXWrII3K-JJV1YkzjpVkpS0tVXTIXJI-pk_
 eNeBaJ7Q6in9X3xQKXnIqA8I8zxZt3LNnxR-aui2yufzP5BDh2kfwU0B1Uq8fEuqNmbj4HN1NrmnTHkRJTZ4ooYoqAQtnQ", 

"token_type": "bearer", 

"refresh_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCI
 sImFsZyI6IlJTMjU2In0.eyJqdGkiOiI4N2IxNDg2MC03YzI0LTQ0NmQtOWJlYS05Mzk2ZDI
 3MmNmOWQiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU
 3MDE5NjMyMywiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY
 4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjMyM30.Fn8ZlXgvGBr-uvDi6e7-72g8tP-u42T
 5FNW5NW4YQ7GkrMqUEthexGc9NOcf6uWYfSD4EiSbDVO8EIojZzIUgyXmG3tYDgSejFcDSPc
 MrF11m9WkOcapbIFTnFk2OyPVi48BVZ6vNb7j2184pJ3KHKoq9E7qlaKrEbvBn2HRVdtvb1y
 j1Xv1tH38I6Qong8xMAEMCcIfzTinEOFIbENYzgxBsSNVrS15CYtDRFEDPGmAVPzd4I7HN_
 ed-pzOET3YbUBBQUbrAuZSrSrBcgfBCtT9C5szd7tYXmi-1AMVdFybnVXArAXsDX0nZzm-PuCi_DGKMJET0sY2QNyesyKv8w", 

"expires_in": 899, 

"scope": "transactions", 

"refresh_token_expires_in": 31535999, 

"client_status": "active" 

}

Revoking Permissions

Merchants can manually revoke the permissions that they have granted your application. If a merchant revokes your application’s permissions in the Business Center, any current access token is immediately invalidated, and no new access tokens can be generated. If the merchant decides later to grant permissions to your application, they can do so by performing the access delegation steps again.

Contact

If you have any questions or you are interested in becoming a pilot partner, contact us.