> For the complete documentation index, see [llms.txt](https://docs.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doku.com/subscription-and-billing/flexibill/account-billing/doku-hosted-scheduler.md).

# DOKU Hosted Scheduler

**DOKU Hosted Scheduler** is a fully automated billing model where DOKU manages the entire charge execution lifecycle on behalf of the merchant. The merchant configures the billing rules once via API, shares a checkout link with the customer, and DOKU handles tokenization and all subsequent automatic charges on schedule — no token management required on the merchant side.

***

## Features & Benefits

**⚙️ Zero Scheduling Overhead**

DOKU manages the entire billing schedule automatically. Merchants configure billing rules once and the system executes all subsequent charges without any further intervention.

**🔒 No Token Management Required**

Customer card credentials are tokenized and stored securely by DOKU in a PCI-DSS compliant vault. Merchants only need to store the `billing_number` — no raw card data or tokens ever touch the merchant's server.

**🛒 Hosted Checkout Registration**

DOKU provides a hosted checkout page for card registration. Merchants share the checkout URL with customers — customers fill in their own card details in a secure, DOKU-hosted environment. No card data passes through the merchant's platform.

**🔄 Two Registration Flows**

Supports **Customer Initiate (CI)** for real-time online registration via a checkout link, and **Merchant Initiate (MI)** for bulk batch registration via SFTP or Dashboard file upload.

**📬 Automated Callbacks**

Real-time notifications sent to your configured endpoints for every registration success and payment execution event.

***

## How It Works

{% tabs %}
{% tab title="Customer Initiate (CI)" %}
The Customer Initiate flow is designed for real-time online registration. The merchant calls the Register Bill API to configure the billing rules, receives a checkout URL, and shares it with the customer. The customer fills in their card details on the DOKU-hosted checkout page and pays a registration fee — which is immediately voided. DOKU then tokenizes the card and activates the billing schedule.

* Full programmatic control over the registration flow
* Ideal for web and mobile application onboarding
* Real-time registration confirmation via API response and callback

<img src="/files/5fi4grl4UykShfJBKkRg" alt="" height="397.1044386422976" width="350">

{% stepper %}
{% step %}

#### Call Register Bill API

The merchant's backend calls the Register Bill API to configure the billing rules. The API response returns a `paymentLink` — the checkout URL the customer uses to register their card.

**Endpoint:**

<table><thead><tr><th width="98.7578125">Aspect</th><th>Sandbox</th><th>Production</th></tr></thead><tbody><tr><td><strong>Method</strong></td><td><code>POST</code></td><td><code>POST</code></td></tr><tr><td><strong>URL</strong></td><td><code>https://api-sandbox.doku.com/ab-core-api/v1/billing-registration</code></td><td><code>https://api.doku.com/ab-core-api/v1/billing-registration</code></td></tr></tbody></table>

**Request Headers:**

<table><thead><tr><th width="177.27734375">Header</th><th>Description</th></tr></thead><tbody><tr><td><code>Client-Id</code></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><code>Request-Id</code></td><td>Unique random string (max 128 characters) generated by the merchant to prevent duplicate requests</td></tr><tr><td><code>Request-Timestamp</code></td><td>Request timestamp in ISO 8601 UTC+0 format. For WIB (UTC+7), subtract 7 hours — e.g., 08:51 WIB = <code>2020-09-22T01:51:00Z</code></td></tr><tr><td><code>Signature</code></td><td>HMAC-SHA256 signature generated on the merchant backend. → Authentication</td></tr></tbody></table>

**Request Body:**

```json
{
  "order": {
    "amount": 12000,
    "invoiceNumber": "INV20250724081",
    "currency": "IDR",
    "language": "ID",
    "disableRetryPayment": true,
    "lineItems": [
      {
        "id": "ITEM-001",
        "name": "Monthly Gym Membership",
        "quantity": 1,
        "price": 12000
      }
    ]
  },
  "payment": {
    "paymentDueDate": 8640
  },
  "customer": {
    "id": "CUST029",
    "name": "Yuni",
    "lastName": "Customer 029",
    "phone": "08123456795",
    "email": "customer@email.com"
  },
  "recurring": {
    "billNumber": "BILL2025072415",
    "billDetail": "Monthly Gym Membership",
    "billType": "BILLING_PAYMENT",
    "startDate": "2025-10-28T07:23:00Z",
    "endDate": "2026-10-28T07:23:00Z",
    "executeType": "DATE",
    "executeDate": "5;6;7",
    "executeMonth": "JAN;FEB;MAR;APR;MAY;JUN;JUL;AUG;SEP;OCT;NOV;DEC",
    "flatStatus": true
  }
}
```

For order, payment, customer, shipping address, billing address, additional info object, refer to[ DOKU Checkout Integration Guide](https://developers.doku.com/accept-payments/doku-checkout/integration-guide/backend-integration)

**Recurring Object Parameters:**

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="132.50390625">Parameter</th><th width="81.22265625">Type</th><th width="106.95703125">Required</th><th width="94.18359375">Length</th><th>Description</th></tr></thead><tbody><tr><td><code>billNumber</code></td><td>String (ANS)</td><td>✅</td><td>20</td><td>Unique bill identifier for reference. Must be unique per merchant account.</td></tr><tr><td><code>billDetail</code></td><td>String</td><td>Optional</td><td>—</td><td>Product or service description.</td></tr><tr><td><code>billType</code></td><td>Enum</td><td>Optional</td><td>—</td><td><code>BILLING_PAYMENT</code> — if integrated with DOKU Switching (for utility billers). <code>PAYMENT</code> — standard billing.</td></tr><tr><td><code>startDate</code></td><td>Date</td><td>✅</td><td>—</td><td>Recurring schedule start date. ISO 8601 UTC+0 format.</td></tr><tr><td><code>endDate</code></td><td>Date</td><td>✅</td><td>—</td><td>Recurring schedule end date. ISO 8601 UTC+0 format.</td></tr><tr><td><code>executeType</code></td><td>Enum</td><td>✅</td><td>8</td><td>Determines how billing dates are defined. See Execute Type below.</td></tr><tr><td><code>executeDate</code></td><td>String</td><td>✅</td><td>2048</td><td>The dates on which charges are executed. Format depends on <code>executeType</code>. Multiple values separated by semicolons. See Execute Type.</td></tr><tr><td><code>executeMonth</code></td><td>String</td><td>Optional</td><td>256</td><td>Months in which charges are executed. Required when <code>executeType</code> is <code>DATE</code>. Values: <code>JAN;FEB;MAR</code> etc. Omit when <code>executeType</code> is <code>FULLDATE</code>.</td></tr><tr><td><code>flatStatus</code></td><td>Boolean</td><td>✅</td><td>5</td><td><code>true</code> — fixed billing amount, DOKU uses the <code>order.amount</code> value. <code>false</code> — dynamic amount, DOKU fetches <code>billing_amount</code> from your <strong>URL Amount</strong> endpoint before each charge.</td></tr></tbody></table>

**Execute Type**

`executeType` controls how billing dates are defined for the recurring schedule. Account Billing uses **calendar-based scheduling** — charges run on specific dates, not relative intervals.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="103.57421875">executeType</th><th width="140.97265625">executeDate Format</th><th width="104.56640625">executeMonth</th><th width="137.9140625">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>DAY</code></td><td>Day abbreviations: <code>MON</code> / <code>TUE</code> / <code>WED</code> / <code>THU</code> / <code>FRI</code> / <code>SAT</code> / <code>SUN</code></td><td>Not used</td><td>Charges run on specific days of the week</td><td><code>executeDate: "MON;THU"</code> — charge every Monday and Thursday</td></tr><tr><td><code>DATE</code></td><td>Day numbers: <code>1</code> through <code>28</code></td><td>Required — list of months</td><td>Charges run on specific dates of the month, for specified months</td><td><code>executeDate: "5;6;7"</code>, <code>executeMonth: "JAN;FEB;..."</code> — charge on 5th (primary) + 6th and 7th (retry) each month</td></tr><tr><td><code>FULLDATE</code></td><td>Specific dates in <code>yyyyMMdd</code> format</td><td>Leave empty</td><td>Charges run on exact calendar dates</td><td><code>executeDate: "20251005;20251105"</code> — charge only on Oct 5 and Nov 5 2025</td></tr></tbody></table>

{% hint style="info" %}
**Retry logic with `DATE`:** Pass multiple consecutive dates in `executeDate` (e.g., `"5;6;7"`) to configure automatic retry — if the charge fails on the 5th, the system retries on the 6th, then the 7th. → How Billing Dates Work
{% endhint %}

{% hint style="warning" %}
Maximum date value for `DATE` type is **28**. Day 29, 30, and 31 are not supported to ensure consistent execution across all calendar months.
{% endhint %}

**Dynamic Amount**

By default, Account Billing charges the same fixed amount every cycle — the `order.amount` value from the registration request, with `flatStatus: true`.

If the billing amount varies per cycle (e.g., usage-based billing, tiered plans, or externally calculated charges), set `flatStatus: false`. When this is set, DOKU will **not** use the `order.amount` value for recurring charges. Instead, just before each scheduled charge, DOKU calls the **URL Amount** endpoint configured in your Bill Execution Preferences to retrieve the exact amount for that specific cycle.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="113.66796875">flatStatus</th><th width="211.546875">Amount Source</th><th>Use When</th></tr></thead><tbody><tr><td><code>true</code></td><td><code>order.amount</code> from the registration request — same every cycle</td><td>Billing amount is fixed and does not change between cycles</td></tr><tr><td><code>false</code></td><td>Fetched from your <strong>URL Amount</strong> endpoint before each charge</td><td>Billing amount varies per cycle — DOKU queries your system for the current value</td></tr></tbody></table>

**How the URL Amount endpoint works:**

When `flatStatus` is `false`, DOKU sends a request to your URL Amount endpoint before executing each scheduled charge. Your endpoint must return a `billing_amount` value for the current cycle. DOKU uses this returned value as the charge amount for that execution.

```
Before each charge:
DOKU ──▶ GET {URL Amount endpoint}?bill_number=BILL2025072415&customer_id=CUST029
DOKU ◀── { "billing_amount": 15000 }
DOKU charges customer: IDR 15,000
```

**Configure the URL Amount endpoint** under **Settings → Account Billing → Bill Detail Setting → URL Amount**.

Additionally, `billType` determines where DOKU fetches the dynamic amount from:

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="169.14453125">billType</th><th>Dynamic Amount Source</th></tr></thead><tbody><tr><td><code>PAYMENT</code></td><td>DOKU fetches <code>billing_amount</code> from <strong>your system</strong> via the URL Amount endpoint</td></tr><tr><td><code>BILLING_PAYMENT</code></td><td>DOKU fetches <code>billing_amount</code> from <strong>DOKU Switching</strong> — used for external billers such as utility or BPJS payments</td></tr></tbody></table>

{% hint style="info" %}
If `flatStatus` is `false` and no **URL Amount** endpoint is configured in Bill Execution Preferences, the charge for that cycle will fail. Ensure the endpoint is live, accessible, and returns a valid `billing_amount` value before setting `flatStatus: false`.
{% endhint %}

**API Response:**

<table><thead><tr><th width="141.25390625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td>Response status. <code>success</code> indicates the bill was registered and the checkout link is ready.</td></tr><tr><td><code>paymentLink</code></td><td>The checkout URL to share with the customer for card registration.</td></tr></tbody></table>

{% tabs %}
{% tab title="✅ Bill Registered" %}
**HTTP 200 — Bill registered successfully, checkout link ready.**

```json
{
  "code": "success",
  "type": "success",
  "message": "Success",
  "paymentLink": "https://checkout.doku.com/checkout-link-v2/e615781030584d86..."
}
```

Share the `paymentLink` with the customer. The link takes them to the DOKU-hosted card registration checkout page.
{% endtab %}

{% tab title="❌ Duplicate Bill Number" %}
**HTTP 400 — `billNumber` already registered.**

The `billNumber` passed in `recurring.billNumber` has already been used in a previous registration request.

```json
{
  "code": "FAILED",
  "message": "Bill number already registered"
}
```

**Resolution:** Each `billNumber` must be unique per merchant account. Use a different value and resubmit. Do not reuse bill numbers across customers or billing periods.
{% endtab %}

{% tab title="❌ Authentication Error" %}
**HTTP 401 — Signature validation failed.**

```json
{
  "code": "UNAUTHORIZED",
  "message": "Authentication failed"
}
```

**Resolution:** Verify all four request headers are present and correctly formed — `Client-Id`, `Request-Id`, `Request-Timestamp`, and `Signature`. `Request-Timestamp` must be in ISO 8601 UTC+0 and within acceptable clock skew. → Authentication
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Important — token management:** In the DOKU Hosted Scheduler model, the merchant does **not** need to save or manage card tokens. DOKU stores all tokens in its own PCI-DSS compliant vault and links them to the billing schedule automatically. The only value your system needs to store is the `billNumber`.
{% endhint %}
{% endstep %}

{% step %}

#### Share the Checkout Link with Your Customer

After receiving the `paymentLink` from the API response, share it with the customer through your platform — via email, in-app notification, SMS, WhatsApp, or any other channel.

The customer clicks the link and lands on the DOKU-hosted checkout page — a secure registration form where they enter their card details.

{% hint style="info" %}
The checkout page is fully hosted and secured by DOKU. Card data entered by the customer never passes through the merchant's platform or server.
{% endhint %}
{% endstep %}

{% step %}

#### Customer Registers Card and Pays Registration Fee

On the checkout page, the customer:

1. Enters their card details (card number, expiry, CVV, cardholder name)
2. Confirms and submits the form
3. Pays a **registration fee** — this is an initial charge required to validate that the card is active and accepts charges

**The registration fee is immediately voided.** No money is collected from the customer. The charge appears temporarily as a bank authorization and disappears within a few business days. Its sole purpose is card validation.

**What happens next depends on the configured `startDate`:**

<table><thead><tr><th width="156.90625">Scenario</th><th width="145.14453125">Condition</th><th>Behavior</th></tr></thead><tbody><tr><td><strong>Standard Setup</strong></td><td><code>startDate</code> is a future date</td><td>Registration fee paid and voided. Billing schedule is created but idle. First real charge runs on <code>startDate</code>.</td></tr><tr><td><strong>Immediate Setup</strong></td><td><code>startDate</code> is the same day as registration</td><td>Registration fee paid and voided. System immediately triggers the first billing fee — <strong>2 charges occur on registration day</strong>: the voided registration fee + the first actual billing charge.</td></tr></tbody></table>

{% hint style="warning" %}
**Same-day billing:** If `startDate` is set to the registration date, the customer's card will be charged twice on that day — the registration fee (voided) and the first billing fee (real charge). Ensure this is the intended behavior before setting `startDate` to today.
{% endhint %}
{% endstep %}

{% step %}

#### DOKU Tokenizes and Confirms Registration

Once the card is validated:

* DOKU tokenizes the card and stores the credentials securely
* The billing schedule is created based on `executeType`, `executeDate`, and `executeMonth`
* A **Registration Callback** is sent to the merchant's **New Recurring Alert URL** with the registration result and masked card number
* The customer sees a success or error page on the checkout

**Registration Callback payload (sent to your New Recurring Alert URL):**

```json
{
  "customer": {
    "id": "CUST029",
    "name": "Yuni",
    "email": "customer@email.com"
  },
  "billing": {
    "bill_number": "BILL2025072415",
    "bill_detail": "Monthly Gym Membership",
    "bill_type": "S",
    "start_date": "2025-10-28T07:23:00Z",
    "end_date": "2026-10-28T07:23:00Z",
    "execute_type": "DATE",
    "execute_date": "5;6;7",
    "execute_month": "JAN;FEB;MAR;APR;MAY;JUN;JUL;AUG;SEP;OCT;NOV;DEC",
    "flat_status": true,
    "amount": 12000
  },
  "customerDetail": {
    "card_number": "552002******4209"
  },
  "order": {
    "invoice_number": "INV20250724081",
    "currency": "IDR",
    "amount": 12000
  }
}
```

<table><thead><tr><th width="248.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>billing.bill_number</code></td><td>The <code>billNumber</code> from your registration request — store this as your reference for this customer's recurring billing record.</td></tr><tr><td><code>customerDetail.card_number</code></td><td>Masked card number for display and reconciliation purposes only.</td></tr><tr><td><code>billing.bill_type</code></td><td><code>S</code> = standard <code>PAYMENT</code>, <code>B</code> = <code>BILLING_PAYMENT</code> (DOKU Switching).</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Recurring Charges Execute Automatically

From the first billing date onwards, DOKU automatically charges the customer's card on the configured schedule — no further action required from the merchant or the customer.

For each charge attempt, DOKU sends a **Payment Execution Notification** to your configured **URL Notification** endpoint.

→ [Payment Execution Notification](https://developers.doku.com/get-started-with-doku-api/notification)
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Merchant Initiate (MI)" %}
The Merchant Initiate flow is used when the merchant already holds customer card data — typically for **migrating existing customers** from another system into DOKU Hosted Scheduler. Merchants submit a batch registration file containing customer card data via **SFTP** or the **DOKU Dashboard**.

{% hint style="warning" %}
This flow can be used for data migration — it does not use the DOKU-hosted checkout page and does not involve customer interaction. The merchant is responsible for having obtained proper card data authorization from the customer prior to submission.
{% endhint %}

#### SFTP Registration Flow

1. **Prepare data file** — Generate a `.txt` file containing all customer card data and billing configurations for the batch.
2. **Encrypt and upload** — Encrypt the `.txt` file using AES-256 symmetric key and upload it to the designated `/download` folder on the DOKU SFTP server.
3. **Trigger processing** *(Optional)* — Call the **Trigger Batch API** to initiate processing immediately. DOKU also runs an automated internal scheduler that polls for and processes files at pre-defined intervals.
4. **DOKU processes the file** — DOKU retrieves, decrypts, and processes the registration data. Card tokens and billing schedules are created for each record.
5. **Report generated** — DOKU places a `.txt` result report in the `/upload` folder on the SFTP server and sends a notification to the merchant.
6. **Retrieve report** — Merchant retrieves the report from SFTP to update internal records with registration outcomes.

→ SFTP Setup and Configuration

#### TXT File Format

**Column definitions:**

<table><thead><tr><th width="133.828125">Column</th><th width="133.0625">Type</th><th width="99.37109375">Required</th><th width="93.42578125">Length</th><th>Description</th></tr></thead><tbody><tr><td><code>CUSTOMER ID</code></td><td>Alphanumeric</td><td>✅</td><td>64</td><td>Customer unique ID in the merchant's system</td></tr><tr><td><code>BILLING REF / BILLING NUMBER</code></td><td>Alphanumeric</td><td>✅</td><td>128</td><td>Merchant's unique ID for this billing service</td></tr><tr><td><code>DESCRIPTION</code></td><td>Alphanumeric</td><td>Optional</td><td>256</td><td>Billing description</td></tr><tr><td><code>CURRENCY</code></td><td>Alpha</td><td>✅</td><td>3</td><td><code>IDR</code></td></tr><tr><td><code>AMOUNT</code></td><td>Number</td><td>✅</td><td>12,2</td><td>Billing amount. No decimal: <code>10000</code>. With decimal: <code>10000.00</code></td></tr><tr><td><code>CARD NUMBER</code></td><td>Number</td><td>✅</td><td>16</td><td>Customer's credit card number</td></tr><tr><td><code>CARD EXP DATE</code></td><td>Number</td><td>✅</td><td>4</td><td>Card expiry in <code>MMYY</code> format</td></tr><tr><td><code>CARD HOLDER NAME</code></td><td>Alphanumeric</td><td>Optional</td><td>128</td><td>Cardholder name as printed on card</td></tr><tr><td><code>CARD HOLDER EMAIL</code></td><td>ANS</td><td>Optional</td><td>128</td><td>Customer email</td></tr><tr><td><code>CARD HOLDER PHONE</code></td><td>Number</td><td>Optional</td><td>32</td><td>Customer phone number</td></tr><tr><td><code>CARD HOLDER CITY</code></td><td>Alphanumeric</td><td>Optional</td><td>128</td><td>Customer city</td></tr><tr><td><code>CARD HOLDER REGION</code></td><td>Alphanumeric</td><td>Optional</td><td>128</td><td>Customer region/province</td></tr><tr><td><code>CARD HOLDER COUNTRY</code></td><td>Alpha</td><td>Optional</td><td>2</td><td>ISO country code — e.g., <code>ID</code></td></tr><tr><td><code>CARD HOLDER ADDRESS</code></td><td>Alphanumeric</td><td>Optional</td><td>128</td><td>Customer street address</td></tr><tr><td><code>CARD HOLDER POSTAL CODE</code></td><td>Alphanumeric</td><td>Optional</td><td>16</td><td>Customer postal code</td></tr><tr><td><code>CARD HOLDER BIRTHDATE</code></td><td>Number</td><td>Optional</td><td>8</td><td>Customer birthdate in <code>yyyyMMdd</code> format</td></tr><tr><td><code>START DATE</code></td><td>Number</td><td>✅</td><td>8</td><td>Billing start date in <code>yyyyMMdd</code> format</td></tr><tr><td><code>END DATE</code></td><td>Number</td><td>✅</td><td>8</td><td>Billing end date in <code>yyyyMMdd</code> format</td></tr><tr><td><code>EXECUTE TYPE</code></td><td>Alpha</td><td>✅</td><td>8</td><td><code>DAY</code>, <code>DATE</code>, or <code>FULLDATE</code> — same logic as CI flow</td></tr><tr><td><code>EXECUTE DATE</code></td><td>Alphanumeric</td><td>✅</td><td>2048</td><td>Billing execution dates — format depends on <code>EXECUTE TYPE</code>, values separated by semicolons</td></tr><tr><td><code>EXECUTE MONTH</code></td><td>Alphanumeric</td><td>✅</td><td>256</td><td>Months for execution — required for <code>DATE</code> type, leave empty for <code>FULLDATE</code></td></tr><tr><td><code>FLAT STATUS</code></td><td>Alpha</td><td>✅</td><td>5</td><td><code>TRUE</code> — fixed amount. <code>FALSE</code> — dynamic amount fetched from URL Amount endpoint</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

## Use Cases

{% tabs %}
{% tab title="SaaS" %}

<table><thead><tr><th width="169.91796875"></th><th>Details</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>A SaaS platform charges customers a monthly fee automatically — customers should not need to log in and pay each month.</td></tr><tr><td><strong>Solution</strong></td><td>Integrate Register Bill API into the SaaS onboarding flow. When a new customer signs up, call the API, redirect them to the checkout link, and let DOKU handle all subsequent monthly charges.</td></tr><tr><td><strong>How It Works</strong></td><td>Customer signs up → Merchant calls Register Bill API → Customer clicks checkout link → Enters card + pays voided registration fee → DOKU tokenizes card → Monthly charge auto-executed on billing date → Merchant receives callback.</td></tr><tr><td><strong>Features Used</strong></td><td>CI Flow, Register Bill API, Credit Card Tokenization, Payment Execution Callback</td></tr></tbody></table>
{% endtab %}

{% tab title="Migration" %}

<table><thead><tr><th width="157.2734375"></th><th>Details</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>A business migrating thousands of existing customers from a legacy recurring billing system to DOKU, without requiring each customer to re-register their card.</td></tr><tr><td><strong>Solution</strong></td><td>Use Merchant Initiate (MI) flow — prepare a batch <code>.txt</code> file with existing customer card data and upload via SFTP. DOKU processes the file and creates billing schedules for all customers in one operation.</td></tr><tr><td><strong>How It Works</strong></td><td>Prepare batch file → Encrypt and upload to SFTP → Trigger Batch API (optional) → DOKU processes registrations → Report placed on SFTP → Merchant retrieves and reconciles.</td></tr><tr><td><strong>Features Used</strong></td><td>MI Flow, SFTP Batch Registration, AES-256 Encryption</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

## Merchant & Customer Experience

#### Merchant View

* Call the **Register Bill API** to configure billing rules and receive a checkout link
* Share the checkout link with the customer via any channel (email, in-app, WhatsApp, SMS)
* Store the `billNumber` returned in the Registration Callback — this is the primary reference for the customer's recurring billing record
* Monitor all registered customers and charge statuses under **Account Billing → Manage Recurring**
* Download transaction reports from **Account Billing → Register Report**
* Configure billing execution behavior in **Settings → Account Billing → Bill Detail Setting**

#### Customer View

* Receives a checkout link from the merchant
* Clicks the link and enters card details on the DOKU-hosted checkout page
* Pays a registration fee (immediately voided — no money collected)
* Sees a success or error page; receives confirmation notification
* Is charged automatically on each billing date — no further action required

***

## Terms & Conditions

* Credit Card channel with **SALE + RECURRING** or **SALE + MOTO** must be enabled on your account before using DOKU Hosted Scheduler — Activate Account Billing
* Merchants must store the `billNumber` as the primary reference for each customer's recurring billing record — card tokens are managed entirely by DOKU
* Maximum `executeDate` value is **28** when using `DATE` type — day 29, 30, and 31 are not supported
* MI flow (SFTP batch registration) requires SFTP connectivity to be configured — Connectivity & File Security

***

## FAQ

<details>

<summary>What is the registration fee and why is it charged?</summary>

The registration fee is a small charge executed when the customer submits their card details on the checkout page. Nominal IDR 10,000 or MYR 2. It is immediately voided — no money is actually collected. Its sole purpose is to validate that the card is active and can accept charges, ensuring the recurring billing schedule is created against a working card.

</details>

<details>

<summary>What does the customer see when the registration fee is voided?</summary>

The customer may see a temporary authorization on their bank statement or mobile banking app. This disappears within a few business days — it is not a real deduction. After successful registration, the customer receives a confirmation notification and sees a success page on the checkout.

</details>

<details>

<summary>What happens if the customer's card is declined during registration?</summary>

If the card validation fails, the customer sees an error page on the checkout. No token is created and no billing schedule is registered. The customer must retry with a valid card by opening the checkout link again — if `disableRetryPayment` is set to `false` in the request.

</details>

<details>

<summary>Do I need to save the card token returned after registration?</summary>

No. In the DOKU Hosted Scheduler model, DOKU stores all card tokens internally. You only need to save the `billNumber` from the Registration Callback — this is your reference for the customer's recurring billing record. Never attempt to store raw card numbers or tokens on your own server.

</details>

<details>

<summary>What is the difference between executeType DAY, DATE, and FULLDATE?</summary>

`DAY` schedules charges on specific days of the week (e.g., every Monday and Thursday). `DATE` schedules charges on specific dates of the month (e.g., the 5th of every month) for specified months — this is the standard calendar-based billing mode. `FULLDATE` schedules charges on exact calendar dates (e.g., only on 5 October 2025 and 5 November 2025). Use `DATE` for standard recurring monthly billing.

</details>

<details>

<summary>Can I configure retry dates if the charge fails on the primary billing date?</summary>

Yes. When using `executeType: DATE`, pass multiple consecutive dates in `executeDate` separated by semicolons — e.g., `"5;6;7"`. If the charge fails on the 5th, the system automatically retries on the 6th, then the 7th. Enable **Send One Bill/Month** in Bill Execution Preferences to prevent double-charging if a retry succeeds.

</details>

<details>

<summary>What happens when a recurring charge fails?</summary>

DOKU sends a failure notification to your configured **URL Notification** endpoint. The charge is logged with a failed status in the Manage Recurring dashboard. If retry dates are configured, the system automatically attempts on the next date.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.doku.com/subscription-and-billing/flexibill/account-billing/doku-hosted-scheduler.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.