PayU Colombia/LATAM (via PaymentsOS) integration guide

PayU Colombia PayU Colombia/LATAM via PaymentsOS Connection is a gateway that allows you to collect card payments. This guide is intended to help you implement PayU Colombia based on your preferred integration workflow.

Services and compatibility

Supported payment types
  • Card
Supported transaction types
  • Sale (saved card token) ( API )
  • Refund (partial and multiple) ( API )
Supported processing currenciesCOP, USD
3D Secure 1.x supportedNo
3D Secure 2.x supportedNo
External 3D Secure supportedNo
Installments supportedYes

Gateway-specific information

PayU Colombia supports sale transactions as well as partial, multiple, or full refunds. For refunds, refundReason is a required parameter.

For Kount with PayU Colombia, only Success, Decline, and Error statuses are available. Review is not supported. For additional information about Kount, see Kount verification.

The installment feature for recurring billing is supported. Use a period of 1-36. The amount must be at least 300 and the transaction currency must be COP. For additional information, see Recurring billing overview.

The following are not supported with PayU Colombia:

  • Auth-only and Capture
  • 3D Secure
  • Void


Apart from working with Integrations Support to add PayU Colombia as a connection, you do not need to do any other configuration steps.

Required fields

In addition to the default required field of data.amount, PayU Colombia requires the following fields to process a transaction with the Run card transaction or Run card transaction with iframe endpoint.

For many of the fields, when included in the Create one-time-use token, Save card token, or Save card token with iframe endpoint. the field is stored in the card token and automatically gets sent with the Run card transaction request without needing to explicitly specify it. For more information about this possibility, see the What data is saved with tokens? topic.

Required FieldDescription
card.securityCodeThe numeric code printed on the card for enhanced security.

When included in the Save card token or Save card token with iframe request, Nexio caches the value for up to 24 hours. Therefore, if you save the card token and then submit a transaction with that card token more than 24 hours later, you need to recapture the security code.
data.amountThe transaction amount.

For installments, this value must be a minimum of 300 COP.
data.currencyThe three-character ISO currency code for the transaction. For PayU Colombia, supported currencies are COP and USD. For installments (recurring payments), only COP is allowed.

If you do not include this parameter, the system uses the default of USD. Therefore, if your merchant account does not support USD, you will get an error response.
data.customer.emailThe customer's email address.
data.customer.billToCountryThe two-character (Alpha-2) ISO country code.
data.customer.shipToCountryThe two-character (Alpha-2) ISO shipping country code.
data.customer.orderNumberThe order number. This must be a unique value for the merchant with PaymentsOS. If a payment fails, you can continue to reuse that orderNumber value until the payment succeeds. If you use a value that is not unique, the system returns an error.
data.customer.nationalIdentificationNumberThe identification number issued by a national authority to the individual person, such as a social security number.

The following list provides information about potential identification sources:
  • Brazil: CPF or CNPJ.
  • Chile: RUN for individual users and RUT for companies
  • Colombia: For individual users CC (Cédula de ciudadanía), CE (Cédula de Extranjería) and TI (Targeta de Identidad) and for companies NIT
  • Mexico: RFC and CURP (individual user) and RFC (legal entity/company)
data.descriptorInclude this parameter to specify the descriptor on the customer's statement.

Testing data

Use the following test card information to test your PayU Colombia configuration. For more information about testing, see Testing for PayU Colombia on the PaymentsOS website.

BrandCard numberExpiration dateSecurity codeCardholder nameTransaction result
American Express377813000000001Any7777APPROVEDSuccess
American Express377813000000001Any6666AnyDecline

Status workflows

The status of a successful transaction with PayU Colombia varies, depending on the options you choose.

SaleSuccessful capture transactions will have the following statuses:
  • pending* or authorized
  • settled
RefundSuccessful refund transactions will have the following statuses:
  • pending* or authorized
  • settled

*Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the appropriate transactionStatus table).

If you have any additional questions or feedback, contact us.