Integrate via Groov APIs

Getting started with Groov APIs

This guide is for our developer community and is an attempt to outline an initial getting started steps that the developer teams need to authenticate a connection with Groov and then explore our unified API. 

Every call to a Groov API must include an API secret key. After you create a Groov account, we generate the API key for you – for both test and live modes. To start integrating and connecting your merchants Live accounts with your live-mode keys, you need to activate your account as part of the registration process. Whilst your account gets activated to Live mode, you can use your test-mode keys to test the integration with the mocked up sandbox dataset provided by us.

---

1. Get yourself familiarised first

For a better understanding of Groov API objects and how they fit together, take a tour of our API Catalogue or visit the API reference.

The guide assumes you/your commerce platform organisation has already registered/signed up with Groov, has done necessary product configuration already using the Groov Customer Portal dashboard.

2. Authenticate

Groov platform uses API Key Authentication to authenticate and authorize the application that is making the request. The API key is validated by Groov gateway before granting access to the requested resource.

API Key is located in the header of the request URI, starting with ‘x-api-key’.

API Key example:'x-api-key: pk-test-I9GLn…'

2.1 Get your API key

Your API secret keys can be viewed and copied if you have a Groov dashboard (Groov Customer Portal) with user role as Administrator or Developer. The API Key is used to authorise and authenticate your application and should be treated confidentially. In test-mode, it will be prefixed with pk-test whilst in live-mode it will have pk-live as prefix. 

We dont expire the user secret_keys at the moment but if you cant access the keys via your Groov dashboard, reach out to us.

3. Connect your accounts via code to Sandbox partner

Whilst we are enabling your Live account, you can always test all integrations on the Platform using the test-mode API key assigned to your account.

1. Remember to toggle the sandbox partner in the 'Product Connections' view on your Groov Portal account
2. Copy the test-mode API Key from the Developer section (you will have access as long as you are an Administrator or a Developer user role type on groov platform).
3. Setup integration at your end;
   1. Create a new REST client using https://app.wearegroov.io/api/ as the base URL.
   2. Use the test-mode API key in the header of the request for making test calls.
4. Request a new Connect link for a test merchant using the GET /v1/auth/consent/page. you will receive a Connect URI/link in the response body.
5. Copy the link from above step. You will now need to follow the Connect journey via a web browser as if your client/merchant is doing it. Open the link in a new browser window and follow the journey steps. You will go through a mocked up test journey using the test/sandbox partner account.
6. Once the journey is complete, copy the ledgerAccountId reference from the redirect URI page.
7. Retrieve the connected-account / merchants business info/details using the GET method on the /v1/ledgeraccounts/{ledgerAccountId} endpoint.
8. you have now successfully generated a Connect link for your test customer as well as received details of the connected-customer via the API calls instead of via the Groov Portal.

4. Call Groov's Live API's

Now you are all setup, you have already authorised yourself and have tested using our sandbox test account  

1. Call our API in a live-mode for the first time using code

1. Create a new REST client using https://app.wearegroov.io/api/ as the base URL.
2. Copy the Live API Key from the Developer section (you will have access as long as you are an Administrator or a Developer user role type on groov platform)
3. Setup your Authorisation and Authentication schema using the Live API keys from Groov from your application.
4. You will be able to request a new Connect link for a Live merchant via the /v1/auth/consent/page endpoint

2. Retrieve data from all our available APIs

Groov has provides a rich suite of various endpoints associated to your customer connected platform and all is structured with 'ledgeraccount' object as the primary root. The endpoints that have been available till date have been explained in details in our API Reference documentation section.

As an example if you want to query for all the payments associated to your customer (i.e a ledgeraccount on Groov), you should use the GET method of the Payments sub-category endpoints, refer API reference documentation for details.

Groov API Catalogue

Please browse through our catalog to see what we are working towards to over the next few days. Groov API Catalogue

Happy Grooving....