SDK Integration

PayU’s Software Development Kit (SDKs) provides a simple solution for a complex integration.

Similar to any API integration, you can customize your checkout according to your shop’s needs and the customer stays on your site during the purchase and payment process. To integrate this option you must have a PayU Business account and advanced programming skills.

Access multiple payment methods (varies per country), including credit cards, bank transfers, and cash payments.

API integration

Initial settings

PayU allows you to integrate with the transactional gateway, available payment tools and Queries by developing a web site in Java or PHP. It is critical that sensitive transaction data such as credit card number, expiration date, are not stored. It is recommended to follow PCI DSS’ best practices (Payment Card Industry Data Security Standard).

Java

To integrate with the API, the SDK relies on the Apache’s library HttpClient which also relies on the libraries HttpCore, CommonsLoggin and CommonsCodec.

In general, you need the following libraries in your classpath:

Download SDK Java 1.5.0

Before performing any operation with the SDK, you need to assign some values to the PayU class, which apply to all the SDK operations and must be configured with your commerce data. The following table shows the values you need to configure.

Parameter name Size Type Mandatory Description
language 2 Language Yes The language used for error messages in the system and in emails that are sent to the buyer and seller. It is currently supported in en (English), es (Spanish) and pt (Portuguese).
isTest boolean Yes Assign true if it’s a test request. Otherwise, assign false. Depending on the type of transaction or operation, the behavior may vary depending on the value of this field.
apiLogin Min:12 Max:32 String Yes Your API Login. How do I get my API Login
apiKey Min:6 Max:32 String Yes Your API Key. How do I get my API Key
merchantId String No The merchant identifier, it’s used to generate the signatures to verify payment transactions.
This parameter is mandatory when you want to check the transaction, unless you send the signature.
paymentsUrl Min:1 String No The URL of the page to where you will send the requests related to payments. By default, this parameter takes the production URL.
reportsUrl Min:1 String No The URL of the page to where you will send the requests related to the reports. By default, this parameter takes the production URL.

Example

PayU.apiKey = "xxxxxxxxxxxx"; // Enter your API key here
PayU.apiLogin = "xxxxxxxxxxxx"; // Enter your API Login here
PayU.language = Language.en; // Enter the language here
PayU.isTest = false; // assign true if you are in test mode
LoggerUtil.setLogLevel(Level.ALL); // Include it only if you want to see the full log trace. Otherwise, you can remove it.
PayU.paymentsUrl = "https://api.payulatam.com/payments-api/"; // Include it if you want to test in a specific payment server and assign its URL.
PayU.reportsUrl = "https://api.payulatam.com/reports-api/"; // Include it if you want to test in a specific report server and assign its URL.

To execute the operations provided by the PayU’s SDK, you must send to the method a parameter map as an argument, this map has all the required information to process a transaction. Example:

Map<String, String>  parameters = new HashMap <String, String>();
parameters.put(PayU.PARAMETERS.TRANSACTION_ID, transactionId);
parameters.put(PayU.PARAMETERS.ORDER_ID, orderId.toString());

To ease the usage, you find a set of constants in the interface PayU.PARAMETERS, which contains the names of the parameters used in the SDK methods.

PHP

To integrate with the API, the SDK can be executed in machines with PHP version greater than or equals to 5.2.1. Furthermore, the following PHP extensions are required in your server:

  • curl
  • xml
  • mbstring
  • json

Download SDK PHP 4.5.8

To have access to the SDK features, you need to include the PayU class located in [PayU-php-sdk-Path]/lib/PayU.php.

<?php
require_once '[PayU-php-sdk-Path]/lib/PayU.php';
...
?>

Before performing any operation with the SDK, you need to assign some values to the PayU class, which apply to all the SDK operations and must be configured with your commerce data. The following table shows the values you need to configure.

Parameter name Size Type Mandatory Description
PayU::$language 2 Language Yes The language used for error messages in the system and in emails that are sent to the buyer and seller. It is currently supported in en (English), es (Spanish) and pt (Portuguese).
PayU::$isTest boolean Yes Assign true if it’s a test request. Otherwise, assign false. Depending on the type of transaction or operation, the behavior may vary depending on the value of this field.
PayU::$apiLogin Min:12 Max:32 String Yes Your API Login. How do I get my API Login
PayU::$apiKey Min:6 Max:32 String Yes Your API Key. How do I get my API Key
PayU::$merchantId String No The merchant identifier, it’s used to generate the signatures to verify payment transactions.
This parameter is mandatory when you want to check the transaction, unless you send the signature.

Example

<?php
PayU::$apiKey = "xxxxxxxxxxxx"; // Enter your API key here
PayU::$apiLogin = "xxxxxxxxxxxx"; // Enter your API Login here
PayU::$merchantId = "1"; // Enter your Merchant Id here
PayU::$language = SupportedLanguages::ES; // Enter the language here
PayU::$isTest = false; // assign true if you are in test mode
...
?>

Furthermore, you need to configure the API to redirect the requests using the Environment class:

<?php
// Payments URL
Environment::setPaymentsCustomUrl("https://sandbox.api.payulatam.com/payments-api/4.0/service.cgi");
// Reports URL
Environment::setReportsCustomUrl("https://sandbox.api.payulatam.com/reports-api/4.0/service.cgi");
...
?>

Considerations

  • You must have an active PayU account.
  • You must install a valid SSL certificate in your server and your site must be able to make SSL connections. Due to this, the virtual machine must have appropriate security extensions.
  • Temporarily, do not use security certificates elliptic curve or those who have the suite of encryption TLS_ECDHE_ECDSA_WITH_RC4_128_SHA in your payment requests.
  • You must have CGI or server languages such as Java, C#, VB, PHP, etc.
  • You must be able to store your authentication credentials (API Key and API Login) safely.
  • The encoding for messages must be UTF-8.
  • The dates must have format yyyy-MM-ddTHH:mm:ss, the time format is 24 hours. Example: 2015-08-22T21:35:12.
  • Normally the connection guarantees response times of three seconds on average. If there is an unusual situation, the maximum response time is one minute. It is highly recommended that you set timeouts when you connect with PayU.
  • It is important to validate the length and numbers of credit cards by franchise, together with the security codes.

Available features


Topics in this Section

Payments SDK - Argentina

Payments SDK Argentina lets your shop process different transaction types with multiple payment methods.

Payments SDK - Brazil

Payments SDK Brazil lets your shop process different transaction types with multiple payment methods.

Payments SDK - Chile

Payments SDK Chile lets your shop process different transaction types with multiple payment methods.

Payments SDK - Colombia

Payments SDK Colombia lets your shop process different transaction types with multiple payment methods.

Payments SDK - Mexico

Payments SDK Mexico lets your shop process different transaction types with multiple payment methods.

Payments SDK - Peru

Payments SDK Peru lets your shop process different transaction types with multiple payment methods.

Queries SDK

Queries SDK lets you check the status of the placed orders along with their transactions.

Tokenization SDK

Tokenization SDK allows you to safely store the data of your customers’ credit cards through the creation of a token. This token lets you make regular charges or implement the 1 Click payment feature, following PCI DSS (Payment Card Industry Data Security Standard) security standards to handle credit card data.

Voids and Refunds SDK

This feature allows you to request the cancellation or the refund of the transactions authorized or charged. You can create the refund request using the Refund or Void method according to the status of the transaction.

Last modified March 13, 2024: Documentation updates (ae44f4ea)