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 - invoking the widget or using the form to capture 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.

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. Steps:
  • (first payment) tokenize the card, you may use form or PayU widget, CVV/3DS are required, PayU sends back single-use token
  • (first payment) send Order with single-use token, 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 Front-end

Below description refers to pop-up widget. It is also possible to use inline widget, however it is important to note that the inline widget does not include the header which informs the user that the purchase will initiate recurring payments.
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".

Modifying front-end: Widget integration

1. Include the payment form presenting a payment button that defines a payment handling action. To do this, define a correct action parameter:
                    <form action="http://exampledomain.com/processOrder.php" method="post">
                        <button id="pay-button">Pay now</button>
                    </form>
                
2. Include the PayU widget bootstrap JS script. Define all the parameters according to POS configuration:
                    <script
                        src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
                        pay-button="#pay-button"
                        merchant-pos-id="145227"
                        shop-name="Shop name"
                        total-amount="9.99"
                        currency-code="PLN"
                        customer-language="en"
                        store-card="true"
                        recurring-payment="true"
                        customer-email="email@exampledomain.com"
                        sig="13e20d4e596fd2d4604f9c5296f83f072d3c134b0418f31653ccd06248314142">
                    </script>
                

3. Calculate the SIG parameter necessary to secure communication. Widget parameters and SIG algorithm: Widget parameters.

Modifying front end: Form integration

To capture card data via input fields in your website, follow the instructions in "Card data form" section.

2.2 Back-end

Back-end: integration based on tokenization

Order involving REST API is described in: Creating a new order. payMethods section is the extension to the standard OrderCreateRequest. Additionally you need to add "recurring" parameter as in below example.

Note: first transaction (order) has single use token (TOK_) and should include "recurring" parameter set to "FIRST" value.

Additionally, in case of response with WARNING_CONTINUE_3DS the payer must be redirected to card issuer website for authentication via 3D Secure.

Sample recurring payment order with reccuring flag.

                    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"
                              }
                          }
                      }'
                

Authentication methods are described in: Signing API calls parameters.

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

Back-end: integration based on plain card data

Order involving REST API is described in: Creating a new order. payMethods section is the extension to the standard OrderCreateRequest. Additionally you need to add "recurring" parameter as in below example.

Note: first transaction (Order) has "recurring" parameter set as "FIRST". Next Orders has "recurring" parameter set as "STANDARD". At least one payment "FIRST" for three: POS, card, extUserID, must have positive authorization, in order for next payments ("STANDARD") not to require CVV/3DS.

Additionally, in case of response with WARNING_CONTINUE_3DS the payer must be redirected to card issuer website for authentication via 3D Secure.

Sample recurring payment order with reccuring flag.

                    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":"[generateExtOrderId]",
                          "products":[
                             {
                                "name":"Laptop",
                                "unitPrice":"15000",
                                "quantity":"1"
                             }
                          ],
                          "buyer": {
                             "email": "john.doe@example.com",
                             "firstName": "John",
                             "lastName": "Doe",
                             "language": "en",
                             "extCustomerId": "1001"
                          },                          
                          "payMethods": {
                             "payMethod": {
                                "card": {
                                   "number":"5100052384536818",
                                   "expirationMonth":"11",
                                   "expirationYear":"2020",
                                   "cvv":"123"
                                }
                             }
                          }
                       }'
                

Authentication methods are described in: Signing API calls parameters.

POS used in the example is not configured at PayU side.

Responses to OrderCreateRequests:

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.

3 Retrieving tokens

Payment methods retrieve service description

Payment methods available for a given user should not be stored locally on merchant's server, but rather retrieved from PayU system for each payment. Retrieved are both the stored (tokenized) payments methods and generic payment methods. Using the retrieve service gives the following benefits:

- only payment methods available at the moment for the user are provided,

- payment methods stored for the user are always up to date and synchronized with user's active PayU Account.

In order to retrieve the payment methods, you need first to obtain OAuth access token.

Obtaining OAuth access token

To obtain OAuth access token, use the POST method to send request to endpoint /pl/standard/user/oauth/authorize.

apiary

Sample request:

curl -X POST https://secure.payu.com/pl/standard/user/oauth/authorize \
   -H "Cache-Control: no-cache" 
   -H "Content-Type: application/x-www-form-urlencoded" 
   -d 'grant_type=trusted_merchant&client_id=[provided by PayU]&client_secret=[provided by PayU]&email=[users email]&ext_customer_id=[Id of the customer used in merchant system]' 

                

ext_customer_id is unique customer identifier given by merchant, it is necessary in order to correctly generate the OAuth token.

Sample positive response (HTTP 200):
{
    "access_token": "4099c2c3-276f-488a-90e2-32620ac441dc",
    "token_type": "bearer",
    "expires_in": 43199,
    "grant_type": "trusted_merchant"
}
            

Retrieving payment methods

Insert the access token into header and use the GET method to send request to endpoint api/v2_1/paymethods .

apiary

Sample request:
curl -X GET https://secure.payu.com/api/v2_1/paymethods \
   -H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5" 
   -H "Cache-Control: no-cache" 

                

Sample postive response (HTTP 200). Description of fields are below the sample:

{  
   "cardTokens":[  
      {  
         "cardExpirationYear":"2017",
         "cardExpirationMonth":"12",
         "cardNumberMasked":"411111******1111",
         "cardBrand":"VISA",
         "value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
         "brandImageUrl":"http://static.payu.com/images/mobile/visa.png",
         "preferred":true,
         "status":"ACTIVE"
      },
      {  
         "cardExpirationYear":"2014",
         "cardExpirationMonth":"12",
         "cardNumberMasked":"424242******4242",
         "cardBrand":"VISA",
         "value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
         "brandImageUrl":"http://static.payu.com/images/mobile/visa.png",
         "preferred":false,
         "status":"EXPIRED"
      }
   ],
   "pexTokens":[  
      {  
         "accountNumber":"5311...7744",
         "payType":"mtex",
         "value":"TOKE_XPJ4UKJGHVRPMQPGB6X1JJQCUSS",
         "name":"account name set by the user",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pex_mbank.png",
         "preferred":false,
         "status":"ACTIVE"
      }
   ],
   "payByLinks":[  
      {  
         "value":"c",
         "name":"Płatność online kartą płatniczą",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
         "status":"ENABLED",
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"o",
         "name":"Pekao24Przelew",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_o.png",
         "status":"DISABLED",
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"ab",
         "name":"Płacę z Alior Bankiem",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_ab.png",
         "status":"TEMPORARY_DISABLED",
         "minAmount": 50,
         "maxAmount": 100000
      }
   ]
}          
            

cardTokens

This section will be returned empty if the user does not have any active or expired card tokens.
Parameter Description
cardExpirationYear YYYY
cardExpirationMonth MM
cardNumberMasked First 6 and last 4 digits of the PAN (card number).
cardBrand Possible values: 'VISA', 'MASTERCARD', 'MAESTRO'. Other card types are not supported, moreover 'MAESTRO' is not supported in recurring payments. VISA describes various Visa card brands, incl. Visa Electron. MASTERCARD also includes MasterCard Debit.
value Card token value.
brandImageUrl Link to card brand graphic on PayU server.
preferred true/false; it is set to 'true' for a cardToken or bankToken used most recently by the user.
status Possible values: 'ACTIVE' and 'EXPIRED'. 'EXPIRED' tokens may be skipped or presented to the user with a prompt to update or add a new card.If a token has been closed by the user or blocked for security reasons by PayU, it will not be provided in retrieve response.

pexTokens

This section will be returned empty if the user does not have any active pexTokens.

pexTokens relate to bank accounts tokenized through PayU|Express service.

Parameter Description
accountNumber First and last 4 digits of the bank account in the IBAN format.
payType Represents payType of the token.
name Name of the bank account set by the user.
value Bank token value.
brandImageUrl Link to bank logo graphic on PayU server.
preferred true/false; it is set to 'true' for a cardToken or bankToken used most recently by the user.
status Possible value: 'ACTIVE'. If a token has been closed by the user or blocked for security reasons by PayU, it will not be provided in retrieve response. If payType of the token is not configured on merchant's POS, the token will not be provided.

payByLinks

payByLinks are payment methods which always require redirection of the user. Therefore this section includes online bank transfers (pay-by-links), traditional bank transfer, installments and non-tokenized cards.
Parameter Description
value payType value. Available values are here.
name Name of payType set by PayU
brandImageUrl Link to payType logo graphic on PayU server.
status Possible values: 'ENABLED', 'DISABLED', 'TEMPORARY_DISABLED'.

4 Deleting tokens

Deleting a payment token

In case the buyer terminates the user account in your shop or chooses to remove the stored card from the user account, you need to delete the token.

In order to do it, simply send a DELETE message to https://secure.payu.com/api/v2_1/tokens/{tokenValue}

The header should contain a trusted.merchant OAuth token.

For example:
curl -X DELETE https://secure.payu.com/api/v2_1/tokens/TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE \
   -H "Authorization: Bearer cccbbc40-8113-443b-b4ea-c4b266272b22" 
   -H "Cache-Control: no-cache"