Gateway Integration

🔐 Payment Gateway API Integration Guide

This guide covers how to integrate with the AkuPay Payment Gateway using RESTful APIs. It includes two main endpoints:

Initialize Transaction
Verify Transaction

📍 API Overview

Staging URL:

https://sandbox-api.nectargateway.com

Live URL:

https://api.akupay.africa

Authentication:

Authorization: <your_public_api_key>

Response is in JSON format.

🏁 Initialize Transaction

Endpoint:

POST /transaction/initialize

The authorization at the point of initializing a transaction is your public key

🔧 Request Body

{
  "amount": 100000,
  "email": "[email protected]",
  "currency": "NGN",
  "reference": "{{$randomUUID}}",
  "callbackUrl": "{{$randomUrl}}",
  "channels": ["card", "bank"],
  "bearer": 1,
	"metadata": {
    "customerId": "CUST12345",
    "orderId": "ORDER67890" }

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in lowest currency unit (e.g., Kobo)
`email`	string	Yes	Customer’s email address
`currency`	string	Yes	e.g., NGN, USD
`reference`	string	Yes	Unique transaction reference
`callbackUrl`	string	No	URL for transaction status notifications
`channels`	array	Yes	Payment methods e.g., `["card", "bank"]`
`bearer`	integer	Yes	1 = Merchant bears fee, 2 = Customer
`metadata`	object	No	Custom metadata

✅ Sample Response

{
  "status": 200,
  "message": "Request successfully processed",
  "data": {
    "authorizationUrl": "https://gateway.akupay.africa/S0h-Jcxbpd_1O_MkUZ-i",
    "reference": "{Merchant Ref}",
    "accessCode": "S0h-Jcxbpd_1O_MkUZ-i"
  },
  "errors": []
}

Field	Type	Description
`status`	string	Request status (e.g., 200)
`authorizationUrl`	string	URL to redirect customer for payment
`reference`	string	Merchant's reference
`accessCode`	string	Internal transaction ID

🔍 Verify Transaction

Endpoint:

GET /transaction/verify/{transactionReference}

The authorization at the point of initializing a transaction is your private key

Parameter	Type	Required	Description
`transactionReference`	string	Yes	Reference of the transaction to verify

✅ Sample Response

{
  "status": 200,
  "message": "Request successfully processed",
  "data": {
    "merchant": "Kiwi Nectarlive",
    "reference": "S0h-Jcxbpd_1O_MkUZ-i",
    "merchantRef": "2d059b6a-4626-47e2-8f35-f903ce7a5f22",
    "grossAmount": 50.75,
    "requestedAmount": 50.00,
    "transactionFee": 0.75,
    "settlementAmount": 50.00,
    "customerId": "[email protected]",
    "currencyCode": "NGN",
    "callbackUrl": "https://test-gateway.akupay.africa/receipt",
    "transactionDate": "2025-03-10T14:04:15.158112",
    "channel": "Card",
    "status": 2
  },
  "errors": []
}

Field	Type	Description
`merchant`	string	Merchant name
`reference`	string	Payment gateway reference
`merchantRef`	string	Merchant's transaction reference
`grossAmount`	float	Total amount charged
`transactionFee`	float	Fee charged
`settlementAmount`	float	Net amount received
`customerId`	string	Customer identifier (email)
`status`	integer	Transaction status code
`authorizationType`	string	e.g., ISW_OTP
`channel`	string	e.g., Card
`transactionDate`	datetime	ISO timestamp

🧾 Status Codes

Code	Status	Description
0	COMPLETED	Transaction completed successfully
1	PENDING	Awaiting processing
2	AUTHORIZED	Authorization successful
3	CAPTURED	Funds captured
4	DECLINED	Payment declined
5	CANCELED	Transaction cancelled
6	REFUNDED	Fully refunded
7	CHARGED_BACK	Dispute raised
8	IN_PROGRESS	Still processing
9	VOIDED	Voided by merchant or system
10	PENDING_REVIEW	Under manual review
11	PARTIALLY_REFUNDED	Partially refunded
12	UNDER_INVESTIGATION	Under investigation
13	FAILED_TO_CAPTURE	Failed capture post-authorization
14	EXPIRED	Authorization expired
15	SUSPENDED	Temporarily paused
16	TRANSFERRED	Settled/finalized elsewhere
17	SCHEDULED	Future-dated transaction