Token Payments documentation
Prerequisites
In order to have token payments in your web application, you need to be able to communicate with the PayU platform using HTTP POST.
The following communication protocols should already be in place:
- LiveUpdate or Automatic Live Update (ALU)
- LiveUpdate - HTML form POST to http://secure.payu.ro/order/lu.php, containing the necessary data to initiate a transaction. If the data is in the correct/expected format, the customer is redirected to our platform’s payment page, where he has to enter the credit card data.
- ALU - server to server HTTP POST request, containing customer's data.
- IPN - Instant Payment Notification, HTTP POST made by PayU to a merchant URL (configurable from the PayU cPanel for each vendor), containing all the relevant data about a transaction that has been successfully authorized and approved.
- IDN – Instant Delivery Notification, HTTP POST made by the merchant’s website to http://secure.payu.ro/order/idn.php - This is the normal merchant reaction that signals PayU to finalize (charge, debit) the customer’s account (at the previous step, the money are locked in the customer’s account).
- IRN – Instant Reverse / Refund Notification, HTTP POST made by the merchant’s website to http://secure.payu.ro/order/irn.php - This is an alternate merchant response to the IPN notification, in case the transaction is not to be finalized (for a variety of reasons – i.e. insufficient stock for products).
In addition to the existing protocols mentioned above, PayU provides a separate API for the automatic management of payments, described thoroughly below in this document.
Overview
Token payments are a new way of doing online transactions. Assigning a token to a new transaction will enable future automatic processing for the same client.
For first time customers the initial transaction should be marked as a token payment, offering a way to remember the customer and handle future automatic payments. For each such transaction the PayU system will respond with a specific token id (variable named IPN_CC_TOKEN). Using this unique identifier, merchants will be able to handle future transactions for the same client/credit card, regardless of the transaction amount.
Initializing Token Payments
In order to initiate a token, a transaction has to be created using LiveUpdate or ALU by the web store an paid.
The transaction data has to be formatted as described in the LiveUpdate implementation manual (see the Help/Technical Documentation sections in the PayU Control Panel for details and samples), or if you use ALU, see Automatic Live Update documentation.
Compared to the usual LiveUpdate fields, each Token post should have the following required variables: BILL_FNAME, BILL_LNAME, BILL_EMAIL, BILL_EMAIL, BILL_PHONE, BILL_ADDRESS, BILL_CITY, DELIVERY_FNAME, DELIVERY_LNAME, DELIVERY_PHONE, DELIVERY_ADDRESS, DELIVERY_CITY.
For the initial transaction, we have the extra parameter LU_ENABLE_TOKEN set to 1. This will mark the transaction as token transaction and will enable future automatic processing using the token API.
Receiving Payment Notifications
For each successfully authorized token payment, PayU sends an HTTP POST notification to the IPN URL set by the merchant in Control Panel, at the Account Management - Account Settings - IPN Settings section. The notification format is described in detail in the IPN Implementation manual (see the Help/Technical Documentation sections in the PayU Control Panel for details and samples).
In addition, the IPN will contain 3 parameters specific to token payments:
| VARIABLE | DETAILS |
| IPN_CC_TOKEN | the token number |
| IPN_CC_MASK | last 4 digits of the credit card used to make the payment |
| IPN_CC_EXP_DATE | expiry date of the credit card used to make the payment |
Token API
The dedicated API for token payments allows merchants to have full control over the way token payments happen. The features offered are:
- Create a new token payment
- Cancel an existing token payment
- Get information about an existing token payment
- Persist a token that has an expire date
Parameters
The merchant’s web application can communicate with the API using HTTP POST requests made at http://secure.payu.ro/order/tokens/. The parameters used by the API are the following:
| Variable | Details | Used for methods | Required |
| MERCHANT | PayU Merchant ID | ALL | YES |
| REF_NO | The value of IPN_CC_TOKEN received in IPN | ALL | YES |
| METHOD | One of the following methods, corresponding to the needed action: TOKEN_NEWSALE, TOKEN_CANCEL, TOKEN_GETINFO, TOKEN_PERSIST | ALL | YES |
| TIMESTAMP | Current time in UTC timezone (formatted as YYYYMMDDHHMMSS) | ALL | YES |
| SIGN | Security hash code, similar to the LiveUpdate code, parameters sorted alphabetically by key | ALL | YES |
| EXTERNAL_REF | Merchant Reference Number for the transaction | TOKEN_NEWSALE | YES |
| AMOUNT | New order amount, integer number or decimals separated by "." | TOKEN_NEWSALE | YES |
| CURRENCY | Product price currency | TOKEN_NEWSALE | YES |
| BILL_FNAME | Customer's first name | TOKEN_NEWSALE | YES |
| BILL_LNAME | Customer's last name | TOKEN_NEWSALE | YES |
| BILL_EMAIL | Customer's email address | TOKEN_NEWSALE | YES |
| BILL_PHONE | Phone number | TOKEN_NEWSALE | YES |
| BILL_ADDRESS | Customer's/Company's address | TOKEN_NEWSALE | YES |
| BILL_CITY | City | TOKEN_NEWSALE | YES |
| DELIVERY_FNAME | Customer's first name | TOKEN_NEWSALE | YES |
| DELIVERY_LNAME | Customer's last name | TOKEN_NEWSALE | YES |
| DELIVERY_PHONE | Phone number | TOKEN_NEWSALE | YES |
| DELIVERY_ADDRESS | Customer's/Company's address | TOKEN_NEWSALE | YES |
| DELIVERY_CITY | City | TOKEN_NEWSALE | YES |
| CANCEL_REASON | Reason for cancelling an order | TOKEN_CANCEL | YES |
For each API call, the system will return a JSON formatted response that contains two variables:code and message. Below you will find a list of all the possible codes and their corresponding messages. A sample response might look like the one below:
{
"code": 1500,
"message": "This token is invalid"
}
Error codes
| CODE | MESSAGE | COMMENTS |
| 0 | Operation successful | Operation completed without any problems |
| 300 | Invalid transaction | The REF_NO specified is not a valid transaction |
| 400 | Unknown method | The METHOD variable needs to have one of the following values:TOKEN_NEWSALE, TOKEN_CANCEL, TOKEN_GETINFO |
| 500 | Request expired | The value of TIMESTAMP differs too much from the current time. Check your system clock and ensure that TIMESTAMP is in UTC timezone. |
| 600 | Invalid merchant | Make sure that your MerchantID is the same one found in yourPayU Control Panel |
| 601 | Not sufficient funds | The credit card used has insufficient funds available. |
| 602 | Expired card | The credit card used is expired |
| 603 | Terminal is locked, please try again | Temporary processing error. Retrying after a few minutes should work. |
| 604 | Invalid Card | The credit card used is invalid. |
| 605 | Internal error | General system error. Retrying after a few minutes should work but if it’s not please contact our support team. |
| 606 | Transaction declined | Invalid Transaction error specified by the credit card company. |
| 607 | Waiting for bank authorization | The bank is still processing the transaction, check order status using IOS webservice. |
| 1200 | Invalid signature | There is a problem with your SIGN variable. Please check your code. |
| 1300 | Operation not permitted | The REF_NO you have specified is not valid. Please check the value. |
| 1500 | This token is invalid | Invalid Token command for the REF_NO you have specified. |
| 1600 | Invalid External Ref No | |
| 1900 | Invalid amount type | The AMOUNT value should be a positive number, either integer or a float. |
| 2000 | Maximum amount exedeed | You have exceeded the maximum amount limit for your terminal.Please try again in a few minutes. |
| 2100 | Invalid currency | CURRENCY variable has an unsupported or invalid value |
| 2200 | This Token is disabled | Operation was not performed because the token is disabled |
| 2401 | BILL_LNAME field is mandatory | |
| 2402 | BILL_FNAME field is mandatory | |
| 2403 | BILL_EMAIL field is mandatory | |
| 2404 | BILL_EMAIL field is not a valid e-mail | |
| 2405 | BILL_PHONE field is mandatory | |
| 2406 | BILL_ADDRESS field is mandatory | |
| 2407 | BILL_CITY field is mandatory | |
| 2408 | DELIVERY_LNAME field is mandatory | |
| 2409 | DELIVERY_FNAME field is mandatory | |
| 2410 | DELIVERY_PHONE field is mandatory | |
| 2411 | DELIVERY_ADDRESS field is mandatory | |
| 2412 | DELIVERY_CITY field is mandatory | |
| 2413 | DELIVERY_EMAIL field is not a valid e-mail | |
| 2414 | BILL_COUNTRYCODE field is not a valid ISO 3166-1 alpha-2country code | |
| 2415 | DELIVERY_COUNTRYCODE field is not a valid ISO 3166-1 alpha-2country code | |
| 3000 | Invalid number of installments selected | Please check the following: 1. token payments with installments is enabled for your merchant account in the PayU platform; 2. the value of the SELECTED_INSTALLMENTS_NUMBER variable must be positive number, greater than 1; 3. for one-time payments, SELECTED_INSTALLMENTS_NUMBER should not be sent. |
| 3100 | Token is already persistent | |
| 3101 | Token has expired | |
| 3200 | Token usage on marketplace orders is restricted on this protocol | |
| 4000 | Card Scheme not supported | Please check if the card scheme used to make the original transaction is still enabled for that merchant. |
Examples
Initial Payment Request
The initial payment request is a normal request sent using the Live Update communication protocol. The sample form below is identical to the one used for the Live Update payments and has just one extra variable (LU_ENABLE_TOKEN) used to mark the transaction as a token transaction.
This form is using the Live Update URL: http://secure.payu.ro/order/lu.php.
The response generated by the form above will be extremely similar to the one presented in the LiveUpdate manual, with the only difference being the 3 new variables presented below.
| VARIABLE | VALUE (EXAMPLE) |
| IPN_CC_TOKEN | 6121191 |
| IPN_CC_MASK | xxxx-xxxx-xxxx-1111 |
| IPN_CC_EXP_DATE | 2012-07-18 |
New sale using token
Using a token obtained from the IPN you received after a LiveUpdate made as described in the Initializing Token Payments and Receiving Payment Notifications sections above, you can make a new sale.
The METHOD variable should be set to TOKEN_ NEWSALE. The AMOUNT and CURRENCY variables are mandatory for this type of request. Please check the Token API section above for a list of all the variables that should be posted.
The URL for handling token API actions is http://secure.payu.ro/order/tokens/.
| VARIABLE | VALUE (EXAMPLE) |
| AMOUNT | 1 |
| CURRENCY | RON |
| BILL_ADDRESS | address 1 |
| BILL_CITY | Iasi |
| BILL_EMAIL | john@doe.com |
| BILL_FNAME | John |
| BILL_LNAME | Doe |
| BILL_PHONE | 0243236298 |
| DELIVERY_ADDRESS | address 2 |
| DELIVERY_CITY | Suceava |
| DELIVERY_EMAIL | john@doe.com |
| DELIVERY_FNAME | John |
| DELIVERY_LNAME | Doe |
| DELIVERY_PHONE | 0243236298 |
| EXTERNAL_REF | 25787sa1 |
| MERCHANT | COMPNAME |
| METHOD | TOKEN_NEWSALE |
| REF_NO | 6121191 |
| TIMESTAMP | 20120625150756 |
| SIGN | 2542b849191cea1061203c96d99c5189 |
The response generated by the data above should look like the one below:
{
"code": "0",
"message": "Operation successful",
"tran_ref_no": "6170429",
"amount": 200,
"currency": "RON"
}
Read Token Payment Details
You can request information about any previous token transaction using TOKEN_GETINFO as the value for the METHOD variable.
The REF_NO variable should contain the reference number for the original transaction. Please check the Token API section above for a list of all the variables that should be posted.
The URL for handling token API actions is http://secure.payu.ro/order/tokens/.
| VARIABLE | VALUE (EXAMPLE) |
| TIMESTAMP | 20130506132263 |
| METHOD | TOKEN_GETINFO |
| MERCHANT | COMPNAME |
| REF_NO | 6121191 |
| SIGN | 2542b849191cea1061203c96d99c5189 |
The response generated by the form above should look like the data below.
{
"TOKEN": "6121191",
"TOKEN_STATUS": "ACTIVE",
"EXPIRATION_DATE": "2013-07-18",
"HISTORY": {
"1": {
"TOKEN_DATE": "2012-07-18 14:21:58",
"REF_NO": "6121191",
"AMOUNT": "2",
"CURRENCY": "RON"
},
"2": {
"TOKEN_DATE": "2012-07-18 14:30:01",
"REF_NO": "6170429",
"AMOUNT": "2",
"CURRENCY": "RON"
}
}
}
A complete history is provided for each token transaction. For each past transaction the date, amount, currency and the transaction ID will be displayed.
Cancel a Token Payment
Any previous token transaction can be cancelled by specifying TOKEN_CANCEL for the METHOD variable. The REF_NO variable should contain the reference number for the original transaction that should be cancelled. A CANCEL_REASON variable is optional and can be used to specify a reason for cancelling the transaction. Please check the Token API section above for a list of all the variables that should be posted.
The URL for handling token API actions is http://secure.payu.ro/order/tokens/.
| VARIABLE | VALUE (EXAMPLE) |
| METHOD | TOKEN_CANCEL |
| TIMESTAMP | 20130506132263 |
| MERCHANT | COMPNAME |
| REF_NO | 6121191 |
| SIGN | 2542b849191cea1061203c96d99c5189 |
The response generated by the form above should look like the data below.
{
"code": 0,
"message": "Operation successful"
}
Persist a Token
Any previous token transaction that had an expire date specified, can be persisted by specifying TOKEN_PERSIST for the METHOD variable. The REF_NO variable should contain the reference number for the original transaction. Please check the Token API section above for a list of all the variables that should be posted.
The URL for handling token API actions is http://secure.payu.ro/order/tokens/.
| VARIABLE | VALUE (EXAMPLE) |
| METHOD | TOKEN_PERSIST |
| TIMESTAMP | 20130506132263 |
| MERCHANT | COMPNAME |
| REF_NO | 6121191 |
| SIGN | 2542b849191cea1061203c96d99c5189 |
The response generated by the form above should look like the data below.
{
"code": 0,
"message": "Operation successful"
}
Resources
PHP implementation
View or download the PHP class used by the example below.
/**
* Include library
*/
require __DIR__ . '/src/TokenService.php';
/**
* token code
*/
$code = '11930179';
/**
* Initialize the service object with the URL, merchant code and IPN key
*/
$token = new \PayU\MerchantClientApi\TokenService('http://secure.payu.ro/order/tokens/', 'OPU_TEST', 'SECRET_KEY');
/**
* call TOKEN_GETINFO for the token
*/
$info = $token->getInfo($code);
var_dump($info);
/*
the displayed result would be similar to:
array (size=4)
'TOKEN' => string '11930179' (length=8)
'TOKEN_STATUS' => string 'ACTIVE' (length=6)
'EXPIRATION_DATE' => string '2015-03-31' (length=10)
'HISTORY' =>
array (size=1)
1 =>
array (size=4)
'TOKEN_DATE' => string '2014-04-01 17:49:52' (length=19)
'REF_NO' => string '11930179' (length=8)
'AMOUNT' => string '2' (length=1)
'CURRENCY' => string 'RON' (length=3)
*/
/**
* call TOKEN_CANCEL for the token
*/
$cancel = $token->cancel($code, 'not needed anymore');
var_dump($cancel);
/*
the displayed result would be similar to:
array (size=2)
'code' => int 0
'message' => string 'Operation successful' (length=20)
*/
$additionalData = array(
'BILL_FNAME' => 'Smith',
'BILL_LNAME' => 'John',
'BILL_EMAIL' => 'john.smith@example.com',
'BILL_PHONE' => '0040210000000',
'BILL_ADDRESS' => '1337 Square Place',
'BILL_CITY' => 'Bucharest',
'DELIVERY_FNAME' => 'Smith',
'DELIVERY_LNAME' => 'Jane',
'DELIVERY_EMAIL' => 'jane.smith@example.com',
'DELIVERY_PHONE' => '0040210000001',
'DELIVERY_ADDRESS' => '1337 Square Place',
'DELIVERY_CITY' => 'Bucharest',
);
/**
* call TOKEN_NEWSALE for the token
*/
$new = $token->newSale($code, 1, 'RON', 'abc1234', $additionalData);
var_dump($new);
/*
the displayed result would be similar to:
array (size=2)
'code' => int 601
'message' => string 'Not sufficient funds' (length=20)
*/
/**
* call TOKEN_PERSIST for token
*
*/
$persist = $token->persist($code);
var_dump($persist);
/*
the displayed result would be similar to:
array (size=2)
'code' => int 0
'message' => string 'Operation successful' (length=20)
*/