Processors - OLIVE Payment Platform

Processors are merchants who accept NFC card payments via POS terminals. Each processor gets API credentials for integration.

Processor Lifecycle

Registration

Admin creates processor with business details

Credentials Issued

API key and HMAC secret generated for POS integration

Processing Payments

Processor accepts card payments via POS terminal

Funds Settlement

Processor can transfer funds or request reclaim

Endpoints

Create Processor

POST /api/v1/processorsRegister new processor with credentials

Get Processor

GET /api/v1/processors/:idRetrieve processor details

List Processors

GET /api/v1/processorsList all processors with pagination

Suspend Processor

POST /api/v1/processors/:id/suspendSuspend processor from processing

Transfer Funds

POST /api/v1/processors/:id/transferTransfer to subscriber account

Transaction History

GET /api/v1/processors/:id/transactionsView processor transaction history

Request Reclaim

POST /api/v1/processors/:id/reclaim - Submit fund withdrawal request for admin review

API Credentials

When a processor is created, they receive:

API Key

olive_pos_live_xxxxxFor POS terminal authentication

HMAC Secret

secret_xxxxxFor signing requests

Dashboard Login

Email + password for web dashboard

API key and HMAC secret are only shown once at creation. Store them securely!

Processor Status

Active
Suspended

Status	Description
`active`	Can process payments normally
Can login to dashboard
Can transfer/reclaim funds

Status	Description
`suspended`	All transactions rejected
Dashboard access blocked
API key deactivated
Must contact admin to reactivate

Reclaim Flow

Processors can request to withdraw funds from their account:

Submit Request

Processor submits reclaim request with amount

Pending Review

Request status is pending

Admin Review

Admin approves or rejects request

Funds Transferred

On approval, funds transferred to designated account

Response Examples

Create Processor
Processor Details
Transactions

{
  "success": true,
  "processor_id": "proc_abc123",
  "message": "Processor created successfully",
  "api_key_id": "key_xyz789",
  "api_key": "olive_pos_live_xxxxxx",
  "hmac_secret": "secret_xxxxxx",
  "warning": "Save credentials - they won't be shown again!"
}

{
  "processor": {
    "id": "proc_abc123",
    "name": "Smart PAY Merchant",
    "phone_number": "+23277123456",
    "email": "merchant@smartpay.sl",
    "account_id": "acc_xyz789",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

{
  "success": true,
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "pos_payment",
      "amount": "150.00 SLE",
      "fee": "1.50 SLE",
      "status": "completed",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total_count": 500
}

Integration

POS Integration Guide

Complete guide for integrating POS terminals

API Authentication

Learn about API key and HMAC authentication

Cash In

Create Processor

Documentation Index

​Processor Lifecycle

​Endpoints

Create Processor

Get Processor

List Processors

Suspend Processor

Transfer Funds

Transaction History

Request Reclaim

​API Credentials

API Key

HMAC Secret

Dashboard Login

​Processor Status

​Reclaim Flow

​Response Examples

​Integration

POS Integration Guide

API Authentication

Processor Lifecycle

Endpoints

API Credentials

Processor Status

Reclaim Flow

Response Examples

Integration