Skip to content

How to use Tuti Gateway Biller System

Tuti Gateway offers a simple and secure way to accept payments, through our billers system. Merchants can leverage our system to accept payments

How to use the new API

Request a new token

Registration service

API: /new

You can register for a new Tuti Gateway merchant service on https://beta.app.2t.sd/api/v1/merchant/new. The step can be done too via TutiPay Merchant App [], to simplify the registration process.

Request

'{"name": "adonese", "city": "kosti", "id_type": 1, "id_no": "1213456",  "password": "1214", "mobile": "0912141679","merchant_id": "assasd"}'
field type
name string
city string
id_type integer
mobileNo string
password string
merchant_id string
push_id string

Response

{"biller_name":"romantic_jang","profile":{"merchant_id":"romantic_jang","name":"adonese","city":"kosti","mobile":"0912141679","id_type":1,"id_no":"1213456","push_id":"","password":"$2a$08$VHTQqbN.U7aZGjjELxXNyeV0Okwjj267VMa.t4keHPoUKsGjDKnsO","is_verified":false,"biller_id":""},"result":"ok","url":"https://beta.app.2t.sd/api/v1/payment/romantic_jang"}
  • url: is needed in subsequent requests. url can be used in TutiPay Merchant app to accept payment.
  • is_verified: is by default false until our team verifies entered data.
  • biller_name: must be stored safely as it will be a unique id assigned to the specific biller.

TODO

assumption: merchant_id is autogenerated name store autogenerated name in sql store autogenerated name in redis

  • in payment (payment_token, and payment/:payment_id):

  • [x] namespace is merchant_id

  • [o] get table from sql
  • [o] get is_verified from sql
  • [o] get biller_id from sql
  • authorize transactions per biller
  • assign transactions to the biller
  • get transactions from the biller
  • get specific transaction using uuid token
  • delete biller
  • update biller info
  • update biller ebs id
  • get biller_id serviceProviderId from store

responds accordingly

First you need to initialize the paymnet, to do that head over to this link:

curl -H "content-type: application/json" -X POST https://api.beta.2t.sd/api/v1/payment_token/$biller_id

** biller_id: a biller id assigned to specific biller by Tuti Gateway.

Response

The response is in terms of UUID v4 data. It is secure, and don't collide

{"result":{"id":"dabceba4-2d23-41d9-9832-f4f005353ce0","uuid":"dabceba4-2d23-41d9-9832-f4f005353ce0"},"uuid":"dabceba4-2d23-41d9-9832-f4f005353ce0"}

For now, id is the same as uuid but we might change that in the future. So use uuid for future proof integration.

  • Use uuid in response in to build the new url

https://[EXTERNAL_NETWORK].beta.app.2t.sd?id={tawasul_reference_id}&amount={entered_amount}&token={uuid}

For example: http://[EXTERNAL_NETWORK].beta.app.2t.sd/?id=123&token=cf455236-69dd-410e-9996-c828d874d6d4&amount=50

This is the link you will be sharing in your mobile app or your website (iframe) to offer the payment ability.

Timeouts

  • The uuid timeouts in 1 hr

Quering result API

In case, you want to see the previous transactions, we offer a querying api.

We need to use the original uuid (the one you inquired and sent through token param) and the biller id assigned to each biller to retrieve the status of a particular transaction.

curl -H "content-type: application/json" -X POST https://api.beta.2t.sd/api/v1/info?id={token}&biller={biller_id}

Response

Successful response
{"id": "some_uuid_here", "terminalId": "18000377","systemTraceAuditNumber": 76,"clientId": "ACTS","responseMessage": "Approval","responseStatus": "Successful","responseCode": 0,"tranDateTime": "200419085611","tranFee": 1.5,"additionalAmount": -1}
Failed response

Follows our standard 

{"message": "Descriptive message about the error", "code": "error_class"}

note, in this case, the biller ID for [EXTERNAL_NETWORK] is: biller:identifer_id.

Cancel transaction

You can also offer to your users Cancellation or do that automatically. We need to use the original uuid (the one you inquired and sent through token param) to cancel a particular transaction.

curl -H "content-type: application/json" -X POST https://api.beta.2t.sd/api/v1/cancel?id={token}

Response

Always check for status codes

Successful response
{"result": true}
Failed response

Follows our standard 

{"message": "Descriptive message about the error", "code": "error_class"}