Skip to main content

Charging Tokens

To charge tokens, you need to extend the order request by including the buyer object and payMethod section, where the multi-use token (TOK_) serves as the value parameter. To delve into further details on how to create a new order via the REST API, you can refer to the Creating a New Order section.

When conducting a payment using a multi-use token (TOKC_), it is essential to set the cardOnFile or recurring parameter, which provides information about the party initiating the payment:

  1. cardOnFile:
    • STANDARD_CARDHOLDER - refers to a payment made with a previously saved card, initiated by the card owner. Depending on specific payment parameters, such as high transaction amounts, strong authentication, such as 3D Secure and/or CVV, may be required.
    • STANDARD_MERCHANT - refers to a payment made with a previously saved card, initiated by the shop or merchant without the involvement of the card owner. As per the definition, this payment type does not necessitate strong authentication. However, it's important to note that you cannot use this option if the FIRST card-on-file payment had previously failed.
  2. recurring:
    • STANDARD - refers to a subsequent payment in the cycle made with a previously saved card, initiated by the shop or merchant without the involvement of the card owner. As per the definition, this payment type does not necessitate strong authentication. However, it's important to note that you cannot use this option if the FIRST recurring payment had previously failed.
Notes

Carefully considering the value of the cardOnFile and recurring parameter can increase conversion for payment cards.

Example of Charging multi-use Token (TOKC_) Initiated by the Seller
curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
    "notifyUrl":"https://your.eshop.com/notify",
    "customerIp":"127.0.0.1",
    "merchantPosId":"145227",
    "description":"Laptop",
    "currencyCode":"PLN",
    "totalAmount":"15000",
    "cardOnFile": "STANDARD_MERCHANT",
    "extOrderId":"9xl0x8nr1wk7m0i3ltqbja",
    "products":[
        {
            "name":     "Laptop",
            "unitPrice":"15000",
            "quantity": "1"
        }
    ],
    "buyer": {
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "language": "en"
    },
    "payMethods": {
        "payMethod": {
            "value": "TOKC_2IHRST6HKSST3H62K2GS8pElI862",
            "type":  "CARD_TOKEN"
        }
    },
    "deviceFingerprint": "0372098a4a90927db053463454491d78"
}'

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

Example Response for Successful Request
{
    "orderId": "ORDER_ID",
    "payMethods": {
        "payMethod": {
            "card": {
                "number": "424242******4242",
                "expirationMonth": "12",
                "expirationYear": "2017"
            },
            "type": "CARD_TOKEN",
            "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
        }
    },
    "status": {
        "statusCode": "SUCCESS",
        "statusDesc": "Request successful"
    }
}

This response indicates that additional payer authentication may not be necessary. However, please be aware that depending on specific circumstances, 3DS or CVV may still be required during the payment process. For further details on handling 3DS and CVV, please refer to the appropriate sections.

PayU keeps you informed about the payment status by sending a notification to the address specified in the notifyUrl parameter of the order. To gain a comprehensive understanding of how notifications are handled, please refer to the Notifications section.

Handling 3DS​

If a WARNING_CONTINUE_3DS response is received, the payer should be redirected to the card issuer's page using the redirectUri parameter for additional payment authentication through the 3D Secure process. It is important to note that the authentication is currently carried out exclusively via the 3DS 2 protocol, as indicated by the value of the threeDsProtocolVersion field.

To understand how to handle the 3DS2 protocol and Strong Customer Authentication (SCA) requirements, please visit the 3DS 2 (SCA) page.

Example of WARNING_CONTINUE_3DS Response
{
    "orderId": "ORDER_ID",
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2"
}

After successful 3DS authentication on the card issuer's page, the payer is redirected back to the page address that you provided as the continueUrl in the order request body. The redirected URL will have two additional parameters in the query string:

  • statusCode - can have values of either SUCCESS or WARNING_CONTINUE_CVV, indicating the result of the authentication process.
  • refReqId - random alphanumeric string of characters that serves as a reference identifier.
URL Example
https://your.shop.com/payment?statusCode=SUCCESS&refReqId=5c867936fbb3cc2c373820b4550b4645

When the statusCode parameter has the value of SUCCESS, it indicates that the 3DS authentication was successful, and the order has been accepted without the need for another authentication of the payer. At this point, you should wait for the order status notification, which will provide you with the final status of the payment transaction.

Handling CVV2​

In the case of WARNING_CONTINUE_CVV, you should ask the payer to provide CVV2/CVC2 code. To facilitate this process, you need to handle the redirectUri parameter differently depending on the integration type:

WARNING_CONTINUE_CVV Response Example
{
    "orderId": "ORDER_ID",
    "status": {
        "statusCode": "WARNING_CONTINUE_CVV",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}"
}
Example of redirectUri Parameter
https://secure.payu.com/api/v2/token/token.json?refReqId=11ed628ebe88ef6837d90ebb26f1a8b9

Once the payer has provided the CVV2/CVC2 code, PayU will send the order status to notify you of the payment outcome.

On this page