Set Up REST SDK Integration
This tutorial guides you through how to set up the REST Client SDK in order to begin sending and receiving REST API messages to . The SDK is the fastest setup option. It handles common integration tasks, including authentication, and request formatting.
Sign Up for a Test Account
To begin setting up your account, you must first sign up for a sandbox test account. A test account enables you to obtain your REST API keys and test your implementation.
Follow these steps to sign up for a sandbox test account:
Go to the Developer Center test account sign-up page:
Enter your information into the test account form, and click Create Account.
Go to your email and find a message titled Merchant Registration Details and click Set up your username and password now.
Your browser opens the New User Sign Up wizard.
Enter the organization ID and contact email you submitted during account creation.
Follow the wizard pages and on-screen instructions to enter your name, username, and password.
Log in to the using your account credentials:
The Verify your Identity page appears. When you log in for the first time, you must verify your identity through a system-generated email sent to your registered email account.
Check your email inbox for a message titled Identification Code. A passcode is included in the message.
Enter the passcode on the Verify your Identity page.
You are directed to the dashboard page.
Create a REST API Key
Choose either a P12 certificate or a shared secret key pair, then follow the steps for that key type.
| Feature | P12 Certificate | Shared Secret Key Pair |
|---|---|---|
| Best for | Server-side integrations using certificate-based authentication | Most REST API integrations using HTTP Signature authentication |
| How it works | A .p12 certificate file and password authenticate each request | An API key ID and shared secret key sign each request |
| Key benefit | Strong certificate-based security | Easier to generate, store, and rotate |
Decide which REST API key is best for your organization and click its corresponding option below. REST API keys are cryptographic keys that determine how the SDK constructs REST API messages.
This task describes how to:
- Create or submit a P12 certificate.
- Test the P12 certificate to verify that it works.
Create or Submit a P12 Certificate
You can choose to create a new certificate or submit an existing P12 certificate that you created in your system.
Follow these steps to create a P12 certificate file or submit your own certificate signing request (CSR):
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Under REST APIs, choose REST – Certificate, and then click Generate key.
The Key Generation page appears.
If you are using a portfolio account, the Key options window appears, giving you the choice to create a meta key. For more information about how to create a meta key, see Meta Keys.
The Confirmation Key Generation window appears.
Click Download key after reviewing the key details.
The Key Generation page appears.
(Optional) You can set the Certificate Expiry Timeframe field to the number of months you want the key to remain active before it expires. Only whole numbers from 1–36 are accepted. By default, new keys expire after 12 months.
Choose from these two options:
If you are a creating a new P12 Certificate, click Download key .
If you are submitting your own certificate, enter your public PEM-formatted certificate in the text box, then click Download key .
Create a password for the certificate by entering one into the New Password and Confirm Password fields. Click Generate key.
To create or submit another key, click Generate another key. To view all of your created keys, go to the Key Management page.
Testing Your P12 Certificate
After creating your key certificate, you must verify that it can successfully process API requests. This task explains how to test and validate your P12 certificate in the Developer Center and the .
Follow these steps:
Go to the API Reference page:
Under Authentication and Sandbox Credentials, go to the Authentication Type drop-down menu and choose JSON Web Token.
Enter your organization ID in the Organization field.
Enter your Password in the Password field.
Click Browse and upload your p12 certificate from your desktop.
Click Update Credentials.
A confirmation message verifies that your credentials are successfully updated.
On the left navigation panel, choose Payments > POST Process a Payment.
Click Send.
A message confirms that your request is successful with the status code 201.
Log in to the :
On the left navigation panel, choose Transaction Management > Transactions.
Under Search Results, verify that the request ID from the test authorization response is listed in the Request ID column.
This task describes how to:
- Create a shared secret key pair.
- Test the shared secret key pair to verify that it works.
Create Shared Secret Key Pair
Follow these steps to create a shared secret key pair:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Under REST APIs, choose REST – Shared Secret, and then click Generate key.
The Key Generation page appears.
If you are using a portfolio account, the Key options window appears, giving you the choice to create a meta key. For more information about how to create a meta key, see Meta Keys.
The Confirmation Key Generation window appears.
Click Generate key after reviewing the key details.
The Key Generation page appears.
Click Download key .
The .pem file downloads to your desktop.
The Key value is your key ID and the Shared Secret value is your shared secret key pair.
To create or submit another key, click Generate another key. To view all of your created keys, go to the Key Management page.
Test Your Shared Secret Key Pair
After creating your key pair, you must verify that it can successfully process API requests. This task explains how to test and validate your shared secret key pair in the Developer Center and the .
Follow these steps:
Go to the API Reference page:
Under Authentication and Sandbox Credentials, go to the Authentication Type drop-down menu and choose HTTP Signature.
Enter your organization ID in the Organization ID field.
Enter your key ID in the Key field.
Enter your shared secret key in the Shared Secret Key field.
Click Update Credentials.
A confirmation message verifies that your credentials are successfully updated.
On the left navigation panel, choose Payments > POST Process a Payment.
Click Send.
A message confirms that your request is successful with the status code 201.
Log in to the :
On the left navigation panel, choose Transaction Management > Transactions.
Under Search Results, verify that the request ID from the test authorization response is listed in the Request ID column.
Create a REST–API Response MLE Key
Before you can enable your system to support MLE, you must create or upload a REST—API response MLE certificate. After creating or uploading the certificate, you can extract the certificate's key to begin enabling MLE. If your organization is using meta keys, the shared secret key pair and REST – API response MLE key must be created by the same portfolio or merchant account.
Overview of MLE
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. Enabling MLE requires you to create a P12 certificate or shared secret key pair for encrypting your requests and a REST – API Response MLE key for decrypting received responses. If your organization is using meta keys, your REST API keys must be created by the same portfolio or merchant account.
Follow these steps to create or submit an API Response MLE certificate in the :
Create or Submit a REST—API Response MLE Key
To enable MLE, you must first create a new REST—API response MLE certificate or upload an existing certificate. After creating or uploading the certificate, you can extract the certificate key to begin enabling MLE.
Follow these steps to create or submit an API Response MLE certificate in the :
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Under REST APIs, choose REST – API Response MLE, and then click Generate key.
Choose one of these options to download your key:
To create a new API response MLE certificate, click Download key .
To upload your own certificate, enter your public PEM-formatted certificate in the text box, and then click Download key . The .pem file downloads to your desktop. If prompted by your system, approve the location to which the file downloads.
If you are creating a certificate, the Set a Password window appears. Create a password for the certificate by entering the password into the New Password and Confirm Password fields, and then click Generate key
The .p12 file downloads to your desktop. If prompted by your system, approve the location to which the key downloads. To create or submit another key, click Generate another key. To view all of your created keys, go to the Key Management page.
Click Cancel.
The Key Management page appears.
Click the Key Type filter and choose REST-API Response MLE.
Click the Expires At filter and choose All Dates.
Click Search.
Find the REST–API Response key that you created in the Search Results table and save its key ID.
The key ID is needed to test and configure your system to use MLE.
Test Your REST–API Response MLE Key
Follow these steps to verify that your REST-API response MLE key is working.
Go to the REST API Reference page in the Developer Center:
On the left navigation panel, choose an API that supports MLE. For testing purposes, you can choose Intelligent Commerce > Intelligent Commerce Product > Enroll a Card.
MLE support is indicated by Request MLE and Response MLE at the top of the screen.
Choose the MLE Configuration tab.
In the Message Level Encryption Credentials section, enter your API response MLE key credentials:
Response encryption: Enter the key ID of your REST—API response MLE key.
You saved this key ID in Step 11 in the Create or Submit a REST—API Response MLE Key section.
Response decryption: Click Browse to submit your own private decryption key from your local system. Only .p12 files are supported.
Click Update Credentials.
From the Send drop-down menu, choose Send Request with Message Level Encryption.
Click Send.
Install the REST SDK
The REST Client SDK constructs JSON Web Token (JWT) messages for you to send to . These messages are also encrypted using message-level encryption (MLE) by the SDK. When you receive a response message from , the SDK decrypts it using MLE.
For more information about how to install the REST Client SDK into your system, see the REST API related products table in the GitHub.
SDK Version
This table lists the minimum SDK versions that support the updated JWT message construction and MLE requirements. Find your system's processing language and install the corresponding SDK version or a later version:
| Language | Minimum SDK Version Required | MLE Enablement Instructions |
|---|---|---|
| .NET Framework | v0.0.1.60 | cybersource-rest-client-dotnet/MLE.md |
| .NET Standard or .NET Core | v0.0.1.52 | cybersource-rest-client-dotnetstandard/MLE.md |
| Java | v0.0.85 | cybersource-rest-client-java/MLE.md |
| Node | v0.0.75 | cybersource-rest-client-node/MLE.md |
| PHP | v0.0.69 | cybersource-rest-client-php/MLE.md |
| Python | v0.0.73 | cybersource-rest-client-python/MLE.md |
| Ruby | v0.0.81 | cybersource-rest-client-ruby/MLE.md |
Table: Minimum Required SDK Versions
Test Your Setup
recommends that you test and verify that your system can securely send and receive REST API messages before transitioning to a production account. Use the test payment examples provided in this section to test your set up. You should also test any additional API requests that you will use in your live environment. For additional API examples, use the developer guide or the REST API Reference:
Complete a Test Transaction
After setting up your system to be REST compliant, you can send these test requests to verify that you can send and receive REST API messages.
Authorize a Payment
You send this POST request to the /pts/v2/payments endpoint:
{ "orderInformation": { "billTo": { "country": "US", "lastName": "Kim", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "Kyong-Jin", "email": "[email protected]" }, "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4111111111111111", "expirationMonth": "12", "type": "001" } }}Capture an Authorized Payment
You send this POST request to the /pts/v2/payments/{id}/captures endpoint and include the authorization transaction ID as the {id}:
/pts/v2/payments/6461731521426399003473/captures{ "clientReferenceInformation": { "code": "ABC123" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" }}Refund a Captured Payment
You send this POST request to the /pts/v2/payments/{id}/refunds endpoint and include the capture transaction ID as the {id}:
/pts/v2/payments/6772994431376681303954/refunds{ "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "USD" } }}Troubleshooting Errors
If you receive an error message during testing, use this table to determine the cause of the error. For additional error code descriptions, see the Transaction response codes page:
| Symptom | Cause | What to do |
|---|---|---|
Could not load PKCS12 file | Wrong password, corrupted file, or wrong file format | Try opening the file with openssl pkcs12 -in file.p12 -info to verify it's well-formed. Confirm password is correct. |
BAD_CERTIFICATE in response | Certificate expired or revoked | Test certs expire in 90 days; regenerate. Check the Key Management page for the certificate's status. |
| Transaction approved in test, denied in production | Test merchant ID was used in a production-credential request | Verify runEnvironment and credentials match — test certs cannot authenticate to the production host. |
Going Live
When you are ready to begin sending live API requests, you must request a production account. A production account sends API requests to the production endpoint, which routes your message to the applicable services, processors, or networks.
Sign Up for a Production Account
Follow these steps to create your production account:
Log in to your test account:
In the , go to Support Cases > MID Configuration Request.
The MID Configuration Request appears.
Click MID Activation.
In the Description field, enter the merchant ID that you want to take live.
Choose a processor configuration, and enter the name of your processor.
If you are unsure of the processor name, contact your merchant service provider or your merchant acquiring bank.
Choose the production environment to apply these change.
Click Service Enablement and list the products and services that you intend to use.
Click Submit.
Establish a Contract
Contact Sales to establish a contract with that enables you to process real transactions and receive support.
Contact Sales to establish a contract with that enables you to process real transactions and receive support.
Contact Sales to establish a contract with that enables you to process real transactions and receive support.
Activate Production Account
Submit a merchant ID (MID) activation request.
It can take up to three business days for the MID to become active.
Create Your Production Credentials
After your production account is created, log in and generate new production credentials. The credentials you created using your test account, such as your API keys, do not automatically transition to the production environment. You must also update your system configuration to now use your new credentials.
Credential Checklist
- REST API key (P12 certificate or shared secret key pair)
- REST—API Response MLE Key
Next Steps
Your integration is now ready. Choose which solutions to build with next:
Additional Solutions
Billing and Subscriptions
Bill customers on a schedule by sending invoices or creating recurring subscriptions with reusable plans.
View billing guidesPost-Transaction Processing
Track what you process by searching transactions, downloading reports, and keeping stored card data current.
View post-transaction guidesThanks for your feedback!
Last published: September 29, 2026