FX API v1 documentation

Last update: June 18th, 2018

Summary

1. Overview
2. Prerequisites
3. Available endpoints
• Get all FX exchange rates
4. Authentication
5. cURL example
6. Try it yourself!

1. Overview

The FX feature allows for completing payments by using different currencies than the order's currency, converting the total price to buyer's own card currency.

The FX API gives you access to FX-related information, such as exchange rates values.

2. Prerequisites

3. Available endpoints

This API is a RESTful web service. All requests must be authenticated.

Get all FX exchange rates

Retrieves all the rates reported to the baseCurrency currency. The FX rates are available until the expiration date (therefore we recommend you to store or cache the API result). If you receive an error on the authorization step when making your payment, concerning that FX rates are invalid, you should retrieve these again.

URL Schema GET https://secure.payu.ro/api/fx/rates/{baseCurrency}?merchant={merchant}&signature={signature}&dateTime={dateTime} Parameters

Field	Sending as	Description
baseCurrency	URI parameter	Currency used for exchanging to other currencies
merchant	Query parameter	Your merchant identifier, available in Control Panel (Account Management / Account Settings)
dateTime	Query parameter	The current date time according to ISO 8601 format (e.g. 2018-05-24T11:28:13+00:00)
signature	Query parameter	See the "Authentication" section

Response

Here's an example of successful response:

        {
          "meta": {
            "code": 200,
            "message": "success"
          },
          "baseCurrency": "RON",
          "rates": {
            "PLN": 0.9329,
            "EUR": 0.2161,
            ...
          },
          "expiresAt": "2018-05-24T11:28:13+00:00"
        }
    

The error response will always have the following structure:

        {
          "meta": {
            "code": "<the HTTP code>",
            "message": "<the explanation message for this HTTP code>"
          }
        }
    

Based on code meta value, which represents also the HTTP response code for the request, the errors (message meta value) could be:

Meta code	Meta message / description
204	"There are no rates available now for {baseCurrency}" - there are no rates for the provided base currency.
400	"A required configuration is missing for this account" - the service wasn't completely configured for your account; in this case, please contact our team.
	"The provided base currency is invalid: {baseCurrency}" - the provided currency is invalid
401	"Missing datetime parameter." - the "dateTime" parameter is missing
	"Request expired. Please make a new request." - request has expired, check the value of "dateTime" parameter
	"Access denied. "merchant" not set." - the "merchant" parameter is missing
	"Access denied. "signature" not set." - the "signature" parameter is missing
	"Access denied. Unauthorized access." - the "signature" parameter value was computed wrong or the "merchant" parameter has a wrong value
403	"The service is unavailable" - the service is not available for your region
	"The service is unavailable or the configuration is invalid" - the service wasn't completely configured for your account; in this case, please contact our team.
	"The service is not available for this configuration" - same as above situation

Here's an example of an error response:

        {
          "meta": {
            "code": "401",
            "message": "Missing datetime parameter."
          }
        }
    

4. Authentication

To access any of the API's endpoints, you will have to authenticate your requests by computing a signature parameter.

Signature calculation

The signature is calculated using data from all HTTP parameters sent in the HTTP request (whether they are GET or POST).

Let's take the following request example, where we consider the merchant identifier as MERCHANT and the account's secret key as SECRET_KEY:

        https://secure.payu.ro/api/fx/rates/EUR?merchant=MERCHANT&dateTime=2018-05-24T11%3A28%3A13%2B00%3A00
    

We want to add the signature GET parameter.

Step 1: Sort the HTTP parameters sent in the HTTP request alphabetically by their name:

        dateTime
        merchant
    

Step 2: Compose the source string by concatenating the values of each HTTP parameters above, prefixed with their length (as strings):

The length of "2018-05-24T11:28:13+00:00" is 25, while the length for "MERCHANT" is 8. Therefore, we have the following source string:

        252018-05-24T11:28:13+00:008MERCHANT
    

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

Use your secret key as hashing key.

        signature = HMAC_SHA256("252018-05-24T11:28:13+00:008MERCHANT", "SECRET_KEY") = 91a1affb1f0a1d3c60330beb02f66770e4dd499b02934b669864c5d4a906908c
    

Step 4: Add it to the request:

        https://secure.payu.ro/api/fx/rates/EUR?merchant=MERCHANT&dateTime=2018-05-24T11%3A28%3A13%2B00%3A00&signature=91a1affb1f0a1d3c60330beb02f66770e4dd499b02934b669864c5d4a906908c
    

5. cURL example

        curl -H "Accept: application/json" -H "Content-Type: application/json" https://secure.payu.ro/api/fx/rates/EUR?merchant=MERCHANT&dateTime=2018-05-24T11%3A28%3A13%2B00%3A00&signature=91a1affb1f0a1d3c60330beb02f66770e4dd499b02934b669864c5d4a906908c
    

6. Try it yourself!

Download now our Postman collection for this API, which lets you try our API by using the APIs exploring and testing tool Postman.

Alternatively, you can download the OpenAPI 3 JSON specification file.