Getting Started

We’ve put together this section to help you get started. Here, you will find everything you need to get your first application off the ground, including some sample codes. This section is intended as a reference for those working with GTBank’s APIs for the first time, but it should also serve as a guide with references for common use cases. If you are new here, we recommend going through the material below.


 

Create your developer account

  1. If you do not have an account on the portal, click on sign-up .
  2. Fill all details and submit.
  3. An activation mail (from IBM API CONNECT) will be sent to the email (please check your spam if necessary) provided during registration.
  4. Click on the link provided in the email to activate the newly created account.

Not Signed up yet? Sign up now.


 

Register your Application

Before you can use an API, you must register your application on the Developer Portal. When you register the application, you are provided with a Client ID and Client Secret for the application. The Client ID must be supplied when calling any API. The Client secret will be required when calling the OAUTH. You are required to login to perform this action.

PS:
If you are consuming any OAuth related API, you are required to subscribe to OAuth before consumption. You can subscribe to the OAuth using this link (subscribe here)

The APIs that require OAuth include: Inter-transfer, Intra-transfer, Balance enquiry and Transaction History

Client ID and Client Secret

The Client ID and Client Secretare credentials unique to each application created. This uniquely identifies each application consuming our APIs.
The Client ID is the public credential of an application you created used in every call to identify you.
The Client Secret is the private credential of an application used in verifying your identity.

To register an application, complete the following steps:

  1. Click on the My Apps > Create New App menu link
  2. Fill in the following form fields (Title, Description, OAuth Redirection URL)
    The OAuth Redirection URL is the location you would like GTBank to redirect your ongoing authentication process included with a query variable (code) to be used for further Operational call.
  3. Click on Submit. Your application is displayed.
  4. Make a note of your client secret because it is only displayed once. You must supply the Client secret credentials when calling an API that requires you to verify your identity (i.e the OAUTH).

    NOTE: The client secret cannot be retrieved. If you forget it, you must reset it.

  5. Optional: The client ID is hidden, to display the client ID for your application, select the Show check box for Client ID. The client ID is displayed and can be hidden again by clearing the check box.
  6. Optional: To verify your client secret, click Verify adjacent to Client Secret, enter your client secret in the Secret field, then click on Submit . You have confirmed whether your Client Secret is correct or incorrect.
  7. Optional: To specify or change the URL that authenticated OAuth flows for this application should be redirected to, click the Edit icon and then update OAuth Redirect URI field.
  8. Optional: To change the application name or description, or verify or reset the client secret, click the Edit icon.


 

Subscribe to a product

A product is a group of API packaged together and intended for a particular use. It contains plans which are used to differentiate what is offered by the bank. By subscribing to a product, we will be specifically subscribing to a plan.

  1. On successful login, click on the Product menu link for a drop down of all available product on the portal.
  2. Click on your choice of service on the drop-down menu to navigate to the service page.
  3. Click on the subscribe button to subscribe to the development plan of selected service and select the application you would like subscribed.
  4. A request would be generated on successful subscription for approval.
  5. Click on the service name under APIs on the left column of the page to be directed to the documentation and to test.

PS:
If you are consuming any OAuth related API, you are required to subscribe to OAuth before consumption. You can subscribe to the OAuth using this link (subscribe here)

See OAuth login credentials here: OAuth Login


 

Product Consumption - How to create test data

It is assumed that you have created an application, subscribed to a product (Payment Service for this STEP) and your subscription has been approved. The approval process takes 2-3 working days (after which you receive a notification from IBM API CONNECT of the approved request).

If you do not have a know-how on this process, go through previous steps

  1. Login to your account and navigate to the Payment Service page.
  2. On the Left Side menu, is a list of APIs and operations defined under their respective APIs. Click on the POST /payments/internal operation.
  3. Review the full definition of the Operation by the right side of the page.
  4. Your application initiates a request to access an API protected by GTBank by making an initial call for authorization. The successful call redirects user to GTBank’s Authorization page as below:

    From your application code, below is a sample call to generate an initial access code.

    Authorization URL:
    https://api.eu-de.apiconnect.appdomain.cloud/fintechgtbankcom-live/live/...

    REQUEST:

    GET https://api.eu-de.apiconnect.appdomain.cloud/fintechgtbankcom-live/live/...{{YOUR-CLIENT-ID}}

    Queries:

    response_type: code 
    scope: scope1
    client_id: {{YOUR-CLIENT-ID}}

    RESPONSE:

    Header:
    Content-Type: application/json
    Location: ...........(URL location redirected to)

    Body:

    { 
    "httpCode": "302",
    "httpMessage": "Found",
    "moreInformation": "null"
    }
  5. The application communicates directly with GTBank to gather user identity. After GTBank finishes processing authentication (and optional authorization), it returns an HTTP 302 redirect that uses the original-url from the request, with a confirmation code appended
  6. Retrieve the code value from your query which will be used to make a request for a token.
  7. From the call sample below, initiate a request for an access token:

    Token URL: POST https://api.eu-de.apiconnect.appdomain.cloud/fintechgtbankcom-live/live/...

    REQUEST:

    POST POST https://api.eu-de.apiconnect.appdomain.cloud/fintechgtbankcom-live/live/...

    Body:
    Type: xwww-form-urlencoded

    Client_id: {{YOUR-CLIENT-ID}} 
    Client_secret: {{YOUR-CLIENT-SECRET}}
    grant_type: authorization_code
    scope: scope1
    Code: {{Authorization code provided by the /oauth2/authorize endpoint}}

    RESPONSE:

    Header:
    Content-Type: application/json

    Body:

    {
    "token_type": "bearer",
    "access_token": "AAIkNmMyYWZkZTAtYTA4ZS00OWY0LWJlMzEtNDYzZTV ...............",
    "expires_in": 3600,
    "consented_on": 1581673093,
    "scope": "scope1",
    "refresh_token": "AAIhiN8UAf-BJ6SxeTWqqQhNnjphotlgXXHGkKnxj ..........",
    "refresh_token_expires_in": 2682000
    }
  8. Make a call to the Payment API using the access_token received from your previous call:

    EndPoint: POST https://api.eu-de.apiconnect.appdomain.cloud/fintechgtbankcom-live/live/...

    POST:/payments/internal
    Content-Type: application/json
    Authorization: Bearer TOKEN
    X-IBM-Client-Id: {{YOUR-CLIENT-ID}}

    Body:

    {
    "accountToDebit": "0229594055",
    "accountToCredit": "0160482273",
    "type": "2",
    "requestType": "TRANSFER",
    "purpose": "3rdParty Transfer",
    "userType": "USER",
    "customerClass": "I",
    "authMode": "MPIN",
    "authValue": "871344",
    "secretAnswer": "gerzau",
    "remark": "test",
    "gtT_S2S_Withdrawal": "enkimit",
    "beneBankCode": "058",
    "requestId": "123456",
    "channel": "ibank",
    "userId": "20515890601",
    "customerID": "20515890601",
    "sessionid": "160v3ikZWb2PzTJ8wHL4"
    }
  9. Congratulations, you have successfully consumed a GTBank protected API.


 

Next Step ...

You have now set up your application consuming our APIs.
Ready to go LIVE??? Contact our representative using the link below.

Go-LIVE!!!


 

Exploring the Full API Reference

API Reference helps you to quickly make and see raw API calls and data returned. To be able to use it, you will need test user credentials.


 

Error Codes

You received an error code and don't know what it means? Find a brief explanation below:

Code
Description
400
Invalid access token.
401
Authorisation wasn't successful.
402
Not found - Bad endpoint.
429
The application has sent too many requests in a given amount of time.
500
Server error detected.
503
Service unavailable.