PayU Peru

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications in this section to integrate with PayU Peru.

API Version

Minimum required API version: 1.1.0

Payment Methods

The following table lists all supported payment methods.

Payment MethodPayment Method Type
American ExpressCards
DINERSCards
MASTERCARDCards
PAGOEFECTIVOCash
VISACards
YapeeWallet

Currencies

PEN, USD

Features

The following table provides an overview of all supported and non-supported features.

FeatureSupportedNotes
3DS 2.0 ExternalNo
3DS 2.0 PaymentsOS-handledYesSupported flow type: Provider-handled Flow. For more information, see 3DS 2 PaymentsOS-handled Flow.
3DS 2.0 Provider-handledNo
3DS 2.0 Self-handledNo
InstallmentsYes
Level 2 and 3 DataNo
Multi-seller PaymentsNo
Network TokensNo
Payment FacilitatorNo
PayU RiskYes
Pre-authorizationNo
Retrieve Supported Payment MethodsNo
Retrieve Supported PlansNo
Statement Soft DescriptorYes
Stored Credentials FlagNo
Transaction Processing without CVVYes

Requests

The following table lists all supported requests.

Use the bodybuilder to create a sample request body for each request type.

Supported requests for card transactions.
RequestPartial/MultipleModeNotes
AuthorizePartial and multiple are not supportedAsynchronous or Synchronous
  • The request can be synchronous or asynchronous, depending on your setup.
  • Authorize is only supported for the local currency, USD is not supported.
Capture Both partial and multiple are supportedAsynchronous or Synchronous
  • The request can be synchronous or asynchronous, depending on your setup.
  • Capture is only supported for the local currency, USD is not supported.
  • Multiple capture support must be enabled in your provider configuration. For more information, see Configuring Multiple Partial Captures.
Charge Not ApplicableAsynchronous or SynchronousThe request can be synchronous or asynchronous, depending on your setup.
Refund Partial is supportedAsynchronous
Void Both partial and multiple are supportedAsynchronousTo support multiple and partial, you must enable multiple captures in your provider configuration. For more information, see Configuring Multiple Partial Captures.
Supported requests for cash transactions.
RequestPartial/MultipleMode
Charge Not ApplicableAsynchronous
Supported requests for eWallet transactions.
RequestPartial/MultipleMode
Charge Not ApplicableAsynchronous
Refund Both partial and multiple are supportedAsynchronous

Partial Refund Limitations

While partial refunds are supported, the following limitations apply:

  • You can send any amount for the partial refund as long as the value doesn’t exceed the initial or actual amount.

  • You can send as many as partial refund request as you require. The sum of the partial refund amounts cannot not exceed the total value of the transaction.

  • A partial refund request will always get a status of pending in the response. Partial refunds are processed manually by a PayU representative. The refund may take 2 to 6 calendar days to be processed. Once done, depending on the acquirer, the amount will appear in the extract in the next 1 to 30 days after the partial refund is processed.

  • If a partial refund is pending or is being processed, you cannot send a new request until the last one is processed.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

ConfigurationRequired/Optional
In the PaymentsOS Control Center, configure the following credentials:
  • apiLogin: The user name supplied by PayU Peru
  • apiKey: The password name supplied by PayU Peru
  • accountId: The identifier of the account in PayU Peru
  • paymentCountry: PER
  • merchantId: The merchant ID in PayU Peru
When creating a new provider configuration in the PaymentsOS Control Center, select PayU Latam as the provider.
Required
In the PaymentsOS Control Center, create webhooks to be notified when a transaction changes its status.

Notes:
  • Make sure to configure webhook notifications for refunds as well.
  • Some API requests in the payment flow may remain in a pending status for some time.
Required
In your PayU Peru account, enable the validate unique. This will validate that each payment reference sent to the PayU Latam system is unique.Required
In your PayU Peru account, enable asynchronous refunds (refunds will initially have a status of pending)Required
In your PayU Peru account, enable refund notifications. Make sure to include the transaction_type field in the notification (this step is required for PaymentsOS to remain in sync with the refund status).Required
Contact PayU Latam Support to get a list of the minimum payment amounts required by the payment methods that you intend to use.

To avoid unnecessary request failures, we recommend that you include some 'minimum value' validation for the transaction payment.amount in your system.
Optional
Enable multiple captures in your provider configuration. For more information, see Configuring Multiple Partial Captures.Optional

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Handling the Charge Request Response for Cash Transactions

If the charge request is successful, then the provider will return a charge response containing:

  • A status of pending.
  • The expiration date of the Payment Receipt.
  • A provider_data.document object with href links to the Payment Receipt in HTML format and possibly the Payment Receipt in PDF format.

Note that the provider_data.additional_information field may contain a barcode, for receipt tracking purposes.

Now direct your customer to one, or both of the transaction payment receipts, so that they can print the receipt. Your customer should then take the payment receipt to the relevant Payment Office and pay for their purchase, before the expiration date.

When the provider notifies us that your customer has paid, we will update the transaction status. If no payment notification is received by the expiration date then the transaction will be considered as failed.

Configuring Multiple Partial Captures

Suppose your acquirer does not support multiple partial captures, yet your business model requires you to invoke multiple capture requests for a single transaction. You can configure this functionality via your PaymentsOS account (Account > Providers) and choose ‘true’ from the drop-down menu of the ‘multiCapture’ field, like so:

Configuring Multiple Partial Captures

After activating this functionality, you will need to invoke separate capture request for every partial-capture you perform or separate void requests in case an item is out of the stock. We will submit a final capture request on your behalf for the sum of all of these partial captures when the total sum of your partial captures and voids reaches the full authorization amount, or if the capture time frame has timed out.

A few things to note:

  • A transaction’s initial status will always be pending and will remain pending until we invoke the final capture request. The transaction status will change according to the provider’s response, to reflect its new status (i.e., it will change to either succeed or failed).
  • When a transaction status changes to either succeed or failed, you will receive webhook notifications with the final statuses of each of the partial capture requests or partial void requests you invoked (e.g., if you invoked five capture requests, you will receive five webhooks).
  • Time limitation: Acquirers limit the time allotted to invoke a final capture request. We send the final capture request after five days to comply with these limitations.
  • If the total amount of the partial captures you invoked doesn’t equal the original authorization amount, we pass the partial amount for the acquirer’s approval after five days.
  • When you send a void request with no previous capture requests - though the sum still equals the original authorization amount - we call the provider with a void request to release the money back to the shopper’s account.

Errors in a Redirection Flow

In a redirection flow, customers finalize a transaction on a third-party site and are then directed back to your web page (the merchant_site_url) where you inform them of the status of their payment. Of course, there’s always a chance of an unexpected error (such as a provider communication timeout) in this process. If an error does occur, we’ll let you know about it by appending the type of error (api_error or provider_error) to the merchant_site_url. If available, we will also include the ID of the original payment request and related transaction request (action).

Here’s an example.

<merchant_site_url>?error=api_error&payment_id=dd1fbe34-4636-4a61-8cb1-27ac8a175284
&action_id=f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb/

Testing

Follow the steps in the PayU integration testing page.

To test requests in the PayU Latam sandbox environment, make sure your account has been configured to operate in test mode. You can then simulate specific response statuses for each request type, as listed below.

For Authorization and Charge Requests:

  • To simulate a status of Succeed, pass in "holder_name": "APPROVED" in the Create Token request.

  • To simulate a status of Pending, pass in "holder_name": "PENDING_TRANSACTION_REVIEW" in the Create Token request.

  • To simulate a status of Failed, pass in "holder_name": "REJECTED" in the Create Token request.

For Capture, Refund and Void requests:

  • To simulate a successful Capture request, first initiate a successful Authorization request.

  • To simulate a successful Refund request, first initiate a successful Charge or Capture request.

  • To simulate a successful Void request, first initiate a successful Authorization request.

Simulating a Request Timeout

To simulate a request timeout, invoke the Create Token request and pass an expiration_date with a format of MM/2022, where MM is the delay in seconds. The month (MM) can be any value between 01 (10 seconds) and 05 (50 seconds).

Test Cards

You can use the following cards for testing:

Card Number
AMEX Credit Card 377753000000009
DINERS Credit Card 36239200000000
MASTER Credit Card 5491610000000001
MASTER Debit Card 5236930000000003
VISA Credit Card 4907840000000005 - 4634010000000005
VISA Debit Card 4557880000000004
Last modified September 6, 2022