Token API v2 documentation

Last update: April 28th, 2015

Summary

  1. Introduction
  2. Prerequisites
  3. Authentication
  4. Web Service Endpoints
  5. Requests quota

1. Introduction

Token payments are an alternate way of doing online transactions. Assigning a token to a new transaction will enable future automatic processing for the same client.

An initial transaction can be used to create a token, offering a way to remember the customer and handle future automatic payments. Using this unique identifier, merchants will be able to handle future transactions for the same client/credit card, regardless of the transaction amount.

2. Prerequisites

You should confirm with PayU that all necessary settings and configurations are correct on your merchant account and terminal.

You should be able to process orders through PayU services using either the LU or ALU protocol.

3. Authentication

To authenticate your request you will need to provide:


Authentication can be done in two ways

1. Header authentication
To use header authentication you will need to send two headers with your request. 
            Authorization: SIGNATURE [Vendor Code]:[Signature Hash]
            X-timestamp: [UNIX standard timestamp]

Example: 
            Authorization: SIGNATURE VENDOR_CODE:9aff1d0576bda27ba227edbfd3c539e9cbe87a1c360f553e853c792ef8a90198
            X-timestamp: 1421425261
2. Request parameter authentication
This implies that instead of sending headers you can simply send two additional parameters on the query string (besides the one described above)
  • merchant = your vendor code
  • timestamp = current Unix time
  • signature = the signature hash
Example request: 
            https://secure.payu.ro/order/token/v2/merchantToken/44781d7c201e33aedefd5c0ca9288634?merchant=CC921&timestamp=1428665398&signature=7287936853ac67d1f2aa15a0bcf3517e74cf0a80e652a8d883d75c1233c09c6e
 
NOTE: Timestamp format is Unix time. More info can be found here.

Signature calculation

For security reason, each HTTP request must carry a unique signature. The signature is calculated using data from all parameters sent in the HTTP (excepting "signature", and including the authentication parameters if not sent as headers), the Merchant's secret key and the HMAC method with SHA256 algorithm to encrypt data.

For example, let's consider that a Merchant (AMA_TEST with secret key SECRET_KEY) sends the HTTP request to the API containing the following parameters and values: 
        "merchant" => "AMA_TEST"
        "cancelReason" => "Order cancelled"
        "timestamp" => "1418996102156"

Step 1: Sort the parameters (excepting the "timestamp" parameter) sent in the HTTP request alphabetically by parameter name

NOTE Parameters should be sorted by their name (key), NOT their values.
Using the example, this is the order of significant parameters after the sort: 
        "cancelReason" => "Order cancelled"
        "merchant" => "AMA_TEST"

Step 2: Compose the source string by concatenating the values of each HTTP GET parameter above, and append "timestamp" at the end.

Now, based on this, the entire source string for the values of the sorted parameters at Step 1 will be:

Order cancelledAMA_TEST1418996102156

Step 3: Calculate the signature using HMAC with SHA256 as a hashing algorithm applied to the source string

For the calculated source string, the signature value will be:

        4952840ec9e2dbee7e69db9f927ee83800f527cfdbd11636ea40aee53fa90d48

Step 4: Add the calculated signature value to the HTTP request before sending it to PayU

See Authentication for more information on how to send authentication credentials

PayU will also calculate the signature on its side using the data received, and it will match it against the signature sent by the Merchant.
 

4. Web Service Endpoints

The Token Web Service is a REST-ful web service.

The query process requires the Merchant to create a request using the HTTPs protocol, at the following URL: https://secure.payu.ro /order/token/v2/merchantToken/.

Create token

Description:
Creates a token from an original sale.
API endpoint:
https://secure.payu.ro/order/token/v2/merchantToken
Parameters:
Field Required Type Description
merchant NO* string Merchant code
refNo YES Integer Reference number of the original order that will be used to create the reusable token.

Note: There is a certain expiration time set on the terminal that only alows you to create a token a certain amount of time after the original order was created.
timestamp NO* string Current Unix time
signature NO* string Signature hash string
*Parameters are not required if authentication is made using HTTP headers.
Method:
POST
Request:
Request example with request authentication parameters: 
Array
(
    [merchant] => CC921
    [refNo] => 12039391
    [timestamp] => 1428045257
    [signature] => c211b9fc82bc10fb9d104ba3c756bbb0e61eddb3bd26303b9e4109f271c7059e
)
Returns:

Returns the token hash string generated for the given order (refNo).

Response example: 
{
   "meta":{
      "status":{
         "code":0,
         "message":"success"
      },
      "response":{
         "httpCode":200,
         "httpMessage":"200 OK"
      },
      "version":"v2"
   },
   "response":{
      "token":"b7e5d8649c9e2e75726b59c56c29e91d",
      "cardUniqueIdentifier":"e9fc5107db302fa8373efbedf55a1614b5a3125ee59fe274e7dc802930d68f6d"
   }
}

If the order was created with FX, then the response will look like bellow:

Response example: 
{
   "meta":{
      ...
   },
   "response":{
      "token":"b7e5d8649c9e2e75726b59c56c29e91d",
      "fxCurrency": "EUR",
      "cardUniqueIdentifier":"e9fc5107db302fa8373efbedf55a1614b5a3125ee59fe274e7dc802930d68f6d"
   }
}
Errors:
400 Bad Request - The order with reference number "[refNo]" expired at '[Date]' and can no longer be used to create a token. Expiration timeout on terminal is set at 'n' seconds
400 Bad Request - The order with reference number "[refNo]" is not a valid order for this merchant.
400 Bad Request - Invalid value for 'refNo'. '[string]' given. Expecting an integer id value.
400 Bad Request - No order with reference number: [refNo]
401 Unauthorized - See Authentication
500 Internal Server Error - please contact us if this error persists.

Error response example: 
{
   "meta":{
      "status":{
         "code":400,
         "message":"No order with reference number: 120393911"
      },
      "response":{
         "httpCode":400,
         "httpMessage":"400 Bad Request"
      },
      "version":"v2"
   },
   "error":{
      "code":400,
      "message":"No order with reference number: 120393911"
   }
}

Get token information

Description:
Get information for a specific token (:token).
API endpoint:
https://secure.payu.ro/order/token/v2/merchantToken/:token
Method:
GET
Parameters:
Field Required Type Description
merchant NO* string Merchant code
timestamp NO* string Current Unix time
signature NO* string Signature hash string
*Parameters are not required if authentication is made using HTTP headers.
Request:
Request example with request authentication parameters: 
    https://secure.payu.ro/order/token/v2/merchantToken/b7e5d8649c9e2e75726b59c56c29e91d?merchant=CC921&timestamp=1428046996&signature=34b084915a67bf2b54eff4a29e677c2718e26a6632496bfb4c5880a5d938b96e
Response:

Returns token information for a token.

Response example: 
{
   "meta":{
      "status":{
         "code":0,
         "message":"success"
      },
      "response":{
         "httpCode":200,
         "httpMessage":"200 OK"
      },
      "version":"v2"
   },
   "token":{
      "tokenStatus":"ACTIVE",
      "tokenExpirationDate":"2016-04-03",
      "cardNumberMask":"4111-xxxx-xxxx-1111",
      "cardExpirationDate":"2029-01-31",
      "cardHolderName":"test",
      "cardType":"Visa",
      "cardBank":"YAPI KREDI BANKASI",
      "cardProgramName":"Axess"
   }
}
Errors:
400 Bad Request - Invalid token hash "b7e5d8649c9e2e75726b59c56c29e91d1"
400 Bad Request - The token "b7e5d8649c9e2e75726b59c56c29e91d1" is not valid for this merchant.
401 Unauthorized - See Authentication
500 Internal Server Error - please contact us if this error persists.

Error response example: 
{
   "meta":{
      "status":{
         "code":400,
         "message":"Invalid token hash \"b7e5d8649c9e2e75726b59c56c29e91d1\""
      },
      "response":{
         "httpCode":400,
         "httpMessage":"400 Bad Request"
      },
      "version":"v2"
   },
   "error":{
      "code":400,
      "message":"Invalid token hash \"b7e5d8649c9e2e75726b59c56c29e91d1\""
   }
}
Tips:
Normally, one merchant can request token info only for a token created by that merchant.
If sharing tokens is enabled for two (or more) merchants, one merchant can request to get token info for a token created by another merchant

Get multiple token information

Description:
Get information for multiple tokens.
API endpoint:
https://secure.payu.ro/order/token/v2/merchantToken
Method:
GET
Parameters:
Field Required Type Description
tokens[] YES Array of strings List of tokens to get info for
merchant NO* string Merchant code
timestamp NO* string Current Unix time
signature NO* string Signature hash string
*Parameters are not required if authentication is made using HTTP headers.
Request:
Request example with request authentication parameters: 
    https://secure.payu.ro/order/token/v2/merchantToken?tokens[0]=b7e5d8649c9e2e75726b59c56c29e91d&tokens[1]=1c82fc76364cb1eafa04f7225b16b1ae&merchant=CC921&timestamp=1428047425&signature=8a018658dc374e31ac9a6819f4e74810c8ce3e19d4960f21a8ed6fcd62825b4e
Response:

Returns token information for multiple tokens.

Response example: 
{
   "meta":{
      "status":{
         "code":0,
         "message":"success"
      },
      "response":{
         "httpCode":200,
         "httpMessage":"200 OK"
      },
      "version":"v2"
   },
   "tokens":{
      "b7e5d8649c9e2e75726b59c56c29e91d":{
         "tokenStatus":"ACTIVE",
         "tokenExpirationDate":"2016-04-03",
         "cardNumberMask":"4111-xxxx-xxxx-1111",
         "cardExpirationDate":"2029-01-31",
         "cardHolderName":"test",
         "cardType":"Visa",
         "cardBank":"YAPI KREDI BANKASI",
         "cardProgramName":"Axess"
      },
      "1c82fc76364cb1eafa04f7225b16b1ae":{
         "tokenStatus":"ACTIVE",
         "tokenExpirationDate":"2016-04-03",
         "cardNumberMask":"4242-xxxx-xxxx-4242",
         "cardExpirationDate":"2018-01-31",
         "cardHolderName":"test",
         "cardType":"Visa",
         "cardBank":"TURKIYE GARANTI BANKASI, A.S.",
         "cardProgramName":"Bonus"
      }
   }
}
Errors:
400 Bad Request - Invalid token hash "1c82fc76364cb1eafa04f7225b16b1ae1"
400 Bad Request - The token "1c82fc76364cb1eafa04f7225b16b1ae1" is not valid for this merchant.
401 Unauthorized - See Authentication
500 Internal Server Error - please contact us if this error persists.

Error response example: 
{
   "meta":{
      "status":{
         "code":400,
         "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
      },
      "response":{
         "httpCode":400,
         "httpMessage":"400 Bad Request"
      },
      "version":"v2"
   },
   "error":{
      "code":400,
      "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
   }
}

Gets order history for a specific token

Description:
Gets order history for a specific token (:token).
API endpoint:
https://secure.payu.ro/order/token/v2/merchantToken/:token/history
Method:
GET
Parameters:
Field Required Type Description
merchant NO* string Merchant code
timestamp NO* string Current Unix time
signature NO* string Signature hash string
*Parameters are not required if authentication is made using HTTP headers.
Request:
Request example with request authentication parameters: 
https://secure.payu.ro/order/token/v2/merchantToken/1c82fc76364cb1eafa04f7225b16b1ae/history?merchant=CC921&timestamp=1428047880&signature=e6fc15bb26bfc3505fca5739993433616626a45af5f5ff33c69d80ce283a3fcf
Response:

Returns the original sale used to create the token as well as a list of orders created using the token.

Response example: 
{
   "meta":{
      "status":{
         "code":0,
         "message":"success"
      },
      "response":{
         "httpCode":200,
         "httpMessage":"200 OK"
      },
      "version":"v2"
   },
   "info":{
      "originalSale":{
         "26744030":{
            "refNo":"11748318",
            "amount":"70",
            "currency":"RON"
         }
      },
      "history":[

      ]
   }
}
Errors:
400 Bad Request - Invalid token hash "1c82fc76364cb1eafa04f7225b16b1ae1"
400 Bad Request - The token "1c82fc76364cb1eafa04f7225b16b1ae1" is not valid for this merchant.
401 Unauthorized - See Authentication
500 Internal Server Error - please contact us if this error persists.

Error response example: 
{
   "meta":{
      "status":{
         "code":400,
         "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
      },
      "response":{
         "httpCode":400,
         "httpMessage":"400 Bad Request"
      },
      "version":"v2"
   },
   "error":{
      "code":400,
      "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
   }
}

Cancels a specific token

Description:
Cancels a specific token (:token).
API endpoint:
https://secure.payu.ro/order/token/v2/merchantToken/:token
Method:
DELETE
Parameters:
Field Required Type Description
cancelReason NO* string optional cancel reason
merchant NO* string Merchant code
timestamp NO* string Current Unix time
signature NO* string Signature hash string
*Parameters are not required if authentication is made using HTTP headers.
Request:
Request example with request authentication parameters: 
https://secure.payu.ro/order/token/v2/merchantToken/1c82fc76364cb1eafa04f7225b16b1ae?merchant=CC921&timestamp=1428048194&signature=166e48150ef4ab2856b7f3ebfcefca89d1c4ed0f45db0b740c349271063abd7d&cancelReason=Client+requested+token+cancelation
Response:

Cancels a token. Once cancelled it can not be used to make orders anymore.

On success HTTP code 204 is returned with no body
Errors:
400 Bad Request - Invalid token hash "1c82fc76364cb1eafa04f7225b16b1ae1"
400 Bad Request - The token "1c82fc76364cb1eafa04f7225b16b1ae1" is not valid for this merchant.
401 Unauthorized - See Authentication
500 Internal Server Error - please contact us if this error persists.

Error response example: 
{
   "meta":{
      "status":{
         "code":400,
         "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
      },
      "response":{
         "httpCode":400,
         "httpMessage":"400 Bad Request"
      },
      "version":"v2"
   },
   "error":{
      "code":400,
      "message":"Invalid token hash \"1c82fc76364cb1eafa04f7225b16b1ae1\""
   }
}

5. Requests quota

This API has the following quotas for request methods:

Method Requests quota over 60 seconds
GET 1000
POST 500
DELETE 500

More information about API limits can be found here.