Quickstart

This guide takes you from credentials to a completed mobile money collection. The examples use the pre-production base URL, https://preprod.api.nerasika.com.

1. Get your credentials

   When your merchant account is created, Nerasol emails you a merchant ID and a merchant secret. Keep the secret on your server only.

2. Generate an access token

   Send your merchant ID in the body and your secret in the x-merchant-secret header.

   cURL

   curl -X POST https://preprod.api.nerasika.com/api/v1/transactions/auth/token \
     -H "Content-Type: application/json" \
     -H "x-merchant-secret: $NERASIKA_SECRET" \
     -d '{ "merchantId": "'"$NERASIKA_MERCHANT_ID"'" }'

   Node.js

   const res = await fetch('https://preprod.api.nerasika.com/api/v1/transactions/auth/token', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'x-merchant-secret': process.env.NERASIKA_SECRET,
     },
     body: JSON.stringify({ merchantId: process.env.NERASIKA_MERCHANT_ID }),
   });
   const { data } = await res.json();
   const token = data.token;

   PHP

   $ch = curl_init('https://preprod.api.nerasika.com/api/v1/transactions/auth/token');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => [
           'Content-Type: application/json',
           'x-merchant-secret: ' . getenv('NERASIKA_SECRET'),
       ],
       CURLOPT_POSTFIELDS => json_encode(['merchantId' => getenv('NERASIKA_MERCHANT_ID')]),
   ]);
   $token = json_decode(curl_exec($ch), true)['data']['token'];

   Python

   import os, requests
   
   res = requests.post(
       "https://preprod.api.nerasika.com/api/v1/transactions/auth/token",
       headers={"x-merchant-secret": os.environ["NERASIKA_SECRET"]},
       json={"merchantId": os.environ["NERASIKA_MERCHANT_ID"]},
   )
   token = res.json()["data"]["token"]

   The response holds the token in data.token. It is valid for 24 hours, so cache it.

3. Request a payment

   Send the customer’s number, the amount and your callback URL.

   cURL

   curl -X POST https://preprod.api.nerasika.com/api/v1/transactions/payments/collection \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "phone": "0241234567",
       "amount": "10.50",
       "desc": "Order 1042",
       "network": "MTN",
       "merchantRef": "order-1042",
       "merchantCallbackURL": "https://example.com/callback"
     }'

   Node.js

   const res = await fetch('https://preprod.api.nerasika.com/api/v1/transactions/payments/collection', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${token}`,
     },
     body: JSON.stringify({
       phone: '0241234567',
       amount: '10.50',
       desc: 'Order 1042',
       network: 'MTN',
       merchantRef: 'order-1042',
       merchantCallbackURL: 'https://example.com/callback',
     }),
   });
   const { data } = await res.json();
   // Save data.transactionId with your order

   PHP

   $ch = curl_init('https://preprod.api.nerasika.com/api/v1/transactions/payments/collection');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => [
           'Content-Type: application/json',
           'Authorization: Bearer ' . $token,
       ],
       CURLOPT_POSTFIELDS => json_encode([
           'phone' => '0241234567',
           'amount' => '10.50',
           'desc' => 'Order 1042',
           'network' => 'MTN',
           'merchantRef' => 'order-1042',
           'merchantCallbackURL' => 'https://example.com/callback',
       ]),
   ]);
   $data = json_decode(curl_exec($ch), true)['data'];
   // Save $data['transactionId'] with your order

   Python

   res = requests.post(
       "https://preprod.api.nerasika.com/api/v1/transactions/payments/collection",
       headers={"Authorization": f"Bearer {token}"},
       json={
           "phone": "0241234567",
           "amount": "10.50",
           "desc": "Order 1042",
           "network": "MTN",
           "merchantRef": "order-1042",
           "merchantCallbackURL": "https://example.com/callback",
       },
   )
   data = res.json()["data"]
   # Save data["transactionId"] with your order

   NeraSika replies 202 Accepted:

   {
     "success": true,
     "message": "Transaction processing",
     "data": {
       "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
       "merchantRef": "order-1042",
       "amount": 10.5,
       "status": "pending"
     }
   }

   The customer now sees a prompt on their phone to approve the payment.

4. Receive the result

   When the customer approves or declines, NeraSika sends a POST to your callback URL:

   {
     "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
     "merchantRef": "order-1042",
     "transactionType": "collection",
     "amount": 10.5,
     "isoCode": "000",
     "code": "111",
     "status": "successful",
     "statusReason": "successful"
   }

   Reply with any 2xx status. If status is successful (isoCode 000), fulfil the order.

Next steps

• Authentication: token lifetime, caching and errors.
• Collections: every field and rule.
• Callbacks: retries and handling duplicates.