Overview

The appsNmobile Orchard API is built around Representational State Transfer (i.e. REST). Our APIs accept only JSON-encoded requests and return JSON-encoded responses, while using standard HTTP verbs and a combination of standard HTTP and custom response codes.

Developer integration to Orchard begins with a Test Mode access, where only a limited number (up to 10) of Mobile Money numbers or last four digits of card numbers are whitelisted for integration testing purposes. This means that any number that is not whitelisted on the Orchard platform cannot be used for testing by the developer.

Prerequisite

Any external service provider who needs access to the Orchard Platform must, first of all, complete all necessary merchant/client on-boarding requirements. The following processes apply to you:

1. Client On-Boarding Documentation
2. Client Due Diligence
3. Technical API Integration
4. Compliance User Acceptance Testing of Client Platform
5. Training on use of Client Portal (Optional)
6. Client Go-live

Client On-Boarding Documentation:

• Signing of Non-Disclosure Agreement (NDA)
• Product Service Description
• AML Questionnaire
• ID of Directors
• Company Incorporation Certificates
• Company Profile from Registrar General’s Department

API Integration Steps:

• Whitelisting of Static Public IP(s) of server of client
• Creation of Client Portal Login Access
• API integration begins
• Conduct compliance UAT on client’s service
• Migrate client access to production mode

Client Portal:

Access to our Client Portal is given to you upon a successful completion of the on-boarding procedures. Integration to the Orchard API must first start with your access to the Client Portal, after which you will find the API integration keys on the dashboard of the portal.

Note: Testing of payout transactions will require a prior funding of your Orchard payout account.
Similarly, testing of airtime top-up transactions will require a prior funding of your Orchard airtime account

Connection Procedure

"URL": "https://orchard-api.anmgw.com/{endpoint}"
"Method": POST
"Data format": JSON
"Content Type": application/json

Balance Inquiry

Use this to retrieve information about the current balance on your Orchard account

The different types of accounts available to you are:

• Collections
• Payout

The table below presents the list of parameters that must be used in forming a Check Wallet Balance request to Orchard.

// Your cURL sample request code
curl https://orchard-api.anmgw.com/check_wallet_balance
-H 'Authorization: CLIENT_ID:SIGNATURE'
-H 'Content-Type: application/json'
-X POST
-d '{"service_id": abcd,"trans_type": "BLC", "ts":"2022-01-01 23:20:50"}'

// Your sample response code
{
	"sms_bal": 56,
	"payout_bal": 3.72,
	"billpay_bal": 4.4,
	"available_collect_bal": 359.765,
	"airtime_bal": 30.9,
	"actual_collect_bal": 359.765
}
		

Transaction Status Check

Use this feature to query an existing transaction from Orchard in order to know the status of that transaction. This feature is useful in cases where you did not receive the transaction status from Orchard via your callback url for a certain payment request.

The table below presents the list of parameters that must be used in forming a Transaction Status Check request to Orchard.

// Your cURL sample request code
curl https://orchard-api.anmgw.com/checkTransaction
-H 'Authorization: CLIENT_ID:SIGNATURE'
-H 'Content-Type: application/json'
-X POST
-d '{"exttrid":"031059294635","trans_type": "TSC", "service_id": abcd}'

// Your sample response code
{
	"trans_status": "000/01",
	"trans_ref": "031059294635",
	"trans_id": "21870173572",
	"message": "SUCCESSFUL"
}
		

SMS API

Use this API to send SMS from the Orchard platform

The table below presents the list of parameters that must be used in forming a Send SMS request to Orchard.

Sample Resquest
curl https://orchard-api.anmgw.com/sendSms
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"msg_body": "Your one-time password is 72755","msg_type": "T","recipient_number": "233XXXXXXXXX","sender_id": "NTC","service_id": "XX","trans_type": "SMS","unique_id": "6528738478597202"}'

Sample Response
{
  "resp_desc":"Message successfully queued for delivery",
  "resp_code":"082"
}

Debit/Credit Customer Wallet

This API, when called on a merchant platform allows clients to make or recieve payments for goods/services.

Steps involved in the payment process

Receiving money from customer:

1. Customer performs activity on your platform’s customer interface
2. Customer submits payment request from your platform’s customer interface
3. Your platform receives request and forwards it to Orchard, after initial validation of request at your end
4. Orchard performs further validation on request and submits it to the appropriate network for processing
5. Processing network validates request
6. Customer receives USSD PIN authorization prompt
7. Customer confirms and authorizes payment
8. Fund is deducted from customer’s wallet/account by the network
9. Customer receives alert from network for the fund deduction
10. Network sends transaction status to Orchard
11. Orchard forwards transaction status to you via your callback url
12. A customized alert with details about the payment from your side is sent to customer

Sending money to customer:

1. Validate customer mobile money or bank account number
2. Payment is initiated from your platform to Orchard
3. Orchard receives and performs validation on payment request from you
4. Orchard checks the current balance in your account on Orchard
5. Payment request is forwarded to the network processor
6. Network performs validation
7. Money is sent to customer’s mobile money wallet or bank account
8. Customer receives an alert from network
9. Network sends transaction status to Orchard
10. Orchard forwards transaction status to you via your callback url
11. A customized alert with details about the payment from your side is sent to customer

The table below represents the list of parameters that must be used in forming a Payment Request to Orchard.

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"amount": "10.00","callback_url": "https://my.callback_url.com/payment/callback","customer_number": "0123456789","exttrid": "4243846988303","nw": "MTN","reference": "Test payment","service_id": "XYZ","trans_type": "CTM","ts": "2021-10-21 07:21:43"}'
	

Sample Response
{
    "resp_desc": "Request successfully received for processing",
    "resp_code": "015"
}

Account Information Inquiry

Retrieve the name on customer mobile money wallet or bank account using this feature

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"customer_number": "233200018204","exttrid": "48732659843934", "service_id": "abcd","nw": "BNK", "bank_code": "VOD", trans_type":"AII", "ts": "2021-10-21 07:21:43"}'

Sample Response
{
  "resp_code": "027",
  "resp_desc": "Request successfully completed",
  "name": "John Doe"
}

Ghana Card Verification

Use this api to perform a real time live verification of a person.

Sample Request
curl https://orchard-api.anmgw.com/verifyID
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"id_num": "GHA-xxxxxxxxx-x","id_type": "GCA","service_id": abcd,"exttrid": "xxxxxxxxxxxxxs","image": "base64-encoded-live-photo"}'

Sample Response
{
	"resp_code": "027",
	"resp_desc": "Request successfully completed",
	"data": {
		"name": "XXXXXX",
		"gender": "M",
		"verified": "true",
		"card_valid_start": "2022-01-01",
		"card_valid_end": "2028-01-02"
	}
}

Remittance

Use the remittance api to terminate payments from other countries into mobile money wallets or bank accounts of persons in Ghana. For this service to be made available, the Money Transfer Operator (MTO) must provide documentation/evidence of having been licensed in the originating country.

The table below presents the list of parameters that must be used in forming a remittance request to orchard.

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"sender_name": "test","recipient_name": "tester","sender_number": "23359562354","recipient_address": "Box MD ABC, Accra","transf_amount": 1.0,"transf_purpose": "Remittance testing","exttrid": "1234567961717","nw": "VOD","trans_type": "RMT","callback_url": "/","ts": "2021-10-21 07:21:43","ctry_origin_code": "GBR","service_id": abcd,"sender_gender": "M","recipient_gender": "F","transf_curr_code": "GBP","customer_number": "233507333959","amount": 0.1}'

Sample Response
{
    "resp_desc": "Request successfully received for processing",
    "resp_code": "015"
}

Hosted Checkout (Indirect Integration)

Using this API gives you access to a user interface for Card and Mobile Money payment. With this, you do not have to worry about directly integrating to the Orchard platform in order to enable Mobile Money payment.

Additionally, Card payment is only available to those who can show a proof of PCIDSS compliance, a prerequisite for direct Card integration.

Implement this API in your application and be able to provide Mobile Money and/or Card payment to your customers without going through the complexity of direct integration to Orchard, including being free from the burden of adhering to strict Card processing compliance standards and costs.

The table below presents the list of parameters that must be used in forming a Hosted Checkout or Redirect URL request to Orchard.

How It Works:

1. Customer performs activity on your platform’s customer interface
2. Customer submits payment request from your platform’s customer interface
3. Your platform receives request and forwards it to Orchard, after initial validation of request at your end
4. Orchard performs further validation on request and then displays payment interface to customer
5. Customer makes the appropriate inputs on the payment form and submits
6. Customer receives an OTP request for a quick validation
7. Orchard forwards payment request to the payment processor selected by customer
8. Payment processor performs further validation and proceeds to process request
9. Fund is deducted from customer’s wallet/account by the network
10. Customer receives alert from network for the fund deduction
11. Network sends transaction status to Orchard
12. Orchard forwards transaction status to you via your callback url
13. Orchard redirects customer to your landing page
14. A customized alert with details about the payment from your side is sent to customer

Sample Request
curl https://payments.anmgw.com/third_party_request
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"amount": "0.01","callback_url": "https://my.callback_url.com/payment/callback","exttrid": "4243846303","reference": "Test payment","service_id": abdc,"nickname": "sconty","landing_page" : "url","ts": "2021-10-21 07:21:43","payment_mode": "CRD","currency_code":"GHS","currency_val":"0.01"}'
	

Sample Response
{
  "resp_code": "000",
  "resp_desc": "Passed",
  "redirect_url": "https://payments.anmgw.com/payment_page?code=dG9rZW49NDM3MTkwMjIyMTMxNzk5OSZ0cmFuc19pZD02NDYxOTAyMjIxMzE3OTIxNjI2=="
}

Auto Debit

The auto debit service makes it possible to set recurring debit on a custome's mobile money wallet for subsequent automatic debiting of the wallet without any prior authorization from the mobile money wallet owner.

This is suitable for such services as loan repayment, hire purchase, insurance, among other services that require the customer to make repetitive payments at certain regular intervals/durations

How It Works

To enable recurring debit on a custome's wallet, the following operations must be performed:

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","customer_number":"233595999364","amount":"0.10","nw":"MTN","cycle":"DLY","start_date":"2020-10-01","end_date":"2022-11-01","reference":"Auto Debit Test","return_url":"http://localhost/callback_response","resumable":"Y","cycle_skip":"Y","operation":"SUB","apply_penalty": "NO"}'
		

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","operation":"OTP"}'
		

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","operation":"SUS"}'
		

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","operation":"RES"}'
		

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","operation":"CAN"}'
		

Sample Request
curl https://orchard-api.anmgw.com/autoDebit
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"service_id":service_id,"uniq_ref_id":"8901234567891","operation":"STA"}'
		

Sample Response
{
  profile:{
	"amount": "0.10",
	"callback_url": "http://localhost/callback_response",
	"cancel_date": "",
	"completed": false,
	"customer_number": "233595999364",
	"cycle": "Daily",
	"cycle_skip": "Y",
	"end_date": "2023-07-29 10:30:00",
	"nw": "MTN",
	"resumable": "Y",
	"service_id": service_id,
	"service_name": "Test service",
	"start_date": "2023-07-28 09:00:00",
	"status": "Suspended",
	"subscription_date": "2023-07-24 04:51:50",
	"uniq_ref_id": "8901234567891"
  	},
  transactions: [
	{
       	  "prev_schedule": "",
       	  "processing_id": "PR65565656",
       	  "trans_date": "2023-07-24 04:51:50",
       	  "trans_id": "226566565",
       	  "trans_msg": "SUCCESS",
       	  "trans_ref": "Auto Debit",
       	  "trans_status": "Active"
     }
  ]
}
								

Airtime Top Up

This API, when implemented, allows airtime to be sent to a customer for purposes of electronic airtime refill.

The table below presents the list of parameters that must be used in forming an Airtime top-up request to Orchard

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"amount": "10.00","callback_url": "https://my.callback_url.com/payment/callback","customer_number": "0123456789","exttrid": "4243846303","nw": "MTN","reference": "Test payment","service_id": "XYZ","trans_type": "ATP","ts": "2021-10-21 07:21:43"}'

To get the response below, check the callback_url you provided in forming your request
Sample Response
{
    "resp_desc": "Request successfully completed",
    "resp_code": "027"
}

Bill Payment

This API, when called on a merchant platform allows for payment of bills.

The table below presents the list of parameters that must be used in forming a bill_payment request to Orchard

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"amount": "10.00","callback_url": "https://my.callback_url.com/payment/callback","acount_number": "123456789012","exttrid": "4243846303","nw": "MPR","service_id": "XYZ","trans_type": "BLP","ts": "2022-10-21 07:21:43"}'

Sample Response
{
	"resp_desc": "Request successfully completed",
	"resp_code": "027"
}

GHIPSS Payment

This API, when called on a merchant platform allows for payment using a GHIPSS card.

The table below presents the list of parameters that must be used in forming a ghipss payment request to Orchard

Sample Request
curl https://orchard-api.anmgw.com/sendRequest
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"amount": "10.00","callback_url": "https://my.callback_url.com/payment/callback","exttrid": "4243846303","nw": "MTN","service_id": "XYZ","trans_type": "CTM","landing_page" : "url","ts": "2021-10-21 07:21:43"}'

Sample Response
{
  "resp_code": "000",
  "form_url": "https://gigs-test.ghipss.com:7543/EcomPayment/RedirectAuthLink",
  "form_details": {
	  "MerID": "123",
	  "AcqID": "315",
	  "OrderID": "6582",
	  "MerRespURL": "https://appsnmobileagent.com:8215/return_resp",
	  "PurchaseAmt": "000100",
	  "PurchaseCurrency": 936,
	  "PurchaseCurrencyExponent": 2,
	  "CaptureFlag": "A",
	  "Signature": "IAANKxiU=",
	  "SignatureMethod": "SHA1",
	  "Version": "1.0.0"
	}
}

Callback Response from Orchard

Every payment request from you to Orchard will be followed by a transaction status response from Orchard back to you via the callback_url parameter provided in the original request from you.

Below is the list of parameters that constitute the callback response to your payment request, which is sent back to your platform.

Sample Success Response
{
 "trans_id": "98765432100",
 "trans_ref": 4243846303,
 "trans_status": "000/01",
 "message": "SUCCESS"
}
									
								

Sample Failure Response
{
 "trans_id": "98765432100",
 "trans_ref": 4243846303,
 "trans_status": "001/02",
 "message": "FAILED"
}