Salesforce Commerce Cloud

Salesforce Commerce Cloud (SFCC) is an enterprise-grade, cloud-based digital commerce platform that enables brands to deliver personalized and scalable shopping experiences. For more information, visit the official Salesforce Commerce Cloud website.

Benefits

Integrating the PayU cartridge offers the following advantages:

• Quick integration: Preconfigured components that accelerate development.
• Minimal technical effort: No complex coding required.
• Ongoing maintenance: PayU manages updates and improvements.
• PCI-DSS compliance: Ensures security and regulatory adherence.
• Comprehensive functionality: Supports card payments, cash, 3DS, refunds, and more.
• Built on SFRA: Fully aligned with Salesforce’s recommended architecture.
• Customizable setup: Select the payment methods and business rules that best suit your needs.
• Integrated insights: Direct access to transactional data within Salesforce.

Prerequisites

Before beginning the integration, ensure you have the following:

• An active PayU Latam account.
• An active PayU Enterprise (PaymentsOS) account in production/live mode. For details on how to enable live mode, refer to Activating Your PayU Enterprise Account.
• A Salesforce Commerce Cloud (Business Manager) instance with administrator access.
• Access to your SFCC store’s development environment, including permissions to install and configure cartridges.
• Access to the PayU cartridge repository.

SFCC Compatibility

To ensure compatibility, note the following technical requirements and considerations:

• The cartridge is compatible with SFRA version 7.0.1 or later.
• You must install Node.js version 8.9.4 or later in your development environment.

Supported PayU Latam Features

The following table shows the availability of the PayU cartridge by country, along with the supported payment methods:

Country	Payment Method Type	Payment Method Name in SFCC
Argentina	Card	American Express, Argencard, Cabal, Cencosud, DINERS, Master Card, Naranja, Visa
	Cash	COBRO_EXPRESS, PAGOFACIL, RAPIPAGO
Brazil	Card	American Express, Master Card, Visa
	Cash	BOLETO BANCARIO
Chile	Card	American Express, Master Card, Visa
Colombia	Card	American Express, DINERS, Master Card, Visa
	Cash	BANK REFERENCED, EFECTY, OTHERS CASH
Mexico	Card	American Express, Master Card, Visa
	Cash	BANK REFERENCED, OXXO, OTHERS CASH MX, SEVEN ELEVEN
	Bank Transfer	SPEI
Panama	Card	Master Card, Visa
Peru	Card	American Express, Master Card, Visa
	Cash	PAGOEFECTIVO
	Digital Wallet	Yape

Considerations

Review the following key considerations to ensure a smooth and compliant integration across supported countries.

• All countries support one-step or two-step payment processing: authorization and capture in a single request, or authorization and capture as separate steps. In Colombia, the two-step flow is only supported for MasterCard and Visa.
• The following financial operations are supported: Charge, Authorization, Capture, Void, and Refund.
• All countries support fraud analysis and PayU’s manual validation processes.
• Argentina, Brazil, Colombia, Mexico, and Peru support 3D Secure for MasterCard and Visa.
• Installment-based promotions—also known as interest-free months—are supported through routing conditions defined in the PayU Enterprise decision engine.

Initial Setup, Installation, and Configuration

This section outlines the necessary steps to properly install and configure the PayU cartridge on your SFCC site.

Activating Your PayU Enterprise Account

To get started, register on the PayU Enterprise (PaymentsOS) official website. Please provide your name, your company’s name and website, and the email address of the administrator user. Once you’ve completed the registration, you’ll receive an email to set your password. After that, you’ll be able to access the PayU Enterprise Control Center.

By default, new accounts are set to test mode. To enable live transactions, contact your account manager and submit a request with the following details:

• PayU Latam Merchant ID: Locate your LATAM account’s Merchant ID in the PayU Management Panel.
• PayU Enterprise Account ID: Find your Account ID in the PayU Enterprise control panel by clicking your username in the upper-right corner.

Setting Up Your PayU Enterprise Account

PayU Enterprise (PaymentsOS) connects your PayU Latam account with your Salesforce Commerce Cloud (SFCC) store.

To get started, you need to configure the following in your PayU Enterprise account:

• The PayU Latam payment provider
• Your business unit
• The webhook to receive notifications on your SFCC site

Configuring a Payment Provider

A payment provider instance in PayU Enterprise stores your PayU Latam payment processing credentials.

Follow these steps to configure a provider:

1. In the PayU Enterprise Control Panel, select the TEST or LIVE environment at the top. Then navigate to Configurations > Providers, search for, and select the PayULatam provider.

2. Fill in the following details to create the payment provider instance:

The fields apiLogin, apiKey, accountId, and merchantId are different for each environment selected at the top of the control panel.

• For the TEST environment, use the credentials provided in Testing Your Solution. If you’re using 3DSecure, refer to the credentials in Testing 3DS Authentication.
• For the LIVE environment, you must obtain your credentials from the PayU Latam Control Panel. For more information, refer to How to Get the Integration Variables.

3. Once you’ve completed the form, click Create to finish.

Configuring a Business Unit

A business unit links the provider configuration created in the previous section with your PayU Enterprise API credentials, enabling transaction processing on your Salesforce Commerce Cloud (SFCC) site.

Follow these steps to configure the business unit:

1. In the PayU Enterprise Control Panel, select the TEST or LIVE environment at the top. Then go to Settings > Business Units and click on Create Business Unit.

2. Fill out the following information:

In the option to select a default provider for the business unit, choose the provider configuration you created in the previous section. Then click Create.

3. Once the business unit is created, the system will generate an Application ID, a Public API Key, and a Private API Key. These credentials are required to enable payment processing on your SFCC website. Be sure to save them, as you’ll need them in the Managing Custom Site Preferences step.

Configuring a Webhook

The webhook enables your site to receive automatic notifications from PayU whenever a transaction status changes. This is useful for updating pending payments in real-time, such as:

• Cash payments that are confirmed after being completed.
• Fraud verification checks before authorizing the payment.
• 3D Secure authentications that require a challenge from the bank.
• Refunds that remain pending and are later approved or rejected.
• Any other relevant updates.

To enable the webhook, follow these steps:

1. In the PayU Enterprise Control Panel, select either the TEST or LIVE environment at the top. Then go to Settings > Webhooks and click Create a Webhook Endpoint.

2. In the Webhook URL field, enter a URL under the following format: <YourSiteURL>/PayU-Webhook.

3. In the event table, enable the Create and Update events for the following financial operations: Authorization, Capture, Charge, Refund, and Void.

4. Under Associated Business Units, select the business unit you created in the previous section.

5. Finally, click Create to save your webhook.

Installing the PayU Cartridge on Your Site

To enable payment processing with PayU on your Salesforce Commerce Cloud (SFCC) site, you need to install and configure the PayU cartridge. This section guides you through the steps required to integrate the cartridge into the storefront codebase.

1. Clone the PayU-Cartridges repository and integrate it into your project codebase.

2. Inside the PayU-Cartridges folder, locate the package.json file and ensure the paths property correctly points to app_storefront_base:

"paths": {
  "base": "../storefront-reference-architecture/cartridges/app_storefront_base"
}

    To do this, you’ll need to download the official Salesforce Commerce Cloud repository from GitHub. This requires:

• Two-Factor Authentication (2FA) enabled on your GitHub account.
• Logging in with your SFCC credentials.
• Following the access instructions provided in the SFRA Guide and SFCC Repository Access documentation.

3. Ensure you have Node.js version 8.9.4 or higher installed on your machine.

4. Open a terminal and navigate to the root of the repository. Run the following commands:

• npm install

• npm run compile:js

• npm run compile:scss

5. In the same directory where you downloaded the source code, create a file named dw.json with the following structure:

{
  "hostname": "your_sandbox_hostname", // Your sandbox server address.
  "username": "your_username", // Your SFCC login username. 
  "password": "your_password", // Your SFCC login password. 
  "code-version": "version_to_upload" // Label you want to upload. e.g.: ”payu_latam”
}

Activating the Cartridge in Business Manager

You must add the PayU cartridge to the cartridges path of your site in Business Manager before proceeding with further configuration.

To activate the cartridge, follow these steps:

1. Log in to Business Manager.

2. Navigate to Administration > Sites > Manage Sites.

3. Click the name of your site.

4. Open the Settings tab.

5. In the Cartridges field, add the PayU cartridge name at the beginning of the path: int_payu:app_storefront_base

6. Click Apply.

Configuring the Cartridge

This section outlines the setup process for the PayU cartridge.

Importing Metadata with a Single Site Import

All required metadata for the PayU integration is located in the metadata at the root of the cartridge package downloaded from GitHub. This folder includes essential configuration elements such as:

• Custom Preferences
• Job Definitions
• Service Configurations
• Country-Specific Settings

Follow the steps below to import the metadata:

1. Open the metadata folder from the repository.

2. Open the jobs.xml file.

3. Update the site-id value in each job with your site’s ID. You can find your site ID in Business Manager > Administration > Sites > Manage Sites.

    Make sure to update the ID in all jobs. Here’s an example for reference:

<job job-id="PAYU_CAPTURE_PAYMENT">
  <description />
  <parameters />
  <flow>
    <context site-id="payu-argentina" />

4. Inside the metadata/sites folder, rename the subdirectory payu-country to match your site’s ID.

5. Compress the metadata folder into a .zip file.

6. Log in to Business Manager and go to Administration > Site Development > Site Import & Export.

7. Choose the .zip file you just created, click Upload, and upload the file.

8. Once uploaded, select the file and click Import.

    After a successful import, all PayU configurations will be available according to your account.

9. To verify, go to Site > Ordering > Order, open any order, switch to the Attributes tab, and confirm that the data has been imported correctly.

Managing Custom Site Preferences

To manage the custom site preferences for PayU:

1. Log in to Business Manager and navigate to Site > Merchant Tools > Site Preferences > Custom Preferences.

2. Click on the preference group with the ID payu.

    You will need the PayU Enterprise credentials generated in the Configuring a Business Unit section.

3. Edit the attributes according to your PayU account configuration.

Verifying Your Payment Processors

Once you’ve uploaded the metadata file, the payment processor details are updated automatically. Next, verify that the processors are correctly configured:

1. In Business Manager, select the site you want to configure.
2. Go to Merchant Tools > Ordering > Payment Processors.
3. Confirm that the PayU processors appear in the list.

Enabling the Payment Methods

The integration package includes a definition of payment methods in the payment-methods.xml file, located in the metadata folder you previously imported. To enable them:

1. Go to Merchant Tools > Ordering > Payment Methods.
2. Enable the payment methods you want to offer.

    In the Manage Credit/Debit Cards window you can enable the card franchise you wish to accept.

    All card-related fields on this screen are used to configure specific validations.

    You can also configure minimum and maximum payment amounts by payment method.

    Please refer to the following limits for cash payments:

Country	Alternative Payment Method	Minimum Amount	Maximum Amount
Argentina	COBRO_EXPRESS	$5 ARS	$60,000 ARS
	PAGOFACIL	$5 ARS	$200,000 ARS
	RAPIPAGO	$5 ARS	$500,000 ARS
Brazil	BOLETO BANCARIO	$1.00 BRL	$10,000.00 BRL
Colombia	BANK REFERENCED	$1.00 COP	–
	EFECTY	$20,000.00 COP	$6,000,000.00 COP
	OTHERS CASH	$1,000.00 COP	$4,000,000.00 COP
Mexico	BANK REFERENCED	$1.00 MXN	–
	OXXO	$1.00 MXN	$10,000.00 MXN
	OTHERS CASH MX	$1.00 MXN	$10,000.00 MXN
	SEVEN ELEVEN	$1.00 MXN	$10,000.00 MXN

Granting Webhook Access to Orders

Before proceeding with this configuration, make sure you’ve completed the PayU Enterprise Configuring a Webhook section.

Ensure that the webhook controller has access to the order object. To do this:

1. Go to Merchant Tools > Site Preferences > Order.
2. Set the Limit Storefront Order Access field to Allow List.
3. In the text field, enter: PayU-Webhook.

Important Considerations

Before going live, review the following points to ensure proper configuration and avoid issues with webhook communication and order processing.

• If this configuration is not applied correctly, webhook requests from PayU will reach the controller but will not have permission to update the orders. This can result in critical errors when updating order statuses and processing payments.
• After completing the setup, make a test payment to confirm that webhook notifications are being received properly. This step is essential to ensure that the integration is working as expected.
• If your setup includes multiple storefronts across different countries, be sure to validate this configuration for each site individually, using the corresponding URL for each.

Verifying the Service Configuration

To verify that the PayU HTTP service (https.payment.payu) is properly configured in Business Manager, navigate to Administration > Operations > Services.

Configuring the Jobs

PayU provides several jobs to automate key tasks related to payment processing. The jobs.xml file included in the cartridge defines the available jobs.

Below is a summary of the available jobs.

Assigning Jobs to a Single Site

Make sure to assign the jobs to each of your sites. To do this:

1. In Business Manager, go to Administration > Operations > Jobs.
2. Verify that all jobs are properly configured and listed.

    From this screen, you can:

• Check if the jobs are enabled.
• View the last execution, its status, priority, and scope.
• Delete jobs if necessary.

To enable or disable a job, change its schedule, or modify other settings, click on the specific job.
Example:

Ensure each job is linked to the appropriate site. For instance, if the site is payu-argentina, the job will run for Argentina and process authorizations for that country only.

Assigning Jobs to Multiple Sites

If you manage multiple storefronts across different countries, set up a separate job for each site with a unique job ID. This ensures capture, refund, and void operations are handled correctly per site.

To enable any PayU job for a specific site (e.g., PAYU_CAPTURE_PAYMENT for Brazil):

1. Go to Administration > Operations > Jobs and click New Job.

2. Enter a unique job ID using the format: [JOB_NAME]_[SITE_ID_COUNTRY].

• Example Job IDs:
  • PAYU_CAPTURE_PAYMENT_BRAZIL
  • PAYU_PARTIAL_REFUND_ARGENTINA
  • PAYU_REFUND_MEXICO
  • PAYU_VOID_COLOMBIA

3. Provide a clear, relevant description for the job and then click Create.

4. Open the Job Steps section and click Configure a Step.

5. Search for and select the corresponding custom step ID:

• For PAYU_CAPTURE_PAYMENT: custom.payuPaymentCapture
• For PAYU_PARTIAL_REFUND: custom.payuPartialRefund
• For PAYU_REFUND: custom.payuRefund
• For PAYU_VOID: custom.payuPaymentVoid

6. Assign the selected step ID and click Assign.

7. Set the site scope to the corresponding country/site to ensure the job runs only on that specific storefront.

Running Payment Jobs

This section explains how to execute each job correctly, including the required parameters and configuration tips to ensure proper functionality.

PAYU_CAPTURE_PAYMENT Job

This job captures previously authorized payments when the site uses a two-step payment flow (Authorization and Capture as separate steps).

To use this job, ensure that your preferences for payUPaymentFlowType and enableImmediateCapture are configured as follows:

This job scans all orders with a payment status of “Authorized” and attempts to capture them. The results of each execution are recorded in the job logs.

Execution Steps

1. Go to Administration > Operations > Jobs.
2. Select PAYU_CAPTURE_PAYMENT from the job list.
3. Complete the parameter fields according to your requirements.
   • Note that the ID parameter is mandatory for this job: custom.payUPaymentCapture
4. Define the execution frequency (e.g., every hour).
5. Enable or disable the job as needed.

PAYU_PARTIAL_REFUND Job

This job allows you to manually issue partial refunds by specifying the amount to be returned.

Important Considerations

• The payment status must be “Captured”.
• The refunded amount must not exceed the total amount captured for the order.

Execution Steps

1. Go to Administration > Operations > Jobs.

2. Select PAYU_PARTIAL_REFUND from the job list.

3. Click on Job Steps and select custom.payUPartialRefund.

4. Fill in the following parameter fields:

   • ID: custom.payUPartialRefund
   • orderId: ID of the order to be refunded.
   • amount: Amount to be refunded.
     
   • (Optional) refundReason: Explanation for the refund (useful for audit purposes).

Then, click Assign.

5. Click Run Now to execute the job. You can use the Refresh button to update the job history.

PAYU_REFUND Job

This job refunds the full payment amount for a specific order.

Important Considerations

• This job is only applicable if the payment status is “Captured”.
• The refund will be for 100% of the paid amount.

Execution Steps

1. Go to Administration > Operations > Jobs.

2. Select PAYU_REFUND from the job list.

3. Click on Job Steps and select custom.payURefund.

4. Fill in the following parameter fields:

   • ID: custom.payURefund
   • orderId: ID of the order to be refunded.
   • (Optional) refundReason: Explanation for the refund (useful for audit purposes).

Then, click Assign.

5. Click Run Now to execute the job. You can use the Refresh button to update the job history.

PAYU_VOID (ORDER_SPECIFIC) Job

This job is used to void an authorized payment before it has been captured.

Important Considerations

• This job can only be executed if the payment status is “Authorized”.
• Payments that have already been captured cannot be voided.
• The site must be configured to use the two-step payment flow (Authorization and Capture separately).
• To use this job, the payUPaymentFlowType, enableImmediateCapture, and payUVoidAllowed fields must be set as follows:

Execution Steps

1. Go to Administration > Operations > Jobs.

2. Select PAYU_VOID (ORDER_SPECIFIC).

3. Click on Job Steps and select custom.payUPaymentVoid.

4. Fill in the following parameter fields:

   • ID: custom.payUPaymentVoid
   • orderId: ID of the order with the authorized payment.

Then, click Assign.

5. Click Run Now to execute the job. You can use the Refresh button to update the job history.

Enabling or Disabling the PayU Integration

You can temporarily disable or re-enable the PayU payment integration depending on your business needs. The steps below guide you through updating the payment method configurations in Business Manager to either deactivate or reactivate PayU as a payment processor.

Disabling PayU Integration:

1. Go to Merchant Tools > Ordering > Payment Methods.
2. Disable all payment methods associated with PayU.
3. Check each payment method to see which payment processor it uses:
   • Click on a payment method (e.g., CREDIT_CARD) and review the assigned processor.
   • If the processor is set to PAY_U, replace it with another one, such as BASIC_CREDIT.
4. Enable the payment methods you want to use with the new processor.

Re-Enabling PayU:

Switch the processors back to PAY_U for the corresponding payment methods.

Testing the Integration

Once you have completed the initial setup, installation, and configuration steps, we strongly recommend testing your integration before processing real transactions.

Prerequisites

• Ensure that the payUEnvironment preference is set to Test mode.
• Configure the preferences according to the payment flow and payment methods you want to test.
• Use the appropriate payUPublicKey, payUPrivateKey, and payUAppId credentials for the testing environment. These can be found under Configuring a Business Unit.
• After completing your tests, update the preferences with your production credentials.

Running a Test Transaction

1. Log in to Business Manager in Salesforce Commerce Cloud and select your site from the dropdown menu.

2. Select your Storefront.

3. Your configured Storefront will open. Choose any product and proceed to checkout.

4. On the payment page, the available payment methods will be displayed. Select the one you want to test and enter the test data. You can find test card numbers and other relevant information in the Test Cards documentation. Complete the order and payment.

Verifying a Transaction

Once the purchase is approved, you can verify the transaction in the following places:

• In SFCC Business Manager go to Merchant Tools > Ordering > Orders and search for the order you just placed.

The selected order will display full payment information processed through PayU, including transaction status, payment method, authorization details, and other relevant data. This ensures transparency and allows you to track each transaction.

• In PayU Enterprise, go to Payments > Search and look up the transaction.

Debugging the Checkout with PayU

If you receive a declined transaction during testing, you can identify the reason as follows:

1) Checking Logs in Business Manager

Check the logs to find relevant transaction data. To do this:

1. Go to Request Log (top left corner).
2. Search for the request related to the payment attempt.
3. Scroll to the bottom of the log to view the error message or rejection reason returned by PayU.

2) Verifying Order Attributes

Review the order attributes to double-check for any inconsistencies. To do this:

1. Open the order via Merchant Tools > Orders > Search.
2. In the Attributes tab, review the API response from PayU.

3) Checking the Payment Summary

Review the payment summary to verify the transaction details. To do this, open the order and navigate to the Payment tab. There, you’ll find a summary of the payment attempt, including its status and any key messages.

Troubleshooting PayU Job Errors

If you receive an error status while running a PayU job, you can gather more information by following these steps:

1. Navigate to Business Manager > Administration > Operations > Jobs.
2. Select the failed job from the list (e.g., PAYU_REFUND).
3. Click on the History tab.
4. Select the failed execution entry.
5. Click the Log File icon to download the log file.

6. Inside the log, look for the response from PayU or the returned error message.

This information can help you identify whether the issue is related to:

• Incorrect credentials
• Invalid operation for the order
• Invalid order status
• Incorrect amount
• Connection failure

Enabling Installment Promotions

Through this integration, you can offer promotional installments or interest-free months (MSI) to your end customers, based on rules defined in the PayU Enterprise decision engine.

Prerequisites

• Mirror account enabled:
  You must request PayU Latam to create an additional mirror account for your merchant. This account should have only the payment methods enabled that are applicable for MSI or promotional installments.

• Provider configured in the PayU Enterprise control panel for your mirror account:
  You need to register an additional provider in the PayU Enterprise control panel, using the credentials of your mirror account. Follow the same steps used to configure the provider for your main account in Configuring a Payment Provider.

Configuring a Decision Engine

Define the rules that will be applied to route transactions to either your main account or the mirror account enabled for interest-free months or promotional installments by following these steps:

1. Open the PayU Enterprise control panel.
2. In the left-hand menu, select Decision Engine.
3. Choose the Business Unit associated with the site where you currently process payments and want to offer promotions.

4. From the Optimize Your Payment Flow section, select Payment Routing.

5. Add a new routing decision.
   You will need to enter:
   • A name for the routing decision.
   • The conditions that will allow PayU to route transactions to the PayU Latam account enabled for processing promotions or interest-free installments.
   • A required condition, for example:

   Transaction Additional Details
   Key: number_of_installments
   Value type: String
   Equals: Enter the desired number of installments

You may add additional conditions as needed to refine validation and avoid misrouting, including additional filters such as:

• Card Brand
• Card Issuing Country
• Card Type
• Card Issuer or BIN
• Payment Currency
• Payment Amount

These helps identify eligible transactions and apply the installment promotion only when all defined criteria are met.

The routing decision will be triggered when a transaction meets the criteria defined for the promotion, as agreed with your PayU Latam account manager.

The routing decision could look like this: