Skip to main content

Creating Tokens

Single-use Token​

There are two scenarios for a single-use token:

  • a one-time payment with a single-use token - use the tokenize method with SINGLE passed as its value. This will enable you to tokenize the card information and receive a single-use token that can be used for one payment only.
  • the first payment with saving the card for future use - use the tokenize method with MULTI passed as its value. This will enable you to tokenize the card information and receive a single-use token that can be used for a one-time payment, and saved for future use.

Multi-use Token​

The creation of a multi-use token (TOKC_) occurs after the first use of a single-use token (TOK_). There are two scenarios in which you can create a multi-use token:

Notes

When a card is stored without making an actual purchase, it is essential to avoid creating an order with a non-zero total amount that is later canceled. Such approach is not compliant with card scheme regulations. Instead, when storing a card without making a purchase, you should set the total amount of the order to 0.

Creating Multi-use Tokens During Purchase​

Creating token during purchase is the standard and most common way to store a card.

When a customer completes a successful transaction using a single-use token (TOK_), they may be given the option to store their card information for future use. If the customer chooses to do so during the purchase process, a multi-use token (TOKC_) is generated and associated with their card details,

Requirements

When creating a new order, you should extend it with buyer and payMethod sections where single-use token (TOK_) is used as a value parameter.

Additionally, cardOnFile parameter should be set to FIRST (for details on cardOnFile parameter, please refer to Create an Order section in our API Reference).

Make sure that your point of sale (POS) is properly configured to allow the creation of multi-use tokens.

Request Example With Purchase
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": "FIRST",
      "extOrderId":"g1d5q9lpxz5rg556qiue0q",
      "products":[
         {
            "name":     "Laptop",
            "unitPrice":"15000",
            "quantity": "1"
         }
      ],
      "buyer": {
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "language": "en"
      },
      "payMethods": {
          "payMethod": {
               "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
               "type":  "CARD_TOKEN"
          }
      },
      "deviceFingerprint": "1436437b3265e8311c0495a233dcd0a7"
  }'

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

Highlighted above is the payMethods object, which contains single-use token (TOK_)

POS used in the example does not have tokenization switched on.

Response Example for Order With Purchase
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2"
    "orderId": "ORDER_ID",
    "payMethods": {
        "payMethod": {
            "card": {
                "number": "424242******4242",
                "expirationMonth": "12",
                "expirationYear": "2017"
            },
            "type": "CARD_TOKEN",
            "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
        }
    }
}

Highlighted in the response is the multi-use token (TOKC_), which can be used for future payments.

The above response assumes that additional payer authentication may be required using 3DS. For more details on handling 3DS and the authentication process, please refer to the Handling 3DS section.

PayU sends payment status notifications to the URL provided in the notifyUrl parameter. These notifications are essential to keep your system updated with real-time information about the payment status. For further details on how to handle and process notifications, please refer to the Notifications section.

Creating Multi-use Tokens Without Purchase​

Special Configuration

Special arrangements are required before this feature is enabled in either sandbox or production enviroment. Please contact your sales representative in PayU first to find out if you can use this service.

In some cases, you may want to store the card information without an actual purchase being made. This scenario is useful, for example, when you offer free trial periods or want to allow customers to store their card upfront for future use without any immediate charge. In such cases, you can programmatically request the creation of a multi-use token (TOKC_) for a specific card,

Creating multi-use tokens without a purchase involves some special conditions and considerations:

  • Standard order request should be extended with buyer and payMethod sections where single-use token (TOK_) is used as a value parameter.

  • In the request body, the totalAmount parameter should be set to 0 to indicate that no actual charge will be made during the token creation process. However, please note that even though the totalAmount is set to 0, you still need to provide the currency parameter for the sake of API consistency.

  • products object is not required.

  • Zero-amount orders are always auto-received - even in case when card payments are otherwise configured not to be auto-received, for zero-amount always expect status transition from PENDING to either COMPLETED or CANCELED but never to WAITING_FOR_CONFIRMATION.

  • Zero-amount orders are not possible for "shops" configured as marketplace where shoppingCarts object is required.

  • cardOnFile/recurring parameter should be set to FIRST (for details on cardOnFile/recurring parameter, please refer to Create an Order section in our API Reference).

  • Zero-amount orders are only possible for card payments.

  • Your POS must be configured to allow creating multi-use tokens and you "shop" must be configured to allow zero-amount orders.

Request Example Without Purchase
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":"0",
      "cardOnFile": "FIRST",
      "extOrderId":"4ifibqsc9nwkvanq6rcfm9",
      "buyer": {
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "language": "en"
      },
      "payMethods": {
          "payMethod": {
               "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
               "type":  "CARD_TOKEN"
          }
      },
      "deviceFingerprint": "3707dda5515f445886e3b6fff404039b"
  }'

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

The highlighted sections above represent important elements of the payment flow for creating multi-use tokens without a purchase:

  • The totalAmount parameter is set to 0, which is a requirement for order requests without a purchase amount.
  • Additionally, the payMethods object contains the single-use token (TOK_), which is necessary for the first payment to create the multi-use token (TOKC_).

POS used in the example does not have tokenization switched on.

Response Example for Order Without Purchase
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2",
    "orderId": "ORDER_ID",
    "payMethods": {
        "payMethod": {
            "card": {
                "number": "424242******4242",
                "expirationMonth": "12",
                "expirationYear": "2017"
            },
            "type": "CARD_TOKEN",
            "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
        }
    }
}

Highlighted in the response is the multi-use token (TOKC_), which can be used for future payments.

The above response assumes that there is a need for additional payer authentication using 3DS. For more details, please refer to the Handling 3DS section.

PayU provides payment status notifications by sending a notification to the address specified in the notifyUrl parameter contained in the order request body. For further information on handling and processing these notifications, you can refer to the Notifications section.

Retrieving tokens

For multi-use tokens (TOKC_), you should always retrieve them from PayU, instead of copying them from the order response. Retrieving tokens from PayU ensures that you have access to additional information such as token expiration date, token status, and more.

On this page