RMAS API Hub

Welcome to the RMAS API documentation. This guide will help you integrate your PFA systems with RMAS for automated returns submission.

Prerequisites

• Valid PFA registration with PenCom
• API credentials (Client ID and Secret)
• SSL certificate for secure communication

Quick Start

curl -X POST https://api.rmas.pencom.gov.ng/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

RMAS API uses OAuth 2.0 for authentication. You'll need to obtain an access token before making any API calls.

Obtaining Credentials

1. Log in to your RMAS account
2. Navigate to API Settings
3. Generate new API credentials

Token Request

POST /v1/auth/token

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "returns.submit returns.read"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "returns.submit returns.read"
}

To ensure system stability and fair usage, the RMAS API implements rate limiting.

Limits

• 1000 requests per hour per API key
• 100 concurrent requests per API key
• File uploads limited to 50MB per request

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Rate Limit Exceeded Response

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again in 60 seconds.",
    "reset_at": "2024-03-15T10:00:00Z"
  }
}

The API uses conventional HTTP response codes and provides detailed error messages.

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {
      "field": "specific_field",
      "reason": "Detailed explanation"
    },
    "request_id": "req_123abc",
    "documentation_url": "https://docs.rmas.pencom.gov.ng/errors#ERROR_CODE"
  }
}

RMAS provides webhooks to notify your application of events in real-time.

Available Events

• return.submitted - When a return is successfully submitted
• return.validated - When a return passes validation
• return.rejected - When a return is rejected
• return.approved - When a return is approved

Webhook Format

{
  "event": "return.submitted",
  "created_at": "2024-03-15T10:00:00Z",
  "data": {
    "return_id": "ret_123abc",
    "status": "submitted",
    "type": "monthly",
    "period": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    }
  }
}

Webhook Security

All webhook requests are signed using HMAC-SHA256. Verify the signature using your webhook secret:

# PHP Example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RMAS_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = hash_hmac('sha256', $payload, $secret);
if (hash_equals($expected, $signature)) {
    // Valid webhook
    http_response_code(200);
} else {
    // Invalid signature
    http_response_code(401);
}

RMAS supports multiple return types, each with its own schema and validation rules.

All submitted data undergoes strict validation to ensure accuracy and compliance.

Validation Rules

• PEN number format and existence check
• Date range validation
• Numerical data consistency
• Required field validation

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid data format",
    "details": [
      {
        "field": "pen_number",
        "error": "Invalid PEN format"
      }
    ]
  }
}

Use our sandbox environment to test your integration before going live.

Test Credentials

Use these credentials for testing:

Client ID: test_client_id
Client Secret: test_client_secret

We provide official SDKs to help you integrate with the RMAS API quickly and securely.