Merchant Integration Overview

This is an overview of the onboarding requirements for Merchants to integrate with the Riverty Recurring Payments Product. The following steps enables a merchant to successfully integrate with our APIs:

1. Get Client ID

As a new merchant, a client ID would be created for you. It is the first requirement upon which creation of products, consumers and subscriptions are done. One of our team members will be available to create this ID for you, once you are ready for integration.

2. Authentication

The Subscription Payment API uses access token to authenticate requests. The initial token exchange follows the OAuth2.0 flow. To get the JWT you must have Riverty's Subscription Payments client id and your client secret. You'll then have to send these credentials to Riverty Token Exchange, where the credentials will be validated. If valid, you'll receive an access token. It is important to note that the Riverty Client ID used in the request URL and the Auth0 ClientID used to get the JWT token are not the same. Full details about the Authentication process can be found on the Authentication page under the Get Started section.

3. Create Subscription Product

  After authentication, you can configure you subscription product by calling the Endpoint below: <br>

PUT/v1/clients/{clientId}/subscription-products/{subscriptionProductId}

The full API documentation can be found on the API specification page.

Below is a table showing the definitions of the configuration parameters for creating a subscription product. The terms and conditions required for subscriptions cancellations, billing types, commitment cycles also need to be defined.

Object	Parameters	Definition
Product Details	Description	This describes the product you want your customers to subscribe to. Description is used as invoice line for the subscription.
	Product URL	If your product has a URL or link, you will be able to insert it in this field.
	Image URL	This allows you to add the link to an image of your product.
Product Period	Type	This describes the periodization of your subscription. It could either be monthly, quarterly, half year and yearly
	Price	This is where you state the price of your product
	Start	Allows you to enter the start of the period
Items	Name	This describes the name of the item
	Description	Description of the item
	GrossAmount	The gross amount of the item
	VATPercentage	The VAT amount of the item (%)
	Metadata	Additional Data about the item
	isRefundable	Stating whether the item is refundable or not
Terms & Conditions	Billing Type	What type of billing is allowed on your subscription - It could either be INADVANCE or INARREARS
	Cancellation Type	What type of cancellation is allowed on your subscription. It could be INSTANT, AFTERCURRENTPERIOD, AFTERNEXTPERIOD
	Commitment (Optional)	This describes how long the customer should be locked in for the subscription. The period, commitment cycle and end of commitment action needs to be defined. For the commitment cycle, there are 3 options namely; RENEWCOMMITMENT, CONTINUEWITHOUTCOMMITMENT, CLOSESUBSCRIPTION
Availability	From	This describes when your subscription product will be available Until
	Trail Period	The Length of the trial period
	Price	The gross & VAT amount of the trial period. It could either be free or at a discounted price.
Financing Type	Billing	This financing type means settlement or payouts will be done only when invoice has been generated for customer
	Contract	This financing type means settlement or payouts will be done at the start of the period for that subscription.

Sample Request Body: A music streaming subscription that has a monthly billing cycle and monthly renewal where the consumer can cancel at the end of every month

4. Create Consumer

Every transaction in recurring payments revolves around a customer. This means that before you can start adding transactions, you need to create customers.
To create a customer, the API to call is PUT /v1/clients/{clientId}/customers/{customerNumber}
The following parameters are required to successfully create a consumer:

Parameters	Definition
type	Enum: Person or Company (string)
person	person object - Legal information of the person. ssn(string) - The social security number of the person. firstName (string) - The first name of the person lastName(string) - The last name of the person.
phoneNumber	The phone number of the customer(string)
email	The email address of the consumer (string)
address	The address of the consumer (string)

Request Sample:

5. Start Subscription

To successfully start a consumer subscription, the subscription product and the consumer must have been created. A risk check is also performed to assess the credibility of the consumer.

Once a consumer has completed the process of subscribing to your product through your website, the create subscription API is triggered and subscription is created once the customer passes our risk checks. Created Subscriptions will be invoiced based on the configurations of your product.
The API to start a subscription is PUT /v1/clients/clientId/subscriptions/subscriptionId

The API parameters required to start a subscription are:

Parameters	Definition
customerNumber	string <= 100 characters Id of the customer to assign this subscription to.
subscriptionProductId	string <= 100 characters Id of the subscription product.
billingDayOffset	The billing day offset is used to adjust the billing day defined on the subscription product. (integer)
metadata	array of metadata A list of key-value pairs. (optional)
activeFrom	string date The date from which date this subscription is active.

Request Sample: a subscription with a product_id of 500, where an invoice is triggered to the consumer on the 5th day after start of subscription.

Next Steps :

Would you like to get started with integrations? Kindly fill the form on this page and one of our team members will contact you.

Menu