> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kemypay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> One service per app or business activity, reviewed by our team

A **service** is one of your apps, websites or business activities. Each service collects on its own: its payments, its balances, its webhooks and its reports are separate. Create one service per product (for example your dating app and your online shop).

## Create a service

All fields are required, except `callback_url` and `fee_bearer`.

| Field | Rules |
| - | - |
| `name` | 2 to 60 characters, unique among your services |
| `category` | A `code` from [`GET /mobile-money/categories`](https://docs.kemypay.com/guides/categories) |
| `description` | 20 to 1,000 characters: what you sell and to whom |
| `url` | Public address of your website or app |
| `support_email` | Where your customers can reach you |
| `support_phone` | International format, for example `+237670000000` |
| `webhook_url` | **https** address of your server that receives the payment results |
| `callback_url` | Optional. Where your customer is sent back after paying |
| `fee_bearer` | Optional. `merchant` (default) or `customer`. See [Who pays the fee](https://docs.kemypay.com/guides/fee-bearer.md) |

```bash cURL theme={null}
curl -X POST https://api.kemypay.com/v1/mobile-money/services \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Afroyamo",
    "category": "dating",
    "description": "Dating app for the African diaspora. Premium subscriptions paid by mobile money.",
    "url": "https://afroyamo.com",
    "support_email": "support@afroyamo.com",
    "support_phone": "+237670000000",
    "webhook_url": "https://api.afroyamo.com/kemypay/webhooks",
    "fee_bearer": "merchant"
  }'
```

```javascript Node.js theme={null}
const res = await fetch('https://api.kemypay.com/v1/mobile-money/services', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEMYPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Afroyamo',
    category: 'dating',
    description: 'Dating app for the African diaspora. Premium subscriptions paid by mobile money.',
    url: 'https://afroyamo.com',
    support_email: 'support@afroyamo.com',
    support_phone: '+237670000000',
    webhook_url: 'https://api.afroyamo.com/kemypay/webhooks',
  }),
});
const { data } = await res.json();
// Store data.webhook_secret now: it is shown only once.
```

```php PHP theme={null}
$ch = curl_init('https://api.kemypay.com/v1/mobile-money/services');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KEMYPAY_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Afroyamo',
        'category' => 'dating',
        'description' => 'Dating app for the African diaspora. Premium subscriptions paid by mobile money.',
        'url' => 'https://afroyamo.com',
        'support_email' => 'support@afroyamo.com',
        'support_phone' => '+237670000000',
        'webhook_url' => 'https://api.afroyamo.com/kemypay/webhooks',
    ]),
]);
$data = json_decode(curl_exec($ch), true)['data'];
// Store $data['webhook_secret'] now: it is shown only once.
```

```python Python theme={null}
import os, requests

res = requests.post(
    "https://api.kemypay.com/v1/mobile-money/services",
    headers={"Authorization": f"Bearer {os.environ['KEMYPAY_SECRET_KEY']}"},
    json={
        "name": "Afroyamo",
        "category": "dating",
        "description": "Dating app for the African diaspora. Premium subscriptions paid by mobile money.",
        "url": "https://afroyamo.com",
        "support_email": "support@afroyamo.com",
        "support_phone": "+237670000000",
        "webhook_url": "https://api.afroyamo.com/kemypay/webhooks",
    },
)
data = res.json()["data"]
# Store data["webhook_secret"] now: it is shown only once.
```

```json Response (201) theme={null}
{
  "success": true,
  "data": {
    "code": "019a8f2e-4c1b-7d3a-9e55-2b6f0c1d8a47",
    "name": "Afroyamo",
    "category": { "code": "dating", "name": "Dating & social apps" },
    "description": "Dating app for the African diaspora. Premium subscriptions paid by mobile money.",
    "url": "https://afroyamo.com",
    "support_email": "support@afroyamo.com",
    "support_phone": "+237670000000",
    "status": "pending_review",
    "fee_bearer": "merchant",
    "webhook_url": "https://api.afroyamo.com/kemypay/webhooks",
    "callback_url": null,
    "review_reason": null,
    "created_at": "2026-10-29T10:00:00+00:00",
    "reviewed_at": null,
    "webhook_secret": "whsec_5f2c0a9e7b1d4c3a8e6f0b2d9c7a1e4f5b8d3c6a9e2f1b4d7c0a3e6f9b2d5c8a"
  },
  "meta": { "request_id": "a4f8e2c1b3d97056", "timestamp": "2026-10-29T10:00:00+00:00", "mode": "live" }
}
```

> [!WARNING]
>
> **The `webhook_secret` is returned only when you create the service** (and when you rotate it). Store it in your secrets manager right away. Lost it? Call [`POST /services/{code}/rotate-secret`](https://docs.kemypay.com/api-reference/services/rotate-secret).

## The life of a service

| Status | Meaning | Can collect? |
| - | - | - |
| `pending_review` | Waiting for our review | In test mode only |
| `active` | Approved | Yes |
| `rejected` | Not approved. `review_reason` says why | No |
| `suspended` | Blocked by our team. `review_reason` says why | No. Contact support |
| `disabled` | Paused by you | No, until you enable it again |

We email you every review decision. You can also read `status` with [`GET /services/{code}`](https://docs.kemypay.com/api-reference/services/get).

## Change your settings

Without a new review, at any time:

```bash theme={null}
curl -X PATCH https://api.kemypay.com/v1/mobile-money/services/SERVICE_CODE \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fee_bearer": "customer", "callback_url": "https://afroyamo.com/payment/done" }'
```

* `fee_bearer`, `webhook_url`, `callback_url` (send `null` to remove the `callback_url`).
* The name, category, description, website and support contacts were reviewed: contact [support](mailto:hi@kemypay.com) to change them.
* **Pause** an active service with [`POST /services/{code}/disable`](https://docs.kemypay.com/api-reference/services/disable), and resume it with [`/enable`](https://docs.kemypay.com/api-reference/services/enable). A service `suspended` by our team cannot be enabled this way.

> [!TIP]
>
> A `webhook_url` or `callback_url` sent with a payment takes priority over the one of the service, for that payment only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.