Skip to main content

Card Data in Text Form

If you meet the PCI requirements and directly collect and store your customers' card data, you have the option to securely transmit this data to PayU in plain text form.

PCI DSS Requirements

This integration type is exclusively available to those who meet the PCI DSS requirements pertaining to the storage and processing of card data. To enable this integration, additional configuration is necessary. Before proceeding with the integration process, we strongly advise you to get in touch with your designated sales representative at PayU.

Extending the Standard Order​

To facilitate payment with pure card data, the standard order must be enhanced with a payMethods object. Additionally, if payment involves stored card data, you should include either a cardOnFile or a recurring field.

Creating a Payment with Card Data in Text Form​

The card data must be sent in the form of a card object contained in the payMethods section.

Example of the payMethods Section Containing card Object
"payMethods": {
    "payMethod": {
        "card": {
            "number":"5100052384536818",
            "expirationMonth":"11",
            "expirationYear":"2020",
            "cvv":"123"
        }
    }
},

For details on parameters, please refer to the Create an Order section in the PayU API Reference.

cardOnFile Parameter​

You should utilize the cardOnFile parameter when the payment is non-recurring, but involves either a stored card or storing the card for future use.

  • FIRST - payment initiated by a cardholder who has agreed to save it for future use. You can expect full authentication (3D Secure and/or CVV).
  • STANDARD_CARDHOLDER - payment with an already saved card, initialized by the card owner. Depending on payment parameters (e.g. high transaction amount), you can expect strong authentication (3D Secure and/or CVV).
  • STANDARD_MERCHANT (MIT - Merchant-Initiated Transaction) - payment with an already saved card, initialized by the shop without the card owner's participation. By definition, this payment type does not require strong authentication. You cannot use it if the FIRST card-on-file payment failed.
Note that...

The cardOnFile parameter cannot be used with the recurring parameter.

This cardOnFile parameter can only be skipped in the case of a one-time card payment.

For a transaction with plain card data and the cardOnFile parameter set to FIRST, you should extend the payMethods.payMethod section with a card object containing card data in text form.

For subsequent transactions marked as STANDARD_MERCHANT, you should pass the card scheme identifiers of the first successful and completed transaction in the payMethods.payMethod.card section of the transaction request:

  • firstTransactionId - identifier of the first payment. Pass it in every subsequent payment with the stored card. For Mastercard it is the so-called Trace ID, for Visa it is the so-called Visa Transaction Identifier.
  • schemeTransactionId - for stored Mastercard cards, you should also pass an additional identifier of the first payment, the so-called Mastercard Transaction Link Identifier (TLID). Pass it in every subsequent payment with the stored card. Ignore this value for Visa cards.

You can obtain them from the transaction data (card.cardData section) or from the order details retrieved with the with=authorization parameter (authorization.payTypeDetails section) of the first transaction.

For Your Information!

For Mastercard cards, store the schemeTransactionId (TLID) returned for the FIRST payment together with its firstTransactionId (Trace ID) and pass both values in all subsequent payments of the series. Do not replace the stored TLID with schemeTransactionId values returned for subsequent payments.

Mastercard Transaction Link Identifier (TLID)

Mastercard has introduced a new transaction identifier, the Transaction Link Identifier (TLID), in addition to the currently used Trace ID. The TLID is returned in the schemeTransactionId field for payments processed since September 30, 2026. From October 23, 2026, it is highly recommended to send the TLID together with the Trace ID in every subsequent payment with the stored card. Apply this rule to MIT payments (initiated by the shop, i.e. cardOnFile set to STANDARD_MERCHANT or recurring set to STANDARD).

If the first payment was made before September 30, 2026, its TLID is not available. In such case, pass only the Trace ID in firstTransactionId.

Example of the payMethods Section for a Mastercard Card with firstTransactionId and schemeTransactionId
"payMethods": {
    "payMethod": {
        "card": {
            "number":"5100052384536818",
            "expirationMonth":"11",
            "expirationYear":"2020",
            "cvv":"123",
            "firstTransactionId": "MCC0111LL1121",
            "schemeTransactionId": "LzVYm4HlSDaYsHMFmAp4Jg"
        }
    }
},
Example of the payMethods Section for a Visa Card with firstTransactionId
"payMethods": {
    "payMethod": {
        "card": {
            "number":"4444333322221111",
            "expirationMonth":"11",
            "expirationYear":"2020",
            "cvv":"123",
            "firstTransactionId": "483300123456789"
        }
    }
},

For details on parameters, please refer to the Create an Order section in the PayU API Reference.

Setting the cardOnFile parameter in the correct way can increase conversion for payment cards and can guarantee transaction security.

recurring Parameter​

The recurring field marks the order as a recurring payment with stored card data (an order must be flagged as either cardOnFile or recurring; sending both fields will return an error).

The recurring parameter can take one of two values:

  • FIRST - first transaction with full authentication (the user is present and has agreed to recurring payment terms),
  • STANDARD - subsequent recurring payment (user is not present).

For subsequent transactions marked as STANDARD, you should pass the firstTransactionId of the first transaction (and, for Mastercard, its schemeTransactionId) in the payMethods.payMethod.card section of the transaction request, in the same way as described for the cardOnFile parameter.

For details on parameters, please refer to the Create an Order section in the PayU API Reference. And if you are looking for more information about recurring payments, see Recurring Payments.

Setting the recurring parameter in the correct way can increase conversion for payment cards and can guarantee transaction security.

sourcePaymentFlow Parameter​

When you integrate with a digital wallet provider (e.g., Visa Mobile) and want your payment to be processed by PayU, you need to extend the standard order with a payMethods section. Additionally, you must expand the payMethods section with the following:

  • a card section containing payment instrument data in the form of a digital wallet,
  • a threeDsData section including the tavv parameter with the Token Authentication Verification Value (TAVV),
  • the sourcePaymentFlow parameter indicating the source as a digital wallet, e.g. CLICK_TO_PAY.

The sourcePaymentFlow parameter can take one of the following values:

  • CARDS (default value)
  • APPLE_PAY
  • CLICK_TO_PAY
  • GOOGLE_PAY
  • MDES
  • VISA_MOBILE
  • VTS
Example of the payMethods section containing data provided by a digital wallet provider
"payMethods": {
    "payMethod": {
        "card": {
            "number": "5100052384536818",
            "expirationMonth": "1",
            "expirationYear": "2026"
        },
        "threeDsData": {
            "tavv": "AgAAAHsAodvkMRYBFT8CgOpQEAA="
        },
        "sourcePaymentFlow": "VISA_MOBILE"
    }
}

External 3D Secure​

In case you do not provide a 3D Secure authentication result (see External 3D Secure), you should be prepared for handling responses with: WARNING_CONTINUE_3DS or WARNING_CONTINUE_CVV.

On this page