Set Up Custom Integration

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):

2. On the left navigation panel, choose Payment Configuration > Key Management.

   

3. Click + Generate key on the Key Management page.

   

4. 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.

   

5. Click Download key after reviewing the key details.

   The Key Generation page appears.

6. (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.

7. 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 .

   

8. 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.

Extracting the Private Key from Your P12 Certificate

When you have your P12 certificate, extract the private key from the certificate. Use this key to sign your header when sending an API request.

Follow these steps to extract the private key using OpenSSL:

1. Open the command-line tool and navigate to the directory that contains the P12 certificate.
2. Enter this command:

openssl pkcs12 -in [certificate name] -nodes -nocerts -out [private key name]

3. Enter the password for the certificate.

   You set this password when you created the P12 certificate in the .

Testing Your Private Key

After creating your key certificate, you must verify that it can successfully process API requests. This task explains how to test and validate your private key in the Developer Center and the .

Follow these steps:

2. Under Authentication and Sandbox Credentials, go to the Authentication Type drop-down menu and choose JSON Web Token.

3. Enter your organization ID in the Organization field.

4. Enter your Password in the Password field.

5. Click Browse and upload your p12 certificate from your desktop.

6. Click Update Credentials.

   A confirmation message verifies that your credentials are successfully updated.

   

7. On the left navigation panel, choose Payments > POST Process a Payment.

8. Click Send.

   

   A message confirms that your request is successful with the status code 201.

9. Log in to the :

10. On the left navigation panel, choose Transaction Management > Transactions.

11. Under Search Results, verify that the request ID from the test authorization response is listed in the Request ID column.

    

Set the Known HTTP Header Elements

The HTTP message header consists of the content-type, host, and authorization HTTP header elements.

• content-type
• host
• authorization

To be begin constructing the JWT, set the known header values:

Set the JWS Header Claims

This step begins the process of constructing a JSON Web Signature (JWS) token. To construct a JWS token, you must first create the JWS header by setting its header claim values. After creating the JWS header, use Base64URL to encode it. The encoded header claim value is the first segment of the JWS token.

These header claim values do not require calculation.

Set the JWS Body Claims

After you set the JWS header values, you must create the JWS body by setting these body claim values. After the body claims are created, use Base64URL to encode it. The encoded body claim value is the second segment of the JWS token.

The value of the digest JWS claim is a hashed version of the HTTP message body that you must calculate. uses this hash value to validate the integrity of your message body.

Follow these steps to calculate the digest hash:

1. Generate the SHA-256 hash of the JSON payload (message body).
2. Encode the hashed string to Base64.
3. Add the message body hash to the digest JWS body claims.
4. Add the algorithm used to hash the digest in the digestAlgorithm JWS body claims.

echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64

public static string GenerateDigest(){    var digest = "";    var bodyText = "{ your JSON payload }";    using (var sha256hash = SHA256.Create())    {        byte[] payloadBytes = sha256hash.ComputeHash(Encoding.UTF8.GetBytes(bodyText));        digest = Convert.ToBase64String(payloadBytes);    }    return digest;}

public static String GenerateDigest() throws NoSuchAlgorithmException {    String bodyText = "{ your JSON payload }";    MessageDigest md = MessageDigest.getInstance("SHA-256");    md.update(bodyText.getBytes(StandardCharsets.UTF_8));    byte[] digest = md.digest();    return Base64.getEncoder().encodeToString(digest);}

cat <<'EOF' | tr -d '\n' | shasum -a 256{  "clientReferenceInformation": {    "code": "TC50171_3"  },  "paymentInformation": {    "card": {      "number": "4111111111111111",      "expirationMonth": "12",      "expirationYear": "2031"    }  },  "orderInformation": {    "amountDetails": {      "totalAmount": "102.21",      "currency": "USD"    },    "billTo": {      "firstName": "John",      "lastName": "Doe",      "address1": "1MarketSt",      "locality": "sanfrancisco",      "administrativeArea": "CA",      "postalCode": "94105",      "country": "US",      "email": "",      "phoneNumber": "4158880000"    }  }}EOF

Calculate the JWS Signature

You can now calculate the JSON Web Signature (JWS). The JWS consists of the JWS header and claim set hashes in the following format. They are encrypted with the private key.

[JWS Header].[Claim Set]

Follow these steps to calculate the signature:

1. Concatenate the JWS header and claim set hash strings with a period character (.) between the hashes:

   [JWS Header].[Claim Set]

2. Generate an encoded version of the text file using your private key from the .p12 certificate. For more information, see Create or Submit a P12 Certificate.

3. Base64-encode the signature output.

4. After calculating the signature, you can construct a complete JWS token by combining the JWS header claims, body claims, and signature.

Example: Token Signature Hash

YjgwNGIxOTMxMzQ2NzhlYjdiMDdhMWZmYjZiYzUzNzliMTk5NzFmNjAzNWRmMThlNzk0N2NhY2U0YTEwNzYyYQ

Encoding the Signature File Using OpenSSL

Encode the signature file using the openssl tool:

openssl rsautl -encrypt -inkey publickey.key -pubin -in [signature-text-file] > [signature-encoded-file]

Base64 Encoding the Signature File Using the Command Line

Encode the signature file using the openssl tool and remove any padding:

base64 -i [signature-encoded-file]

Complete the Message with JWTs

Combine the completed JWS token from Steps 3B–3D with the other HTTP headers from Step 3A and your HTTP message body to construct your authenticated REST request message:

Host: Content-Type: application/jsonAuthorization: Bearer <Base64URL-encoded JWS header>.<Base64URL-encoded JWS body claims>.<Base64URL-encoded signature>{  "clientReferenceInformation": {    "code": "refnum-123456"  },  "paymentInformation": {    "card": {      "number": "411111111111XXXX",      "expirationMonth": "12",      "expirationYear": "2031"    }  }}

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 :

2. On the left navigation panel, choose Payment Configuration > Key Management.

   

3. Click + Generate key on the Key Management page.

   

4. Under REST APIs, choose REST – API Response MLE, and then click Generate key.

   

5. 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.

   

6. 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.

   

7. Click Cancel.

   The Key Management page appears.

8. Click the Key Type filter and choose REST-API Response MLE.

9. Click the Expires At filter and choose All Dates.

10. Click Search.

11. 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.

    

Extract the SJC Certificate

The REST–API Response MLE Key contains an SJC certificate that you must extract in order to enable MLE.

Follow these steps to extract the SJC certificate from your REST–API Response MLE Key:

1. Open and use a terminal window to navigate to the REST–API Response MLE Key .p12 file in your system.
2. Run this command to open the .p12 file:

  openssl pkcs12 -in {certificate_file_name}.p12

You are prompted to enter the import password.

3. Enter the password you set when you created the REST–API Response MLE Key.
4. Locate the CyberSource_SJC_US certificate in the opened file. This is the SJC certificate.
5. Store the SJC certificate in your system to use when you enable MLE.

Set Up MLE

Use the information in this task to configure your system with a custom MLE using JWTs.

Overview of MLE Setup Tasks

Overview Tasks

1. Import the required programming libraries for your system.

2. Import these three certificates:

   • Signing certificate (P12 Certificate or REST – Certificate)
   • MLE request certificate (SJC public certificate)
   • MLE response certificate (REST – API Response MLE)

3. Encrypt the JSON request message using a JSON Web Encryption (JWE) that uses the SJC public certificate.

4. Create the HTTP body in this format: {"encryptedRequest": "JWE-with-SJC"}.

5. Create the JSON Web Signature (JWS) payload with these JWT payload fields and your signing certificate's private key:

   Expand all

   JWS Header Claim Fields

   Header Field	Description
   alg	The asymmetric algorithm you use to sign the token header. These algorithms are supported: RS256 (default), RS384, RS512, PS256, PS384, and PS512.
   kid	The key ID you use to digitally sign the JWT. It must be registered with the authorizing server. It is the key ID from your P12 certificate. For more information, see Create or Submit a P12 Certificate.
   typ	The token type. Set to JWT.

   Expand all

   JWS Header Claim Fields

   JWS Body Claim Field	Description	Data Type	Field Value Format
   digest	A Base64-encoded hash of the message payload. Do not include the digest field if the request message is empty, such as during a GET or DELETE request.	String	Base64-encoded string: uppercase, lowercase, digits, +, /, and optional = padding
   digestAlgorithm	The algorithm used to hash the message payload. The message payload should be hashed using the SHA-256 algorithm. Do not include the digestAlgorithm field if the digest field is not included.	String	Lowercase
   exp	The time at which the JWS token expires. Important: field values cannot exceed two minutes after the message issue date, which is the iat field value. This field is an HTTP-date value as defined in RFC 7231. For example, 01/01/2020 at 00:02:00 is 1577836920.	String	Numeric
   iat	The date and time at which the message is issued. This field uses a NumericDate value as defined in RFC 7519, which is the number of seconds since 1970-01-01T00:00:00Z (Unix epoch). For example, 01/01/2020 at 00:00:00 is 1577836800.	String	Numeric
   iss	The issuer identifier for the JWS token. Set to the merchant ID that created the P12 certificate. This value is used to validate the issuer.	String	Lowercase
   jti	The unique token ID. This value is used for replay prevention. Format the value using UUID version 4. For example, 6643fb9a-8093-47c6-95d3-8d69785b5e62.	String	Lowercase alphanumeric
   request-host	The endpoint hostname for the HTTP request, excluding the protocol and path. For example, to send a message to the /pts/v2/payments endpoint, set this field to .	String	Lowercase alphanumeric with periods
   request-method	The HTTP request method. For example, post, get, put, patch, or delete.	String	Lowercase
   request-resource-path	The endpoint path for the HTTP request, excluding the domain. For example, to send a message to the /pts/v2/payments endpoint, set this field to /pts/v2/payments.	String	Lowercase alphanumeric
   v-c-jwt-version	The Visa JWT scheme version number. Set to 2.	String	Numeric
   v-c-merchant-id	Your transacting merchant ID (MID). If you are a portfolio or merchant account user, set this to the transacting merchant ID you send requests on behalf of.	String	Lowercase alphanumeric
   v-c-response-mle-kid	The message-level encryption response key ID, also known as the REST-API Response MLE key.	String	Lowercase alphanumeric

6. Sign the JWS with your P12 certificate and send it as Authorization: Bearer.

7. Receive an encrypted response and decrypt it with the MLE private key. You will receive the response in this format: {"encryptedResponse": "JWE-with-ResponseMLECertificate"}

The JWE contains a JOSE header containing these four default 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 the v-c-response-mle-kid from the authentication JWS in step 5.

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"        }    }}

Sign Up for a Production Account

Follow these steps to create your production account:

1. Log in to your test account:

2. In the , go to Support Cases > MID Configuration Request.

   The MID Configuration Request appears.

3. Click MID Activation.

4. In the Description field, enter the merchant ID that you want to take live.

5. 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.

6. Choose the production environment to apply these change.

7. Click Service Enablement and list the products and services that you intend to use.

8. Click Submit.

Establish a Contract

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

Create Shared Secret Key

Follow these steps to create a shared secret key pair:

2. On the left navigation panel, choose Payment Configuration > Key Management.

   

3. Click + Generate key on the Key Management page.

   

4. 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.

   

5. Click Generate key after reviewing the key details.

   The Key Generation page appears.

6. 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.

   

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 certificate, 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:

2. Under Authentication and Sandbox Credentials, go to the Authentication Type drop-down menu and choose HTTP Signature.

3. Enter your organization ID in the Organization ID field.

4. Enter your key ID in the Key field.

5. Enter your shared secret key in the Shared Secret Key field.

6. Click Update Credentials.

   A confirmation message verifies that your credentials are successfully updated.

   

7. On the left navigation panel, choose Payments > POST Process a Payment.

8. Click Send.

   

   A message confirms that your request is successful with the status code 201.

9. Log in to the :

10. On the left navigation panel, choose Transaction Management > Transactions.

11. Under Search Results, verify that the request ID from the test authorization response is listed in the Request ID column.