Set Up a JSON Web Token Message
Setting up your JSON web token message requires you to complete these tasks:
- Sign up and register aCybersourceBusiness Centersandbox account. See Sign Up for a Sandbox Account.
- Create a P12 certificate. See Create a P12 Certificate.
- Construct a message using a JSON web token. See Construct Messages Using JSON Web Tokens.
- (Optional) Enable the optional message-level encryption (MLE) feature. See Enable Message-Level Encryption.
- Go live. See Going Live.
Sign Up for a Sandbox Account
The first step to set up your account is to sign up for a sandbox account. From this account
you can obtain your security keys and test your implementation.
Follow these steps to sign up for a sandbox account:
- Go to theCybersourceDeveloper Center sandbox account sign up page:
- Enter your information into the sandbox account form and clickCreate Account.
- Go to your email and find a message titled:Merchant Registration Details. Click theSet up your username and password nowlink.Your browser opens the New User Sign Up wizard.
- Enter the Organization ID and Contact email you supplied previously. Follow the wizard pages to add your name, a username, and a password.
- Log in to theBusiness Center.When you log in for the first time, you will be asked to verify your identity through a system-generated email to your email account.
- Check your email for a message titled:. A passcode is included in the message.CybersourceIdentification Code
- Enter the passcode on theVerify your Identitypage.You should be directed to theBusiness Centerhome page.You have successfully signed up for a sandbox account.
Create a P12 Certificate
A P12 certificate and its private key are used with JSON Web Token message security. To create
a P12 certificate, you must download a .p12 file from the
Business Center
and
extract its private key.Construct Messages Using JSON Web Tokens
Follow these steps to construct messages using JWTs:
- Generate a hash of the message body. See Generate a Hash of the Message Body.
- Populate the header values. See Generate the Token Header.
- Generate a hash of the claim set. See Generate a Hash of the Claim Set.
- Generate a hash of the token header. See Generate a Hash of the Token Header.
- Generate a token signature hash. See Generate a Token Signature.
- Populate thesignatureheader field. See Update Header Fields.
Enable Message-Level Encryption
IMPORTANT
This feature is in the pilot phase. To use message-level encryption, contact your sales
representative.
There are additional tasks you must complete before you can enable message-level encryption. For
more information, see Prerequisites for Message-Level Encryption.
Message-Level Encryption (MLE) enables you to store information or communicate with other
parties while helping to prevent uninvolved parties from understanding the stored
information. MLE is optional and supported only for payments services.
MLE provides enhanced security for message payload by using an asymmetric encryption
technique (public-key cryptography). The message encryption is implemented with
symmetric encryption using Advanced Encryption Standard (AES), Galois Counter Mode (GCM)
with 256-bit key size. The encryption of keys is supported using RSA Optimal Asymmetric
Encryption Padding (OAEP) with 2048-bit key size. The encryption service is based on
JSON Web Encryption (JWE), works on top of SSL and requires separate key-pairs for
request and response legs of the transaction.
MLE is required for APIs that primarily deal with sensitive transaction data, both
financial and non-financial. These are the types of sensitive transaction data:
- Personal identification information (PII)
- Personal account number (PAN)
- Personal account information (PAI)
MLE is supported when using JSON web tokens. For more information, see Message-Level Encryption Using JSON Web Tokens.
Each of these authentication schemes uses an encrypted payload, called the
JWE
. A
JWE token has these five components, with each component separated by a period (.): - JOSE header containing four elements:"alg": "RSA-OAEP-256", //The algorithm used to encrypt the CEK "enc": "A256GCM", //The algorithm used to encrypt the message "iat": "1702493653" //The current timestamp in milliseconds "kid": "keyId" //The serial number of shared public cert for encryption of CEK
- JWE encrypted key
- JWE initialization vector
- JWE additional authentication data (AAD)
- JWE ciphertext and authentication tag
Going Live
When you are ready to process payments in a live environment, you must transition your account
to a live status with a valid configuration for your chosen payment processor. When
live, your transaction data flows through the production
Cybersource
gateway, to your processor, and on to the appropriate payment network.To transition your account:
- Sign up for a merchant account.
- to establish a contract withCybersourcethat enables you to process real transactions and receive support.
- Submit a merchant ID (MID) activation request.
It may take up to three business days to complete a MID activation request.