How does Remita Integration work

Remita provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their Remita account. Developers may call the API directly over HTTPS using the language of their choice.

The purpose of this integration is to enable the corporate or merchant leverage on Remita's diverse and seamless payment options to complete customers' transactions in a handshake implementation known as Remita integration.

How to integrate

Remita is easy to integrate into your website, portal or ecommerce store. Depending on the type of your website, select one of the available methods.

  1. Download Plugin. Check plugins for compatibility with your eCommerce or CMS store and download the appropriate one. Integration with a plugin is simple and doesn't require any custom integration.
  2. Use the integration specification to adapt Remita to your specific needs.

Tools & Plugins

On this section you will find all of our free plugins for Remita integration. These plugins allow you to integrate complete, ready-to-use shopping carts, CMS into your website at no extra cost, providing a simple and familiar way for your customers to shop from your website and make single-step, multi-item purchases.

If your favorite shopping cart or CMS provider is absent from this list, we are always open to suggestions.

Detailed Integration Specification

You are required to create an HTML form which contains payment parameters.

The Remita payment page is loaded on submitting the form from which a payment method can be chosen to complete the payment.

When the payment type option is set in the request, the user is taken directly to the payment option of choice. If payment type is not set, the user is taken to the invoice page to select which payment option to use.

Fields and Values

Parameter Name Description Type
merchantId Required
This is a unique identifier of merchants
String
serviceTypeId Required
This is a unique service type receiving the payment
String
orderId Required
This is the Merchant Transaction ID
String
hash Required
merchantId+serviceTypeId+orderId+amount+responseurl+api_key
String
payerName Required
This is the name of the customer to be displayed on the payment page.
String
payerEmail Required
This is the Payer Email Address
String
payerPhone Optional
This is the Payer Phone Number
Numeric
amt Required
This is the total monetary value of the transaction.
Numeric
paymenttype Optional
It can be either of the following ATM,POS,VERVE,VISA,MASTERCARD, UNION_PAY,REMITA,BANK_BRANCH,BANK_INTERNET,WALLET, RRRGEN
String
responseurl Required
The URL to which Remita should send transaction status report to on completion of transaction.
String

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: merchantId+serviceTypeId+orderId+amt+responseurl+api_key

Sample HTML Code

<html>
      <body>
            <form action="http://www.remitademo.net/remita/ecomm/init.reg" name="SubmitRemitaForm" method="POST">
                  <input name="merchantId" value="1509328648353" type="hidden">
                  <input name="serviceTypeId" value="1509328543428" type="hidden">
                  <input name="orderId" value="8792" type="hidden">
                  <input name="hash" value="ABCED12D3E1476DEFA12" type="hidden">
                  <input name="payerName" value="Customer Name" type="hidden">
                  <input name="payerEmail" value="customer_email@email.com" type="hidden">
                  <input name="payerPhone" value="080211111111" type="hidden">
                  <input name="amt" value="7000" type="hidden">
                  <input name="responseurl" value="http://www.yourwebsite.com/response.php" type="hidden">
                  <input type ="submit" name="submit_btn" value="Pay Via Remita">
           </form>
      </body>
</html>

RRR Payments

To make payment for Remita Retrieval Reference (RRR), a HTTP POST FORM should be sent to Remita.

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: merchantId+rrr+api_key

Sample RRR Payments HTML Form

<html>
      <body>
            <form action="http://www.remitademo.net/remita/ecomm/finalize.reg" name="SubmitRemitaForm" method="POST">
                  <input name="merchantId" value="1509328648353" type="hidden">
                   <input name="hash" value="ABCED12D3E1476DEFA12" type="hidden">
                  <input name="rrr" value="Y11095959" type="hidden">
                  <input name="responseurl" value="http://www.yourwebsite.com/response.php" type="hidden">
                  <input type ="submit" name="submit_btn" value="Pay Via Remita">
            </form>
      </body>
</html>

Split Payments

The corporate or merchant can also leverage on Remita's diverse and seamless payment options to complete distributed transactions to multiple receiving accounts.

The payment request will be sent via the JSON POST as shown below. Remita will facilitate payment of the specified amounts through the indicated service types into the corresponding collecting accounts as applicable.

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: merchantId+serviceTypeId+orderId+amt+responseurl+api_key

Sample JSON Post For Split Payments

{
      "merchantId":"2547933",
      "serviceTypeId":"35457353800",
      "totalAmount":"7000",
      "hash":"9980c10768896f34d1bb202a45e53879122c01c1e01639d3e5ab90bad63ae37d2774",
      "payerName":"Oshadami Mike",
      "payerEmail":"oshadami@example.com",
      "payerPhone":"08012345678",
      "orderId":"POS3455J2",
      "responseurl":"www.yourresponseurl.com",
      "lineItems":[
                        {"lineItemsId":"itemid1","beneficiaryName":"Oshadami Mike",
                        "beneficiaryAccount":"0360883515","bankCode":"020","beneficiaryAmount":"2000","deductFeeFrom":"1"},
                        {"lineItemsId":"itemid2","beneficiaryName":"Ogunseye Mujib",
                        "beneficiaryAccount":"4017904612","bankCode":"022","beneficiaryAmount":"5000","deductFeeFrom":"0"}
                       ]
}

Upon completion of the process, Remita sends JSON Response to the response url containing the following:

  • status of the Transaction
  • Remita Retrieval Reference (RRR) - If successful.

You can now Initiate a call to Pay for the Remita Retrieval Reference (RRR).

Mandate Activation

Remita Direct Debit / Standing Order enables your customers to pay you from any bank. They are required to raise a mandate to present to you for authorization. The customer's instruction(s) will become effective only after their mandates have been activated when you authorize them. They can either make single, one-time transactions or schedule recurrent payments as required. Your customers need to ensure that the designated paying accounts are always funded to cover the transactions accordingly.

Standing Order Activation - SOACT
Direct Debit Activation - DDACT

Fields and Values

Parameter Name Description Type
merchantId Required
This is a unique identifier of merchants
String
serviceTypeId Required
This is a unique service type receiving the payment
String
requestId Required
This is the Merchant Transaction RequestId
String
hash Required
merchantId+serviceTypeId+RequestId+amount+responseurl+api_key
String
payerName Required
This is the name of the customer to be displayed on the payment page.
String
payerEmail Required
This is the Payer Email Address
String
payerPhone Required
This is the Payer Phone Number
Numeric
payerBankCode Required
This is the Payer Bank Code
Numeric
payerAccount Required
This is the Payer Account Number
Numeric
startDate Required
This is the start Date (Format DD/MM/YEAR)
Date
endDate Required
This is the end Date (Format DD/MM/YEAR)
Date
amt Required
This is the total monetary value of the transaction.
Numeric
mandatetype Required
DDACT,SOACT
String
maxNoOfDebits Required (DDACT ONLY)
This is the Maximum Number of Debits in a calender month
Numeric
frequency Required (SOACT ONLY)
Number of recurrent payments per period selected
Numeric
responseurl Required
The URL to which Remita should send transaction status report to on completion of transaction.
String

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: merchantId+serviceTypeId+requestId+amt+responseurl+api_key

Sample HTML Code

<html>
   <body>
            <form action="http://www.remitademo.net/remita/mandate/init.reg" name="SubmitRemitaForm" method="POST">
                  <input name="merchantId" value="1509328648353" type="hidden">
                  <input name="serviceTypeId" value="1509328543428" type="hidden">
                  <input name="requestId" value="8792" type="hidden">
                  <input name="hash" value="ABCED12D3E1476DEFA12" type="hidden">
                  <input name="payerName" value="Customer Name" type="hidden">
                  <input name="payerEmail" value="customer_email@email.com" type="hidden">
                  <input name="payerPhone" value="080211111111" type="hidden">
                  <input name="payerBankCode" value="033" type="hidden">
                  <input name="payerAccount" value="1234567890" type="hidden">
                  <input name="narration" value="Loan Application for Customer Name" type="hidden">
                  <input name="startDate" value="12/02/2015" type="hidden">
                  <input name="endDate" value="22/10/2015" type="hidden">
                  <input name="mandatetype" value="DDACT" type="hidden">
                  <input name="maxNoOfDebits" value="3" type="hidden">
                  <input name="amt" value="7000" type="hidden">
                  <input name="responseurl" value="http://www.yourwebsite.com/response.php" type="hidden">
                  <input type ="submit" name="submit_btn" value="Pay Via Remita">
            </form>
   </body>
</html>

Direct Debit Processing

The payment request will be sent via the JSON POST as shown below. Remita will facilitate payment of the specified amounts through the indicated service types into the corresponding collecting accounts as applicable.

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: merchantId+serviceTypeId+requestId+responseurl+api_key

Sample JSON Post For Direct Debit Processing

{
      "merchantId":"2547933",
      "serviceTypeId":"35457353800",
      "hash":"9980c10768896f34d1bb202a45e53879122c01c1e01639d3e5ab90bad63ae37d2774",
      "payerName":"Oshadami Mike",
      "payerEmail":"oshadami@example.com",
      "payerPhone":"08012345678",
      "requestId":"POS3455J2",
      "responseurl":"www.yourresponseurl.com",
      "mandateItems":[
                        {"mandateFormNo":"A11111132","mandateItemId":"385625277",
                        "description":"Car Monthly Repayment","debitDate":"05/8/2015","amount":"40000"},
                        {"mandateFormNo":"M46563258","mandateItemId":"3437846483",
                        "description":"Housing Repayment Plan","debitDate":"16/10/2015","amount":"80000"}
                             ]
}

Upon completion of the process, Remita sends JSON Response containing:

  • Status of the Transaction

Sample JSON Response

[
       {
              MANDATEFORMNO=A11111132,
              MANDATEITEMID=34444220615164245,
              STATUS=Approved,
              DESCRIPTION=Successful
       },
       {
              MANDATEFORMNO=34444220615164245,
              MANDATEITEMID=8694220615164245,
              STATUS=Failed,
              DESCRIPTION=Mandate is not Authorised for this Service
       }
]

Mandate Status

Basically report views of transactions tied to a particular MandateID and Inactive, Active or Stopped as well as the respective status dates.

Generating Request Hash
For security reasons you are required to hash your payment details with your API Key. Upon registration on Remita you will be given an API Key which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key: requestId+api_key+merchantId

Get Mandate Status

http://www.remitademo.net/remita/ecomm/mandate/merchantId/requestId/hash/status.reg

Get Mandate Transaction History

http://www.remitademo.net/remita/ecomm/mandate/merchantId/requestId/hash/history.reg

Demo / Test Accounts

Merchant Account Credentials

Merchant ID Service Type ID API KEY
2547916 4430731 1946

Test Card Details

Card Type Name Number Expiration CVV PIN
Verve - 6280511000000095 12/2026 123 0000
Visa VCN Test 4999082100029373 01/2019 518 1234

Pay With Remita

Username Password PIN
GRENVILLE REMITA2 1234

Split Beneficiary Account Numbers

Beneficiary Account Number Beneficiary Account Number Beneficiary Account Number
6020067886 0360883515 4017904612

Server POST URL

http://www.remitademo.net/remita/ecomm/init.reg

Split Payments POST URL

http://www.remitademo.net/remita/ecomm/split/init.reg

Mandate Payments POST URL

http://www.remitademo.net/remita/ecomm/mandate/process.reg

Account Transfer POST URL

http://www.remitademo.net/remita/ecomm/acttransfer/init.reg

Transaction Status

Although a status code is sent to the responseurl, a re-query for the status of the transaction is required to confirm the transaction status on Remita on completion of the transaction.

Status Check Parameter

Parameter Names Description Type
merchantId Required
This is a unique identifier of merchants
String
rrr Required
The Remita Retrieval Reference
String
hash Required
SHA512 (RRR+api_key+merchantId)
String
RESPONSE_TYPE Optional
The format in which the response will be formated, valid options are json or jsonp. Default is json
String

Payment Status URL via RRR

http://www.remitademo.net/remita/ecomm/merchantId/RRR/hash/status.reg

Payment Status URL via OrderID

http://www.remitademo.net/remita/ecomm/merchantId/OrderID/hash/orderstatus.reg

Sample JSON Request

http://www.remitademo.net/remita/ecomm/2547916/W7477391/
781d5689aa52d7f00ff42b169931ec7f863b6c293ba0744bef2e848bab8
c8de94061ae5c2a5b8cb2d2d1636418e3aca0295b834c5f4989bf1d073050b9b7ae8f
/status.reg

Sample JSON Response

   {
      "statusmessage": "Transaction Approved",
      "merchantId": "1509328648353",
      "status": "01",
      "RRR": "O11615747",
      "transactiontime": "2014-08-04 01:39:48 PM",
      "orderId": "1021232"
   }

Sample JSONP Response

callback('
   {
      "statusmessage": "Transaction Approved",
      "merchantId": "1509328648353",
      "status": "01",
      "RRR": "O11615747",
      "transactiontime": "2014-08-04 01:39:48 PM",
      "orderId": "1021232"
   }
')

Response Processing

There are two types of responses that the user can get using the system:

  1. Instant Response: This is gotten when the user is paying using REMITA_PAY, or any of the other card options. Responses are immediately returned to the merchant response url passed in with the request.

  2. Batched Response: For transacting consummated via Bank Branch, POS or bank internet, you would not get a response until the transaction is completed. Here, feedback is posted to the Payment Notification Url configured at the collection rule setup.

Sample Batched Response

   [
      {
         "rrr": "A39359490",
         "channnel": "BRANCH",
         "amount": "6500.00",
         "transactiondate": "19/01/2015",
         "debitdate": "19/01/2015",
         "bank": "033",
         "branch": "033152763",
         "serviceTypeId": "4430731",
         "dateSent": "20/01/2015",
         "dateRequested": "19/01/2015",
         "orderRef": "4086852511",
         "payerName": "mujib ishola",
         "payerEmail": "ishola@specs.com",
         "payerPhoneNumber": "08141376868",
         "uniqueIdentifier": 10001
      }
   ]

Logos & Graphics

Give your website more credibility and help reassure customers about security by including a Remita logo on your checkout pages.

Sample Codes

In this section, you will find some SDKs which will allow you to interact with our APIs as well as some sample codes.

PHP

Sample Post to Remita

You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Split Payments Post
You may use the following sample post as a blueprint for your own custom form post. The script handles the split payment form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Get Transaction Status
You may use the following sample as a blueprint for your own custom check status query. The script handles the basic check status query. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

.NET

Sample Post to Remita

You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Split Payments Post
You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Get Transaction Status
You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

JAVA

Sample Post to Remita

You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Split Payments Post
You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Sample Get Transaction Status
You may use the following sample post as a blueprint for your own custom form post. The script handles the basic form post and verify the transaction by calling the Check Status. You will need to add extra lines of code in order for it to behave as your web application requires.
Click to Download Code

Transaction Codes

Status Description
00 Transaction Completed Successfully
01 Transaction Approved
02 Transaction Failed
012 User Aborted Transaction
020 Invalid User Authentication
021 Transaction Pending
022 Invalid Request
023 Service Type or Merchant Does not Exist
025 Payment Reference Generated
029 Invalid Bank Code
030 Insufficient Balance
031 No Funding Account
032 Invalid Date Format
040 Initial Request OK
999 Unknown Error

SHA512 Hash Generator

Paste the text you wish to SHA512 hash here




Copy your SHA512 message digest from here

Remita e-Collection User Acceptance Test (UAT)

  1. You must have the Remita logo on your site to differentiate our payment services from any other ones you might have.
  2. Is the customer aware of the total amount he/she will be debited of before loading the payment page? Always inform the customer duly.
  3. Are customers on your website registered? If no, then you need to communicate their transaction reference number to them before they make payment so that they will have a reference value in case they have issues with their transactions. You should send a mail, text or you could print these details for them on the website with an eye-catching prompt to notify them.
  4. When the payment page loads up, confirm that the amount displayed is correct.
  5. After a transaction had been processed, certain information needs to be displayed to the customer. They include the following;
    • The transaction reference number which you sent to Remita for that transaction.
    • The payment reference which is generated and returned by Remita.
  6. There are various response codes that can be returned by Remita along with their different descriptions. The objective here is to ensure that the customer gets the same description as sent by Remita. The website should NEVER customize Remita responses displayed to the customer.
  7. It is expected that you have a log of all transaction attempts on your website. When transaction IDs are generated, you are to log the transaction on that table and update when the responses returned. That way, you will be able to determine transactions status. For transactions that were described as pending, you need to have the means of confirming their status on Remita. You are to use the Remita Transaction Status query to do that.
  8. It is expected you have a Payment Notification Listener URL, which will receive Payment Notifications sent by Remita. The URL will be configured on your Remita profile.

After you have successfully integrated Remita to your website, you should run through the test cases in the UAT document, complete the check-list. The goal of this exercise is assist you to verify that all test cases are working before requesting for User Acceptance Test (UAT).