Recurring payments

1 Introduction

Recurring payments service is based on a transparent integration type which allows the Merchant to accept card payments without redirecting users to a page hosted by the payment service provider. This integration type retains the security level and minimizes the PCI DSS compliance effort. It is also meant to give the Merchant more flexibility and increase conversion rates through better control over the payment process.

A payment flow is based on two steps - capturing card credentials in a secure way (front-end process) and then charging the card by creating a payment transaction (back-end process). Card credentials are returned in the form of a token and a masked card number, therefore the Merchant never receives full card details. Back-end processing is based on the OpenPayU protocol and integration is made easier through available SDKs.

Recurring payments are processed with multi-use tokens. All transactions, except of the first one, are not initiated by the cardholder. They can be performed by a scheduler on the Merchant's side at any time, even at night. Therefore, neither 3DS nor CVV authentication is required.

PayU configuration

Recurring payments service requires configuration operations to be performed at PayU side. Therefore, before starting the integration process, please contact PayU via your Account Manager or by our contact form.

On the Sandbox environment, REST API points of sale will be configured automatically, testing this functionality will be possible within 90 minutes of creation.

Security requirements and recommendations

Before integrating the service, please take a look at the requirements and recommendations prepared by our security experts. It will help you protect yourself against frauds.

2 Service integration

Recurring payments service is based on tokenization.

Detailed descriptions of creating, charging, retrieving and deleting tokens can be found on card tokenization page.
Steps:
  • (first payment) tokenize the card, you may use PayU widget or (preferably) Secure Form; CVV/3DS are required, PayU sends back single-use token;
  • (first payment) send Order with token type MULTI (tokenize(type?) method), PayU sends back multi-use token;
  • (second and next payments) send Order with multi-use token, CVV/3DS are not required.

Transparent payment with a single-use token (first payment):

Transparent payment with a multi-use token (second and next payments):

2.1 Capturing card credentials

Please remember to display all the necessary information to the payer and the approval for recurring payments as outlined in "Requirements and recommendations relating to Recurring Payments".
For capturing card credentials please use Secure Form.

2.2 Back-end

Back-end: integration based on tokenization

Standard OrderCreateRequest should be extended by payMethods.payMethod section and recurring parameter, which indicates the type of recurring payment:

  • FIRST - for first payment recurring payment,
  • STANDARD - for subsequent recurring payments.
Detailed descriptions of recurring parameter values can be found in JSON properties section.

Additionally, because each initial payment requires 3DS authentication, it is suggested to include data required by 3DS, especially threeDsAuthentication.recurring. More information can be found in separate chapter on 3DS.

Examples of OrderCreateRequests for recurring

Sample of OrderCreateRequest for FIRST recurring payment:

                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",
                    "recurring": "FIRST",
                    "description":"Laptop",
                    "currencyCode":"PLN",
                    "totalAmount":"15000",
                    "extOrderId":"n7kln2ipw5q1neabmjabc123",
                    "products":[
                        {
                            "name":"Laptop",
                            "unitPrice":"15000",
                            "quantity":"1"
                        }
                    ],
                    "buyer": {
                        "email": "john.doe@example.com",
                        "firstName": "John",
                        "lastName": "Doe",
                        "language": "en"
                    },                         
                    "payMethods": {
                        "payMethod": {
                            "value": "TOK_1JQMSW8MILUV69k0TVFZV593Riw2",
                            "type": "CARD_TOKEN"
                        }
                    },
                    "threeDsAuthentication": {
                        "recurring": {
                            "frequency": "30",
                            "expiry": "2025-12-31T00:00:00Z"
                        }
                    }
                }'
                
            

Sample of OrderCreateRequest for subsequent recurring payments:

                    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",
                          "recurring": "STANDARD",
                          "description":"Laptop",
                          "currencyCode":"PLN",
                          "totalAmount":"15000",
                          "extOrderId":"[generateExtOrderId]",
                          "products":[
                             {
                                "name":"Laptop",
                                "unitPrice":"15000",
                                "quantity":"1"
                             }
                          ],
                          "buyer": {
                              "email": "john.doe@example.com",
                              "firstName": "John",
                              "lastName": "Doe",
                              "language": "en"
                          },                          
                          "payMethods": {
                              "payMethod": {
                                   "value": "TOKC_1IHRPT6HKSSS3H62K0GS8pElP862",
                                   "type": "CARD_TOKEN"
                              }
                          },
                        "threeDsAuthentication": {
                            "recurring": {
                                "frequency": "30",
                                "expiry": "2025-12-31T00:00:00Z"
                            }
                        }
                      }'
                

Authentication methods are described in: Signing API calls parameters.

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

Responses to OrderCreateRequests in recurring:

Example for SUCCESS response with multi-use token (first Order):
{
     "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"
       }
}
                
Example for WARNING_CONTINUE_3DS response (first Order):
{
     "orderId": "ORDER_ID",
     "status": {
         "statusCode": "WARNING_CONTINUE_3DS",
         "severity": "WARNING"
     },
     "redirectUri": "{redirectUri}"
}
                
Example for WARNING_CONTINUE_CVV response (first Order):
{
     "orderId": "ORDER_ID",
     "status": {
         "statusCode": "WARNING_CONTINUE_CVV",
         "severity": "WARNING"
     },
     "redirectUri": "{redirectUri}"
}
                

PayU informs the Shop about the payment by submitting a notification to the address provided in the order in the notifyUrl parameter. To learn more about notifications, read Notifications.

Back-end: integration based on plain card data

Full description for creating order with plain card data can be found here.