timilo

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #golang #android #rust #deep-learning #linux #docker #cli #security #mcp #openai

(★ 17)

A lightweight TypeScript SDK for Orange Money Web Payment. Easily create payment links with your Orange credentials. Designed to simplify integration and boost developer productivity. Community contributions welcome!

timilo 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Timilo — Orange Money SDK

[![npm version](https://img.shields.io/npm/v/timilo.svg)](https://www.npmjs.com/package/timilo)
[![license](https://img.shields.io/npm/l/timilo.svg)](https://raw.githubusercontent.com/sorybarry223/timilo/main/LICENSE)

> **Disclaimer:** This is not an official SDK from Orange. It is a side project created to simplify Orange Money Web Payment integration. Make sure you comply with Orange Money's terms of service.

An easy-to-use, dependency-free SDK for integrating **Orange Money Web Payment** into your Node.js / TypeScript applications.

---

## Features

- Handles OAuth authentication and request signing for you
- Single method to create a payment link
- Written in TypeScript — ships with full type definitions
- **Zero runtime dependencies** (uses the native `fetch` API)

---

## Requirements

- **Node.js 18 or higher** (the SDK relies on the built-in `fetch` API)

---

## Installation

```bash
npm install timilo
```

```bash
yarn add timilo
```

```bash
pnpm add timilo
```

---

## Prerequisites

Before using the SDK, you need an Orange Money developer account and the following credentials obtained from Orange Money:

- **basicToken**: Your OAuth basic authentication token (for the initial token request)
- **tokenUrl**: URL to request the OAuth access token (e.g. `https://api.orange.com/oauth/v3/token`)
- **paymentUrl**: URL to create payment requests (e.g. `https://api.orange.com/orange-money-webpay/dev/v1/webpayment`)
- **merchantKey**: Your merchant secret key used to sign payment requests

---

## Usage

### TypeScript / ES Modules

```ts
import { OrangeMoney } from 'timilo';

const sdk = new OrangeMoney({
  basicToken: 'your_basic_token_here',
  tokenUrl: 'https://api.orange.com/oauth/v3/token',
  paymentUrl: 'https://api.orange.com/orange-money-webpay/dev/v1/webpayment',
});

async function createPayment() {
  try {
    const result = await sdk.createPaymentLink({
      merchantKey: 'your_merchant_key',
      orderId: 'ORDER_001',          // Must be unique for each transaction
      totalPrice: 1000,              // Amount in the smallest currency unit
      currency: 'XOF',
      returnUrl: 'https://example.com/success',
      cancelUrl: 'https://example.com/cancel',
      notifUrl: 'https://example.com/notify',
    });

console.log('Payment link:', result.payment_url);
    console.log('Notification token:', result.notif_token);
  } catch (error) {
    console.error('Error:', error);
  }
}

createPayment();
```

### CommonJS

```js
const { OrangeMoney } = require('timilo');
```

---

## API

### `new OrangeMoney(config)`

| Option       | Type     | Required | Description                                       |
|--------------|----------|----------|---------------------------------------------------|
| `basicToken` | `string` | Yes      | OAuth basic token for the initial authentication  |
| `tokenUrl`   | `string` | Yes      | URL to request the OAuth access token             |
| `paymentUrl` | `string` | Yes      | Orange Money API endpoint to create payment links |

### `sdk.getToken(): Promise<string>`

Requests an OAuth access token and returns it. Called automatically by `createPaymentLink`, but exposed in case you need the raw token.

### `sdk.createPaymentLink(input): Promise<{ payment_url: string; notif_token: string }>`

| Option        | Type     | Required | Description                                                                 |
|---------------|----------|----------|-----------------------------------------------------------------------------|
| `merchantKey` | `string` | Yes      | Your merchant secret key used to sign the payment request                   |
| `orderId`     | `string` | Yes      | Unique identifier for the transaction (reusing it causes errors)            |
| `totalPrice`  | `number` | Yes      | Amount to be paid (in the smallest currency unit)                           |
| `currency`    | `string` | No       | Currency code (e.g. `XOF`, `USD`, `EUR`). Defaults to `XOF`                 |
| `returnUrl`   | `string` | Yes      | URL where customers are redirected after a successful payment               |
| `cancelUrl`   | `string` | Yes      | URL where customers are redirected after cancelling a payment               |
| `notifUrl`    | `string` | Yes      | Backend URL where Orange Money sends asynchronous payment notifications     |

**Returns**

| Field         | Type     | Description                                              |
|---------------|----------|----------------------------------------------------------|
| `payment_url` | `string` | The URL to redirect the customer to in order to pay      |
| `notif_token` | `string` | Token used to verify asynchronous payment notifications  |

> **Important:** `notifUrl` is crucial for receiving asynchronous transaction results. Make sure it is publicly accessible and secured.

---

## Important Notes

- **Unique orderId**: Each transaction must have a unique `orderId`. Reusing it results in errors such as HTTP 403 Forbidden.
- **Notification URL (notifUrl)**: Must be publicly accessible so Orange Money can send payment status notifications.
- **Keep credentials secure**: Never expose your `merchantKey`, `basicToken`, or other sensitive information in public repositories or client-side code.
- **Server-side only**: This SDK is intended to run on a server. Do not embed your credentials in a browser bundle.
- **Error handling**: Always wrap SDK calls in `try/catch` to handle network and API errors gracefully.

---

## Development

```bash
git clone https://github.com/sorybarry223/timilo.git
cd timilo
npm install
npm run build
```

### Testing

The SDK ships with a comprehensive test suite (unit + integration) using Jest, with the native `fetch` mocked.

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# With coverage report
npm run test:coverage

# CI mode
npm run test:ci
```

---

## Support

If you encounter issues or have questions, please open an issue on the [GitHub repository](https://github.com/sorybarry223/timilo/issues).

## License

timilo

timilo 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

timilo

timilo 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README