C’Connect API Documentation

BASIS

The CGate InstantPay Gateway is a secure interface designed by CoralPay for payment processing and has the capabilities of enabling customers to use their USSD PIN to authorize POS or WEB transaction.

To take advantage of this infrastructure, merchants are expect to consume our APIs. Upon registration, we provide merchants with authentication credentials (i.e username & password) which will be used for test and development purpose. You will be provided live setup once you complete the integration process and all necessary documentations have been made. You can reach out to us for more information, support and inquiries.

Note: A working knowledge of PGP/GPG is required, as you will need to generate key pairs for encryption and decryption. click here to generate pgp keys . For more information on PGP please visit our PGP guide page.

Generate a reference from CGate InstantPay API for the POS/WEB USSD Transaction

This is the endpoint called by merchants to generate a reference code with which the customer will pay; usually 4 digits.

URL https://testdev.coralpay.com/cgateproxy/api/invokereference
Verb POST
Content-Type Text/plain
Request Data HEX(PGP(JSON Object)
JSON OBJECT (payload)

{
    "RequestHeader": {
      "Username": "CrownForce",
      "Password": "xxccvvbb"
    },
    "RequestDetails": {
      "TerminalId": "1057P010",
      "Channel": "USSD",
      "Amount": 2000.0,
      "MerchantId": "1057P0100000001",
      "TransactionType": "0",
      "SubMerchantName": "Contoso Limited",
      "TraceID": "09283474728"
      } 
}


.

Field Description

username
This is the username assigned to the channel user for authenticationMandatory
password
This is the password assigned to the channel user for authenticationMandatory
terminalId
This is the terminal that the customer wants to make payment from. Please note for WEB Merchant, this terminal will be created for the merchant and sent to him.Mandatory
amount
This is the amount will pay for the item purchasedMandatory

merchantId
This is the merchant Id of the terminal the customer wants to make payment for. Please note for WEB Merchant, this merchant Id will be created and will be sent to him.Mandatory
TraceIDThis is used as a spare propertyOptional

Channel

This is to determine the source of the transaction. (WEB, POS, USSD)
Optional

SubMerchant Name

This is the name of the aggregators merchant.
Optional

TransactionType

This is to determine the transaction type, the default value is 0.
0 = purchase, 30=Cashout, 35=Cashin, 50= Bill Payment
Optional

Response from the CGATE InstantPay Interface

Content-TypeText/plain
Request DataHEX(PGP(JSON Object)
Response JSON Object



{
  "ResponseHeader": {
    "ResponseCode": "00",
    "ResponseMessage": "Success"
  },
  "ResponseDetails": {
    "Reference": "1856",
    "Amount": "2000.0",
    "TransactionID": "19012301000000001357"
    "TraceID": "09283474728"
}

.

Field Description

responseCodeThe response code of the request
referenceThis is the reference to be used by the customer for the POS/WEB USSD payment
responsemessageThis is the description of the response
TransactionIdThis is the Transaction Identifier

Transaction Status from the POS/WEB/APP

This is a callBack endpoint where the status of the transaction will be pushed. This will return the successful response when customer has made payment. CGATE InstantPay Refernce Code expires after 5minutes. The specification below is expected to be implemented and the endpoint sent for profiling on Cgate.

urlTo be provided by the client
VerbPOST
Content-TypeText/plain
Request DataHEX(PGP(JSON Object)
JSON Object


{
  "responseCode": "00",
  "responsemessage": "Success",
  "reference": "1466",
  "amount": 2000.00,
  "terminalId": "1057P010",
  "merchantId": "1057P0100000001",
  "retrievalReference": "19010811000000000967",
  "institutionCode": "777",
  "shortName": "Sink Node",
  "customer_mobile": "080",
  "SubMerchantName": "Contoso Limited",
  "TransactionID": "19010811000000000967",
  "UserID": "66141919074003",
  "TraceID": "xyz123abc"
}

.

Field Description

referenceThe reference generated by the by the first request and displayed for the customer to make payment.
Mandatory
responseCodeThe response code of the request
referenceThis is the reference to be used by the customer for the POS/WEB USSD payment
responsemessageThis is the description of the response
ShortcodeShort Code dialled by the customer
customer_mobileThe Mobile Number of the customer
terminalIdThis is the terminal that the customer wants to make payment from. Please note for WEB Merchant, this terminal will be created for the merchant and sent to him.
TransactionIDThis is the transaction Identifier
SubMerchantNameThis is the name of the aggregators merchant.
UserIDThis is the unique ID for the customer dialling.

Response from the CGATE InstantPay Interface

Content-TypeText/plain
Response JSON Object{“ResponseCode”:”00″,”ResponseMessage”:”Successful “}
Response DataHEX(PGP(JSON Object)

Transaction Query from the POS/WEB/APP with transaction number

The transaction Id will be used by the POS/WEB/APP to Query the status of the transaction. This will return the successful response when customer has made payment. This transaction confirmation endpoint can be used to query for transactions that have exceeded 5 minutes from the time the reference code was generated. Please note that you will be unable to query for transactions on the Cgate InstantPay Interface using this endpoint after 3 months from when the reference code was generated.

urlhttps://testdev.coralpay.com/cgateproxy/api/statusquery
VerbPOST
Content-TypeText/plain
Request DataHEX(PGP(JSON Object)
JSON Object


 {
  "RequestHeader": {
    "Username": "Citi_Serve",
    "Password": "PosP@ssw3824652"
  },
  "RequestDetails": {
    "TerminalId": "1057P010",
    "Amount": 2000.0,
    "MerchantId": "1057P0100000001",
    "TransactionID": "19012307000000001388"
    } 
}


.

Field Description

TransactionIdThis is the transaction identifier
Mandatory
Mandatory
usernameThis is the username assigned to the channel user for authenticationMandatory
passwordThis is the password assigned to the channel user for authenticationMandatory
terminalIdThis is the terminal that the customer wants to make payment from. Please note for WEB Merchant, this terminal will be created for the merchant and sent to him.Mandatory
amountThis is the amount will pay for the item purchasedMandatory
merchantIdThis is the merchant Id of the terminal the customer wants to make payment for. Please note for WEB Merchant, this merchant Id will be created and will be sent to him.Mandatory

Response from the CGATE InstantPay Interface

VerbPOST
Content-TypeText/plain
Request DataHEX(PGP(JSON Object)
JSON Object

{
  "responseCode": "00",
  "responsemessage": "Success",
  "reference": "1466",
  "amount": 2000.00,
  "terminalId": "1057P010",
  "merchantId": "1057P0100000001",
  "retrievalReference": "19010811000000000967",
  "institutionCode": "777",
  "shortName": "Sink Node",
  "customer_mobile": "080",
  "SubMerchantName": "Contoso Limited",
  "TransactionID": "19010811000000000967",
  "UserID": "66141919074003",
  "TraceID": "xyz123abc"  }



.

Field Description

referenceThe reference generated by the by the first request and displayed for the customer to make payment.
responseCodeThe response code of the request
referenceThis is the reference to be used by the customer for the POS/WEB USSD payment
responsemessageThis is the description of the response
ShortcodeShort Code dialled by the customer
customer_mobileThe Mobile Number of the customer
terminalIdThis is the terminal that the customer wants to make payment from. Please note for WEB Merchant, this terminal will be created for the merchant and sent to him.
TransactionIDThis is the transaction Identifier
SubMerchantNameThis is the name of the aggregators merchant.
UserIDThis is the unique ID for the customer dialling.

Please note that all the response codes conform to the ISO 8583 response code standard format and can be downloaded from the internet.