Rovas payment processor

The rovas payment processor functionality allows a calling client — a web, desktop, or mobile application — to direct users to Rovas and collect their payment (say, for a subscription) in Chrons, or Euros. This option expects your application to have a database of users, and keep a record of their access to the premium services your application offers.

Steps to implement:
  1. create an account in Rovas for yourself and make a note of your API key. The API key can be found in the Rovas API tab of your Rovas profile,
  2. create a project in Rovas, for your application,
  3. Put the URL of your payment confirmation webhook endpoint into the Webhook url of the project form (expand the Reward sharing fieldset),
  4. OPTIONAL: in the project form, enter the minimum price in Chrons, or in Euros for the service offered by your application. In both cases users will be able to pay with either currency, but setting the price in Euros will dynamically recalculate the price in Chrons using the current exchange rate. These prices will be used if your request URL does not provide prices as parameters.
  5. in your application, implement a "payment" hyperlink or a button that will issue a HTTPS call to:

    https://<server>/rewpro?<argument pairs>

    where:
    <server> is either:
        - dev.rovas.app - for the development environment, or
        - rovas.app - for the production environment
    <argument pairs> are url arguments:

    parameter type value
    paytype string {project, or user}. In most cases the value will be "project"
    recipient int ID of the Rovas entity (project or user) to be rewarded. For "project" it will be the ID of the one you created in step #2
    callbackurl string the URL of your after-purchase landing page. Rovas will use it to send back the user after purchase.
    token string a unique string to identify the request
    expiration int UNIX timestamp of the request expiration datetime
    price_eur int OPTIONAL - price in euro cents for example, 2€ = 200
    price_chr int OPTIONAL - price in whole Chrons
    name string the name of the product sold
    description string the product description
    signature string the whole URL request without the signature, encoded using the hash algorithm described below
    email string OPTIONAL - email of the user making the purchase - will be used to pre-populate the Rovas ordering form "email" field
    lang string OPTIONAL - two-letter ISO language code of the language of the name and description parameters

     

  6. A request to the URL, will return an order form in Rovas, allowing the buyer to pay with Chrons, or Euros.

  7. Upon completion of the payment process, Rovas will call the URL listed in the webhook url project field, with these parameters:

    parameter type value
    token string the same token received in the request
    signature string a string, generated from the token and secret by the hash algorithm described below 
    amount_paid integer the amount actually paid by the buyer
    currency string {CHR|EUR} - the currency of the payment
    email string the buyer email

  8. If the webhook returns response code = 204, then the user will be sent to the callback URL. Otherwise they see a message "Thank you for the payment. Due to a temporary problem, the premium features at @project could not be immediately activated. We will remedy the problem, and notify you as soon as possible."

The hash algorithm

The token parameter is generated with the HMAC (Hash-based Message Authentication Code) algorithm, from the string to be encoded — the request URL when generating the signature, or token when verifying the webhook response — and the Rovas project owner API key as the shared secret.

Request example

https://rovas.app/rewpro
?
paytype=project
&
recipient=35384
&
token=69e895fb340de7dcd0d6a3e33e56a139a3066224dbd490cee952d3a0cc3f142a
&
callbackurl=https%3A%2F%2F40anywhere.xyz%2FpurchaseCallback.html
&
expiration=1750489424
&
email=somebody%40anywhere.xyz
&
lang=en
&
name=Product+name
&
description=Product+description
&
price_eur=800
&
price_chr=80
&
signature=895991d46af5f989b320f4e04e3959b60723736345cd33483205e0ac307953dc