PayU Colombia
API Version
Minimum required API version: 1.1.0
The following features require an API version higher than the minimum:
- 3DS 2.0 External requires API version 1.3.0
Payment Methods
The following table lists all supported payment methods.
Payment Method | Payment Method Type | Notes |
---|---|---|
American Express | Cards | |
BANK REFERENCED | Cash | Payment offices: Davivienda, Banco de Bogotá, Bancolombia. |
DINERS | Cards | |
EFECTY | Cash | |
Google Pay | eWallet | |
MASTERCARD | Cards | |
Nequi | eWallet | |
OTHERS CASH | Cash | Local name: Matrix (Su Red). Payment offices: PagaTodo, Gana Gana, Gana, Acertemos, Apuestas Cúcuta 75, Su Chance, La Perla, Apuestas Unidas, JER. |
PSE Bank Transfers | Bank Transfer | |
VISA | Cards |
Currencies
COP, USD
Features
The following table provides an overview of all supported and non-supported features.
Feature | Supported | Notes |
---|---|---|
3DS 2.0 External | Yes | |
3DS 2.0 PaymentsOS-handled | Yes | Supported flow type: Provider-handled Flow. For more information, see 3DS 2 PaymentsOS-handled Flow. |
3DS 2.0 Provider-handled | No | |
3DS 2.0 Self-handled | No | |
Installments | Yes | |
Level 2 and 3 Data | No | |
Multi-seller Payments | No | |
Network Tokens | Yes | |
Payment Facilitator | No | |
PayU Risk | Yes | |
Pre-authorization | No | |
Retrieve Supported Payment Methods | No | |
Retrieve Supported Plans | No | |
Statement Soft Descriptor | Yes | |
Stored Credentials Flag | No | |
Transaction Processing without CVV | Yes |
Requests
Note
The PaymentsOS test environment does not support the requests listed (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.
Request | Partial/Multiple | Mode | Notes |
---|---|---|---|
Authorize | Partial and multiple are not supported | Asynchronous or Synchronous | |
Capture | Partial and multiple are not 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 refunds require that you send unique partial refund requests. |
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
Request | Partial/Multiple | Mode |
---|---|---|
Charge | Not Applicable | Asynchronous |
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
Creating a provider configuration
When creating a new provider configuration in the PaymentsOS Control Center, select PayU Latam as the provider.The following table lists the setup procedures that are specific to this provider.
Configuration | Required/Optional |
---|---|
In the PaymentsOS Control Center, configure the following credentials:
| Required |
In the PaymentsOS Control Center, create webhooks to be notified when a transaction changes its status. Notes:
| Required |
In your PayU Colombia account, enable the validate unique. This will validate that each payment reference sent to the PayU Latam system is unique. | Required |
In your PayU Colombia account, enable asynchronous refunds (refunds will initially have a status of pending) | Required |
In your PayU Colombia 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 Colombia 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 payment.amount in your system. | 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
ofpending
. - 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.
Permission to use the PSE Payment Method
PSE Certification
PSE certification is required, before being allowed to use the PSE payment method. To receive certification, you’ll need to conform to the specifications setup by the ACH organization, which is responsible for the PSE payment method.
Creating a PSE Bank Transfer Capture Page
The PSE Bank Transfer Capture page is used by your customer, to capture their PSE Bank Transfer details. Create this page on your site according to the specifications described in the PayU PSE (Colombia) Certification Guide (Download as PDF or Download as HTML.
Redirecting your Customer to Capture the PSE Bank Transfer
When you send a post charge request, we will return a charge resource containing a charge.redirection.url
, and a status of pending
.
Redirect your customer to this URL (the PSE Bank Transfer Capture page on your site), so that they can capture the bank transfer.
For detail of how to create the PSE Bank Transfer Capture page on your site, and how your customer should capture a PSE bank transfer, see the Permission to use the PSE Payment Method section above.
Once the PSE bank transfer has been captured, we’ll redirect your customer’s browser back to your site, using the merchant_site_url (that you provided in the post charge request). We’ve included the following URL parameters in the merchant_site_url
, to provide you with the context of the page that you’ll need to load: payment_id
, charge_id
, and status
(of the charge).
Example - Charge request Pending:
<merchant_site_url>
?payment_id=dd1fbe34-4636-4a61-8cb1-27ac8a175284
&charge_id=aec1c306-e0f7-452b-8fb5-5b34489e9d10
&status=Pending
The status of your Charge request may still be ‘pending’ when we redirect your customer back to your site (while the provider is processing the request).
Example - Charge request failed:
<merchant_site_url>
?payment_id=dd1fbe34-4636-4a61-8cb1-27ac8a175284
&charge_id=aec1c306-e0f7-452b-8fb5-5b34489e9d10
&error=provider_error
Integrating Google Pay™
Note
If you use Google Pay, you must comply with the Google Pay API Acceptable Use Policy and accept the terms and conditions set forth in the Google Pay API Terms of Service.Integrating Google Pay involves the following:
-
Adding Google Pay to your checkout page.
-
Integrating Google Pay with your PaymentsOS transaction flows.
Adding Google Pay to your Checkout Page
Start by adding Google Pay to your checkout page, as explained in the following documentation:
- Google developer documentation.
- API integration checklist
- Brand guidelines published on the Google developer documentation site.
When you add Google Pay to your checkout page, you will also create a script to allow Google to encrypt the information for the card selected by the payer for secure processing. The gateway parameter in the script should have a constant value of payulatam
, and the gatewayMerchantId
should contain your PayU account number. Here’s an example:
const tokenizationSpecification = {
type: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'payulatam',
'gatewayMerchantId': 'YOUR_ACCOUNT_ID '
}
};
Note that PayU, as the processor of Google Pay payments, supports all types of payment cards issued by Visa and Mastercard. Therefore, you should instruct the Google script to use the following allowedCardNetworks
and allowedCardAuthMethods
:
const allowedCardNetworks = ["MASTERCARD", "VISA", “ELECTRON”, “MAESTRO];
const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
Now proceed to integrate Google Pay with PaymentsOS.
Integrating Google Pay with PaymentsOS
Once you’ve added Google Pay to your checkout page, you are ready to integrate Google Pay with PaymentsOS. Proceed as follows:
- When the customer chooses to pay with Google Pay, grab the token that Google returns to your web page from
tokenizationData.token
and grab the card network name frompaymentMethodData.cardNetwork
. Here’s a sample response from Google:
{
"apiVersion": 2,
"apiVersionMinor": 0,
"paymentMethodData": {
"description": "Visa •••• 9792",
"info": {
"assuranceDetails": {
"accountVerified": true,
"cardHolderAuthenticated": false
},
"cardDetails": "9792",
"cardNetwork": "VISA"
},
"tokenizationData": {
"token": "{\"signature\":\"MEUCIBuuToFwppW6YXcxf47WrBKfkXwhXXF01m/tb/fsjT7PAiEA/qjWfL3STHfJgIPkWgXqCPSKrh/jCqEAmkKUj0plQT0\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8vUyahj3Dg9J496cv7ML7+BRf61lgEE2TJqCeul7y+icQ2q0vzACDGeNVlY/YWCLnlX/vWNnBOeGUk6+g1tdkQ\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1706759255632\\\"}\",\"signatures\":[\"MEQCIGqB2pW8+5L8i9GqE/TxDNIOxgt5u8yrKp8zadC7Kw3zAiAMlv8YEVOGz+jp+TlsmW4JiW7YV4t0CLkevyha34LPPw\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"iQaWYUOWRUod96OCqcz0jWU2d0fuf1Og0NNoeqGLOEF1pug4Gq2itU1yaWj9FMvjTryBeBfAA00w0L2uIezjWkTajb5Dfy2hXgiiwUfJjDNZXwVQfUKvzHM0WmX/kWsEx8NcnuWrgk+4XZOZuvF+HRUmMiyZH7kF204jE8rmPdQiIxdAQC0NE/iyXWnEW5AH/7+ltpdXmDZnElf6Pbh5gPe/bF6bo9JiNuvun6QkII1VwtxU3wz6MqlBWY5GSk4Am3sCU7PWzUKh/k3eeMEEhyZjxVVb/PGjqY6pYcsL2I57PnplWLkrvCvg7X7ycWAzWAGdqyv+8U/AjBl8jcPffVT7URfSqHhhbaXB+0F2PIhiYYhHyP1TrIJbHVMEMNK4EDOOerKfjg7zGk2/3V9AFLHZkBon7CCwfw7GTASRqzu//8vm57VPETJJczPmGubFQB/vJigR8gufJJt8KDYOEe/QMsPWhIpyg+0r6YlNO4cSX7nG4eotQcQYKFTc9UtDpdk44ZipdkGzY++U8PawREe3qy4QE2X9q2cYWXdxKiyQxV8rrP2NuTFBxFaPBKHu5XG1agca\\\",\\\"ephemeralPublicKey\\\":\\\"BMVxybvdkSOBQbUwmKfgJcgIZBdAKCGjeeEMGyxcv6G+7xRr+Ifzh+Zrj07RnRLnCAjqnxzpD+OaNMLtYl7Y8rA\\\\u003d\\\",\\\"tag\\\":\\\"331LwnejlJHo1nONzei7fYqEUjFFGiWEXlYGZXY0HG0\\\\u003d\\\"}\"}",
"type": "PAYMENT_GATEWAY"
},
"type": "CARD"
}
}
- Pass the token in the
payment_method.additional_details.googlepay_token
field of the Create Charge request. Also pass the card holder name in thepayment_method.additional_details.creditcard_name
field, and pass the card network name in thepayment_method.additional_details.card_network
field. Here’s a sample request body (notice that the Google Pay token value must be passed as astring
):
{
"payment_method": {
"source_type": "ewallet",
"type": "untokenized",
"vendor": "googlepay",
"additional_details": {
"card_network" : "MASTERCARD",
"creditcard_name": "Nhoj Atlovart",
"googlepay_token": "{\"signature\":\"MEUCIQCwQu3vBAe9YTgaFU+\/TAlCBF7\/ssCUoNh\/jqLMZ694aAIgIKqTbiDhZH05V3EXmeZNjqloTUbpo4aC753Kkqz9sLo\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEHb3\/4WkpiP5IfynAS7dHdgpB2jIjgkaAvBWMHS4rg63H6C0Y3zAshWzUW45j2LCzjQ4JeXGcHZn9suXJJuHdbA\\\\u003d\\\\u003d\\\"...}"
}
},
"reconciliation_id": "40762342"
}
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.
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.
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
Note
You can only simulate a timeout request, if you do not pass a CVV code in the request (provider_specific_data.payu_latam.process_without_cvv2: true
)
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 Procedures for Bank Transfers
Use the following test values in the post charge
request:
"bank_transfer_financial_institution_code": "1022",
"bank_transfer_financial_institution_name": "BANCO UNION COLOMBIANO",
"user_type": "N",
"national_identify_number_type": "CC",
Follow a step by step procedure to test PSE bank transfers in the PayU Sandbox environment. For details see the PSE Test Guide (PDF).
Test Cards
You can use the following cards for testing:
Card | Number |
---|---|
AMEX Credit Card | 377813000000001 |
DINERS Credit Card | 36032400000007 |
CODENSA Credit Card | 5907121111111115 |
CRM Credit Card | 6271800000000002 |
MASTER Credit Card | 5471300000000003 |
MASTER Credit Card2 | 2221000000000009 |
VISA Credit Card | 4097440000000004 |
VISA Debit Card | 4509420000000008 |