Arianta Pay Payment Gateway - API Documentation

Documentation

Overview

Arianta Pay is a comprehensive payment gateway solution that enables businesses to process payments securely and efficiently through a simple REST API.

Secure

Bank-grade security with JWT authentication and encrypted communications.

Fast

Real-time payment processing with instant status updates and notifications.

Flexible

Easy integration with comprehensive API documentation and sample code.

How Arianta Pay Works

Architecture

Arianta Pay operates on a microservices architecture with the following components:

API Gateway: Handles authentication and request routing
Payment Processor: Processes payment requests through PostgreSQL functions
Transaction Manager: Tracks and manages transaction states
Notification System: Sends real-time updates via webhooks

Payment Flow

Client authenticates and receives JWT token
Payment request is submitted with transaction details
Arianta Pay processes payment through microservices
Transaction status is updated in real-time
Webhook notifications are sent to client's callback URL

Client Onboarding

To get started with Arianta Pay, you need to become an approved client. Here's what you need to know:

Requirements

Business Information

Valid business registration
Company name and contact details
Business address and phone number
Contact person information

Technical Requirements

HTTPS-enabled callback URL
Ability to handle webhook notifications
Secure storage of API credentials
Compliance with security best practices

Onboarding Process

Submit Application

Contact our team with your business information and integration requirements.

Review & Approval

Our team reviews your application and approves your client account.

Account Setup

We create your account and assign you unique API credentials.

Integration & Testing

Integrate our API and test with our sandbox environment.

Go Live

Once testing is complete, you're ready to process live payments!

Getting Started

Ready to get started? Contact our integration team at support@ariantapay.com or call +250 783 200 510 to begin your onboarding process.

Hybrid Authentication

Arianta Pay supports hybrid authentication - both Basic Auth and Bearer Token authentication on the same endpoints for maximum flexibility:

Authentication Priority

The system automatically detects the authentication method based on the Authorization header format:

Bearer Token: If header starts with "Bearer "
Basic Auth: If header starts with "Basic "

Method 1: Basic Authentication

POST /api/v1/auth/token

Get JWT token using Basic authentication.

Headers: Authorization: Basic {base64(username:password)}, X-App-ID: {app_id}

# Get JWT token with Basic Auth
curl -X POST "http://localhost:5000/api/v1/auth/token" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{}'

# Use Basic Auth directly for payment processing
curl -X POST "http://localhost:5000/api/v1/payment/process" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{"f000": "mtnmomorwa", "f001": "SERVICE", "f002": "send_money", ...}'

Method 2: Bearer Token Authentication

# Step 1: Get Bearer token
TOKEN=$(curl -X POST "http://localhost:5000/api/v1/auth/token" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r '.token')

# Step 2: Use Bearer token for payment processing
curl -X POST "http://localhost:5000/api/v1/payment/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"f000": "mtnmomorwa", "f001": "SERVICE", "f002": "send_money", ...}'

Security Notes

Never expose your API credentials in client-side code
Store credentials securely on your server
JWT tokens expire after 24 hours
Always use HTTPS for API communications
X-App-ID header is required for Basic Auth but not for Bearer tokens

API Endpoints

Arianta Pay provides three main API endpoints for payment processing:

POST /api/v1/auth/login

Authenticate and receive JWT token for API access.

Response: JWT token with client permissions and service access.

POST /api/v1/payment/process

Process a new payment transaction.

Headers: Authorization: Bearer {jwt_token}, X-App-ID: {app_id}

POST /api/v1/payment/status

Check the status of an existing transaction.

Headers: Authorization: Bearer {jwt_token}, X-App-ID: {app_id}

Request Payload Format

All payment requests use a standardized payload format with fields f000 through f010:

Field	Description	Type	Required
`f000`	Service name (e.g., "mtnmomorwa")	String	Yes
`f001`	Action type ("SERVICE" for process, "BASE" for status)	String	Yes
`f002`	Route/command name (e.g., "collection")	String	Yes
`f003`	Your App ID	String	Yes
`f004`	Transaction amount (in smallest currency unit)	Number	Yes
`f005`	Mobile number	String	Yes
`f006`	Username/account identifier	String	Yes
`f007`	Encrypted password	String	Yes
`f008`	Plain password	String	Yes
`f009`	Device/app identifier	String	Yes
`f010`	Unique transaction ID	String	Yes

Response Formats

Arianta Pay returns standardized responses based on PostgreSQL function outputs with action: "OUTPUT". The response format varies based on the data type:

String Response (Success)

{
  "status": "200",
  "message": "Transaction processed successfully",
  "action": "OUTPUT",
  "command": "send_money",
  "type": "string",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "successful",
    "message": "Transaction processed successfully",
    "transaction_id": "TXN_MTN_001"
  }
}

String Response (Pending)

{
  "status": "202",
  "message": "Transaction accepted for processing",
  "action": "OUTPUT",
  "command": "send_money",
  "type": "string",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "pending",
    "message": "Transaction accepted for processing",
    "transaction_id": "TXN_MTN_001"
  }
}

String Response (Failed)

{
  "status": "400",
  "message": "Transaction unable to process request",
  "action": "OUTPUT",
  "command": "send_money",
  "type": "string",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "failed",
    "message": "Transaction unable to process request",
    "transaction_id": "TXN_MTN_001"
  }
}

String Response (Not Found)

{
  "status": "404",
  "message": "Transaction not found",
  "action": "OUTPUT",
  "command": "send_money",
  "type": "string",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "failed",
    "message": "Transaction not found",
    "transaction_id": "TXN_MTN_001"
  }
}

Object Response

{
  "status": "200",
  "message": "Account is found",
  "action": "OUTPUT",
  "command": "account_lookup",
  "type": "object",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "successful",
    "message": "Account found",
    "transaction_id": "TXN_MTN_001",
    "object": {
      "account_number": "123456",
      "account_name": "John Doe",
      "balance": 150000,
      "currency": "RWF"
    }
  }
}

Array Response

{
  "status": "200",
  "message": "accounts",
  "action": "OUTPUT",
  "command": "list_accounts",
  "type": "array",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "successful",
    "message": "Account found",
    "transaction_id": "TXN_MTN_001",
    "array": [
      {
        "account_number": "123456",
        "account_name": "John Doe",
        "balance": 150000
      },
      {
        "account_number": "1234563",
        "account_name": "Jane Doe",
        "balance": 75000
      }
    ]
  }
}

Response Processing

The response handler automatically processes PostgreSQL function outputs and formats them according to the specified type (string, object, or array). All responses include a timestamp and standardized status mapping.

Complete Field Reference (F000-F069)

Arianta Pay supports dynamic field validation for fields F000 through F069. Here's the complete field documentation organized by category:

Field Status

static: Field has predefined allowed values
dynamic: Field accepts any value within specified constraints

F000-F003: Gateway & Microservice Metadata

Field	Name	Description	Example	Status
`f000`	ServiceName	Identifies the service provider's microservicename used for processing	mtnmomorwa	dynamic
`f001`	Connection Type	Communication layer or mode	BASE/SERVICE	static
`f002`	serviceRoute	Identifies one of the api route of the microservice mentioned in F000	collection	dynamic
`f003`	AppId	Identifies the application id code initiating the transaction	W3XUDA2	dynamic

F004-F010: Customer/Employee Authentication & Device

Field	Name	Description	Example	Status
`f004`	Customer/Employee ID	Internal unique customer ID	CUSTOMERID	dynamic
`f005`	Mobile Number	Customer mobile number	250788123456	dynamic
`f006`	Username	Registered username	john.doe	dynamic
`f007`	Password	Encrypted/hashed password	***	dynamic
`f008`	Authentication Mode	Auth method (PWD or OTP or PIN or BIO)	PIN	static
`f009`	Device Number	IMEI or device serial	352021094876233	dynamic
`f010`	Device Type	e.g. ANDROID, IOS, WEB	AND	static

F020-F025: Customer/Employee KYC

Field	Name	Description	Example	Status
`f020`	KYC Document Type	e.g. NATIONAL_ID	NATIONAL_ID	dynamic
`f021`	Customer Phone	MSISDN format	+250788123456	dynamic
`f022`	Customer Email	Email address	user@example.com	dynamic
`f023`	First Name	Given name	John	dynamic
`f024`	Middle Name	Middle name (optional)	M.	dynamic
`f025`	Last Name	Surname	Doe	dynamic

F030-F035: Employee's Company Information

Field	Name	Description	Example	Status
`f030`	Company ID	Partner ID	123	dynamic
`f031`	Company Name	company name	Itmholdings Ltd	dynamic
`f032`	Company Email	Contact email	info@itmafrica.com	dynamic
`f033`	Company Phone	Support number	250788123000	dynamic
`f034`	Company Status	ACTIVE, INACTIVE	ACTIVE	dynamic
`f035`	Country of Operation	Country code	RW	dynamic

F040-F049: Payment/Transaction Details

Field	Name	Description	Example	Status
`f040`	Country	Transaction country	RW	dynamic
`f041`	Currency	Currency code	RWF	dynamic
`f042`	Amount	Transaction amount	10000	dynamic
`f043`	Transaction Reference ID	Unique reference	4f2a9e01-...	dynamic
`f044`	Payment Reference ID	payslip number, meterNumber, orderid, or any token	SLIP/004	dynamic
`f045`	Customer Mobile Number	Reused for redundancy	250788123456	dynamic
`f049`	Payment ID	Gateway payment ID	PAY_9938273	dynamic

F050-F059: Payment Information from Payslip

Field	Name	Description	Example	Status
`f050`	Payment Status	Current payment status from payslip	pending	dynamic
`f051`	Payment Amount	Payment amount from payslip	10000.0	dynamic
`f052`	Payment Currency	Payment currency from payslip	RWF	dynamic
`f053`	Payment Method	Payment method from payslip	bank_transfer	dynamic
`f054`	Payment Ready	Whether payment is ready for processing	true	dynamic
`f055`	Payment Batch	Payment batch reference from payslip	BATCH/001	dynamic
`f056`	Gateway Transaction ID	Gateway transaction ID from payslip	TXN_123456789	dynamic
`f057`	Gateway Reference	Gateway reference from payslip	REF_123456789	dynamic
`f058`	Payment Date	Payment date from payslip	2025-09-10	dynamic
`f059`	Retry Count	Number of payment retry attempts	0	dynamic

F060-F069: Employee Payment Configuration

Field	Name	Description	Example	Status
`f060`	Account Number	Employee payment account number	0783200510	dynamic
`f061`	Bank Name	Employee payment bank/provider name	MTN Rwanda	dynamic
`f062`	Payment Provider	Payment service provider	ARIANTAPAY	dynamic
`f063`	Payment Method Code	Payment method identifier code	USD_MOBILE_MONEY	dynamic
`f064`	Payment Currency Code	Employee payment currency code	USD	dynamic
`f065`	Payment Details Valid	Whether payment details are valid	true	dynamic
`f066`	Custom Payment Data 1	Custom payment data field 1	custom_value_1	dynamic
`f067`	Custom Payment Data 2	Custom payment data field 2	custom_value_2	dynamic
`f068`	Custom Payment Data 3	Custom payment data field 3	custom_value_3	dynamic
`f069`	Custom Payment Data 4	Custom payment data field 4	custom_value_4	dynamic

Code Examples

1. Hybrid Authentication

Method 1: Basic Authentication

# Get JWT token with Basic Auth
curl -X POST "http://localhost:5000/api/v1/auth/token" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{}'

# Use Basic Auth directly for payment processing
curl -X POST "http://localhost:5000/api/v1/payment/process" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{"f000": "mtnmomorwa", "f001": "SERVICE", "f002": "send_money", ...}'

Method 2: Bearer Token Authentication

# Step 1: Get Bearer token
TOKEN=$(curl -X POST "http://localhost:5000/api/v1/auth/token" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r '.token')

# Step 2: Use Bearer token for payment processing
curl -X POST "http://localhost:5000/api/v1/payment/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"f000": "mtnmomorwa", "f001": "SERVICE", "f002": "send_money", ...}'

2. Process Payment with Complete Field Set

# Process a payment with comprehensive field set
curl -X POST "http://localhost:5000/api/v1/payment/process" \
  -H "Authorization: Basic YXBpX2xyUFVBcjpHSXRDbk5tMHpkeVQ=" \
  -H "X-App-ID: U8EQDpo2" \
  -H "Content-Type: application/json" \
  -d '{
    "f000": "mtnmomorwa",
    "f001": "SERVICE",
    "f002": "send_money",
    "f003": "U8EQDpo2",
    "f004": "CUST_MTN_001",
    "f005": "+250788123456",
    "f006": "john.doe",
    "f007": "encrypted_pin_123",
    "f008": "PIN",
    "f009": "352021094876233",
    "f010": "AND",
    "f020": "NATIONAL_ID",
    "f021": "+250788123456",
    "f022": "john.doe@example.com",
    "f023": "John",
    "f024": "M.",
    "f025": "Doe",
    "f030": "123",
    "f031": "Itmholdings Ltd",
    "f032": "info@itmafrica.com",
    "f033": "250788123000",
    "f034": "ACTIVE",
    "f035": "RW",
    "f040": "RW",
    "f041": "RWF",
    "f042": 50000,
    "f043": "TXN_MTN_001",
    "f044": "SLIP/004",
    "f045": "+250788123456",
    "f049": "PAY_9938273",
    "f050": "pending",
    "f051": 50000.0,
    "f052": "RWF",
    "f053": "bank_transfer",
    "f054": true,
    "f055": "BATCH/001",
    "f056": "TXN_123456789",
    "f057": "REF_123456789",
    "f058": "2025-09-10",
    "f059": 0,
    "f060": "0783200510",
    "f061": "MTN Rwanda",
    "f062": "ARIANTAPAY",
    "f063": "USD_MOBILE_MONEY",
    "f064": "USD",
    "f065": true,
    "f066": "custom_value_1",
    "f067": "custom_value_2",
    "f068": "custom_value_3",
    "f069": "custom_value_4"
  }'

# Response (String Type - Success)
{
  "status": "200",
  "message": "Transaction processed successfully",
  "action": "OUTPUT",
  "command": "send_money",
  "type": "string",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "status": "successful",
    "message": "Transaction processed successfully",
    "transaction_id": "TXN_MTN_001"
  }
}

3. Check Payment Status

# Check payment status
curl -X POST "https://api.ariantapay.com/api/v1/payment/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-App-ID: YOUR_APP_ID" \
  -d '{
    "f000": "mtnmomorwa",
    "f001": "BASE",
    "f002": "collectionStatus",
    "f003": "YOUR_APP_ID",
    "f004": 5000,
    "f005": "+250788123456",
    "f006": "john_doe",
    "f007": "encrypted_pwd_123",
    "f008": "mypassword",
    "f009": "mobile_app_v1",
    "f010": "txn_20250104_001"
  }'

# Response
{
  "status": "200",
  "type": "object",
  "message": "Transaction status retrieved",
  "version": "1.0.0",
  "action": "OUTPUT",
  "command": "collectionStatus",
  "appName": "Your Company",
  "serviceurl": "N/A",
  "servicepayload": [
    {"i": 0, "v": "YOUR_APP_ID"},
    {"i": 1, "v": "Your Company"},
    {"i": 2, "v": "Your Entity"},
    {"i": 3, "v": "mtnmomorwa"},
    {"i": 4, "v": "Your Country"}
  ],
  "transaction_data": {
    "unique_id": "txn_20250104_001",
    "status": "completed",
    "amount": 5000,
    "mobile_number": "+250788123456",
    "device_id": "mobile_app_v1",
    "created_at": "2025-01-04T10:30:00Z",
    "updated_at": "2025-01-04T10:31:00Z",
    "request_payload": {...},
    "response_payload": {...}
  }
}

Python Example

import requests
import base64
import json

# Configuration
API_BASE_URL = "https://api.ariantapay.com/api/v1"
USERNAME = "your_username"
PASSWORD = "your_password"
APP_ID = "your_app_id"

# Step 1: Authenticate
auth_string = f"{USERNAME}:{PASSWORD}"
auth_bytes = auth_string.encode('ascii')
auth_b64 = base64.b64encode(auth_bytes).decode('ascii')

auth_response = requests.post(
    f"{API_BASE_URL}/auth/login",
    headers={
        "Authorization": f"Basic {auth_b64}",
        "Content-Type": "application/json"
    }
)

if auth_response.status_code == 200:
    token = auth_response.json()["access_token"]
    
    # Step 2: Process Payment
    payment_payload = {
        "f000": "mtnmomorwa",
        "f001": "SERVICE",
        "f002": "collection",
        "f003": APP_ID,
        "f004": 5000,
        "f005": "+250788123456",
        "f006": "john_doe",
        "f007": "encrypted_pwd_123",
        "f008": "mypassword",
        "f009": "mobile_app_v1",
        "f010": "txn_20250104_001"
    }
    
    payment_response = requests.post(
        f"{API_BASE_URL}/payment/process",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "X-App-ID": APP_ID
        },
        json=payment_payload
    )
    
    print("Payment Response:", payment_response.json())
else:
    print("Authentication failed:", auth_response.text)

Support & Resources

Technical Support

Get help with integration and technical issues.

support@ariantapay.com
+250 783 200 510
24/7 Support Available

Resources

Additional resources to help you succeed.

Ready to Get Started?

Contact our integration team today to begin your Arianta Pay journey. We're here to help you succeed!