@mnpay/dugaar-deeree

Client library for Mobicom Mongolia's Direct Carrier Billing (DCB) service — Dugaar Deeree. Allows customers to charge purchases directly to their mobile bill, interest-free and fee-free.

Official documentation: https://merchant.mobicom.mn/docs/api

Features

• Auto-managed tokens — access tokens are fetched and refreshed automatically via an axios request interceptor; no manual token management required
• Customer eligibility check — verify whether a phone number is enabled for DCB before initiating a purchase
• Two-step purchase flow — purchaseInitiate followed by purchaseConfirm (OTP-based)
• Transaction lookup — check the status of any transaction by invoice ID
• Statement retrieval — fetch paginated transaction history within a date range

Installation

npm install @mnpay/dugaar-deeree

yarn add @mnpay/dugaar-deeree

Usage

import { useDugaarDeeree } from '@mnpay/dugaar-deeree'

const dcb = useDugaarDeeree({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  // baseURL is optional; defaults to https://cb-api.mobicom.mn/cb-open-api/rest
})

Tokens are managed internally. Every request automatically calls authenticateIfTokenExpired() before being sent — you do not need to call authenticate() manually.

Methods

Authentication

| Method | Description | |--------|-------------| | authenticate() | Fetches a new access token using clientId/clientSecret and stores it internally | | authenticateIfTokenExpired() | Refreshes the token only when expired; called automatically before each request | | getIsExpired() | Returns true if the stored token has expired or has not yet been fetched |

Payments

checkCustomer({ isdn })

Checks whether the customer with the given phone number (isdn) is eligible to use DCB.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | isdn | string | Yes | Customer mobile number |

purchaseInitiate({ buyer, amount, description })

Initiates a purchase transaction. On success returns an invoiceNo used to confirm the purchase.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | buyer | string | Yes | Customer mobile number | | amount | number | Yes | Purchase amount | | description | string | Yes | Purchase description shown to customer |

purchaseConfirm({ invoiceNo, tan })

Confirms a pending purchase using the OTP (tan) sent to the customer.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | invoiceNo | string | Yes | Invoice number from purchaseInitiate | | tan | string | Yes | One-time password received by the customer |

checkTransaction({ invoiceId })

Retrieves the current status of a transaction.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | invoiceId | string | Yes | Invoice ID to look up |

Response: | Field | Type | Description | |-------|------|-------------| | amount | number | Transaction amount | | buyerIsdn | string | Customer mobile number |

checkStatement({ startDate?, endDate?, offset?, limit? })

Retrieves paginated transaction history.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | startDate | string | No | Statement start date | | endDate | string | No | Statement end date | | offset | number | No | Number of records to skip | | limit | number | No | Number of records to return |

Response: | Field | Type | Description | |-------|------|-------------| | startDate | string | Statement start date | | endDate | string | Statement end date | | offset | number | Offset applied | | limit | number | Limit applied | | total | number | Total number of matching records | | response | Transaction[] | Array of transaction records |

Error Codes (IntCode)

All responses include an intCode field. A value of 0 means success.

| Code | Constant | Description | |------|----------|-------------| | 0 | success | Request successful | | 2 | wrongRequest | Bad request | | 3 | otpCodeUnavailable | OTP code is no longer usable | | 5 | badRequest | Bad request | | 6 | invalidAccount | Inactive account | | 8 | purchaseRequestExpired | Purchase confirmation window expired | | 10 | purchaseRequestFailed | Purchase request failed | | 11 | purchaseRequestNotConfirmed | Purchase not yet confirmed | | 12 | wrongConfirmationCode | Incorrect OTP / confirmation code | | 14 | userNotFound | Customer record not found | | 15 | purchaseRequestNotFound | Purchase request not found | | 16 | userBankAccountNotFound | Customer bank account not found | | 19 | otpCodeConfirmationTimeout | OTP confirmation timed out | | 21 | purchaseRequestCanNotBeConfirmed | Purchase cannot be confirmed | | 25 | wrongUserInfo | Invalid customer information | | 26 | userInactive | Customer account is inactive | | 999 | internalSystemError | Internal system error |