Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.
- API Version
- Payment Methods
- Setup Procedures
- Integration Procedures
- Handling the Charge Request Response for Cash Transactions
- Errors in a Redirection Flow
Minimum required API version: 1.0.0
The following features require an API version higher than the minimum:
- 3DS 2.0 External requires API version 1.3.0
The following table lists all supported payment methods.
|Payment Method||Payment Method Type||Notes|
|Elo||Cards||This is a local card vendor.|
|Hipercard||Cards||This is a local card vendor.|
The following table provides an overview of all supported and non-supported features.
The PaymentsOS test environment only supports Authorize and Capture requests (this is a limitation of the PayU Latam sandbox environment).
The following table lists all supported requests. Use the bodybuilder to create a sample request body for each request type.
|Authorize||Partial and multiple are not supported||Asynchronous or Synchronous|
|Capture||Partial is supported||Asynchronous or Synchronous|
|Charge||Not Applicable||Asynchronous or Synchronous||The request can be synchronous or asynchronous, depending on your setup.|
|Refund||Partial is supported||Asynchronous||Partial refund is only supported for the following payment methods: VISA, MASTERCARD, AMEX, DINERS.|
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
pendingin 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.
The following table lists the setup procedures that are specific to this provider.
|In the PaymentsOS Control Center, configure the following credentials: ||Required|
|In the PaymentsOS Control Center, register webhooks to be notified when a transaction changes its status.|
|In your PayU Brazil account, enable the validate unique. This will validate that each payment reference sent to the PayU Latam system is unique.||Required|
|In your PayU Brazil account, enable asynchronous refunds (refunds will initially have a status of pending)||Required|
|In your PayU Brazil 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|
|In your PayU Brazil account, enable the 'Process without a cvv2 security code' feature if you intend to use it.||Optional|
|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
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:
- The expiration date of the Payment Receipt.
provider_data.documentobject 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.
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 (
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.
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.
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.
Not passing a CVV code?
If do not pass a CVV code in the request (
provider_specific_data.payu_latam.process_without_cvv2: true), then you also need to pass an expiration date where MM <= 06 and YYYY != 2022 to simulate a status of
Succeed, in addition to the
holder_name values listed above. When simulating a status of
Failed, MM must be > 07.
Simulating a Request Timeout
You can only simulate a timeout request, if you do not pass a CVV code in the request (
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).
You can use the following cards for testing:
|AMEX Credit Card||376611000000000|
|DINERS Credit Card||36213800000009|
|ELO Credit Card||5067310000000002|
|HIPERCARD Credit Card||6062820000000003|
|MASTER Credit Card||5123740000000002|
|VISA Credit Card||4422120000000008 - 4984460000000008|