Merchant Hosted Scheduler

Availability: 🇮🇩 Indonesian Business Account only

Merchant Hosted Scheduler gives merchants full control over billing execution. The merchant manages customer payment tokens internally and triggers charges on demand by uploading a batch billing file to DOKU via SFTP. DOKU executes the charges and returns a consolidated result report.

Unlike DOKU Hosted Scheduler where DOKU manages the full schedule automatically, in this model the merchant owns the schedule — DOKU only executes the charge when the merchant submits a file.

---

Features & Benefits

🎛️ Full Scheduling Control

Merchants define exactly when charges are executed. Billing is triggered by file upload — not managed automatically by DOKU.

🗄️ Merchant-Managed Tokens

Customer payment tokens are obtained and stored by the merchant from a prior first payment. Tokens are reusable across billing cycles as long as the underlying payment method remains valid.

📁 Bulk Billing via SFTP

Process large volumes of charges simultaneously by uploading a structured .TXT billing file to the DOKU SFTP server. Each file is processed as a batch — one file can cover thousands of customers in a single operation.

📊 Consolidated Reporting

After each batch is processed, DOKU generates a result report with per-record outcomes — success, failure, and failure reason — placed in the SFTP outbound directory for merchant download and reconciliation.

---

Prerequisites

Before using Merchant Hosted Scheduler, the following must be in place:

• Account Billing activated with a compatible payment channel — Activate Account Billing

• SFTP access configured and IP whitelisted — Connectivity & File Security

• Customer tokens obtained via First Payment — see Step 1 below

---

How It Works

Customer                Merchant System              DOKU
    │                         │                        │
    │── First Payment ────────▶│                        │
    │   (card/direct debit)   │                        │
    │                         │── Get Token List API ──▶│
    │                         │◀─ Token returned ───────│
    │                         │                        │
    │   [On billing date]     │                        │
    │                         │── Prepare .TXT file    │
    │                         │── Encrypt file         │
    │                         │── Upload to SFTP ──────▶│ /download folder
    │                         │── Trigger API ─────────▶│ (optional)
    │                         │                        │
    │                         │                        │── Process batch
    │                         │                        │── Execute charges
    │                         │                        │── Generate report
    │                         │                        │
    │                         │◀─ DOKU notification ───│ (report ready)
    │                         │◀─ Report file ──────────│ /upload folder
    │                         │                        │
    │◀─ Payment notification ─│                        │

---

Step-by-Step Guide

1

First Payment: Obtain Customer Token

Before a customer can be included in any batch billing file, a token must be obtained for their payment method. A token is a secure reference to the customer's payment credential — it never exposes the raw card or bank account number.

How to get a token:

1. The customer completes a First Payment through one of the supported payment methods:

   • Credit Card / Debit Card → Direct API - Cards

   • Direct Debit (BRI, MANDIRI) → Direct API - Direct Debit

2. After the First Payment completes, call the Get Token List API to retrieve the token bound to that customer: → Get Token List API

3. Store the token in your system alongside the customer record. The token is bound to both the payment credential and the customer_id used during the First Payment.

Token lifecycle:

Scenario	Token Status	Action Required
Payment method is active	✅ Valid — reuse across billing cycles	No action
Card expired	❌ Invalid — token no longer usable	Initiate new First Payment with customer to obtain a new token
Card cancelled or blocked	❌ Invalid	Initiate new First Payment with customer
Charge failed due to insufficient funds	✅ Still valid	Retry with the same token in the next billing cycle

Tokens are reusable. You do not need a new token for each billing cycle — the same token works for every charge against the same payment method until that method becomes invalid.

When a card expires and the merchant obtains a new token from the customer's replacement card, use the new token in all subsequent batch files. Do not continue submitting the expired token — it will generate a record-level failure every cycle.

2

Prepare the Batch Billing File

Create the billing file in .TXT format. Each line in the file represents one charge record.

File Naming Convention

The filename must include the prefix TKN_. Files without this prefix will not be recognized and processed by DOKU.

✅ TKN_202510ABC.TXT
✅ TKN_20251005_BATCH01.TXT
❌ BATCH_202510.TXT        (missing TKN_ prefix)
❌ TKN_202510ABC.csv       (wrong extension)

File names are used as idempotency keys in the Trigger API. Do not reuse the same filename across different billing cycles — each batch file must have a unique name.

Column Definition

Column	Type	Required	Length	Description
BILLING REF / BILLING NUMBER	Alphanumeric	✅	128	Merchant's unique ID for this billing service record
DESCRIPTION	Alphanumeric	Optional	256	Billing description
INVOICE NUMBER	Alphanumeric	✅	64	Unique invoice number for this charge
CURRENCY	Alpha	✅	3	IDR only
AMOUNT	Number	✅	10,2	Charge amount. No decimal: 10000. With decimal: 10000.00
TOKEN	Number	✅	32	Customer payment token obtained from Get Token List API
CARD HOLDER NAME	Alphanumeric	Optional	128	Customer name
CARD HOLDER EMAIL	Alphanumeric	Optional	128	Customer email
CARD HOLDER PHONE	Number	Optional	32	Customer phone number
CARD HOLDER CITY	Alphanumeric	Optional	128	Customer city
CARD HOLDER REGION	Alphanumeric	Optional	128	Customer region/province
CARD HOLDER COUNTRY	Alpha	Optional	2	ISO country code — e.g., ID
CARD HOLDER ADDRESS	Alphanumeric	Optional	128	Customer street address
CARD HOLDER POSTAL CODE	Alphanumeric	Optional	16	Customer postal code
CARD HOLDER BIRTHDATE	Number	Optional	8	Customer birthdate in yyyyMMdd format
EXECUTE DATE	Number	Optional	8	Specific date to execute this charge in YYYYMMDD format. If omitted, DOKU executes the record immediately when the file is processed. Must not be a past date.

EXECUTE DATE must not be a date in the past. If a past date is provided, the record will fail with an INVALID EXECUTE DATE error and the file will be placed in /upload/failed without any charges being executed. Set EXECUTE DATE to today or a future date, or omit it to execute immediately.

3

Encrypt and Upload to SFTP

Before uploading, the file must be encrypted. After encryption, upload to the DOKU SFTP /download folder.

For full encryption procedure, folder structure, and SFTP connection details → Connectivity & File Security (SFTP)

4

Trigger DOKU Processing (Optional)

After uploading the file, optionally call the Trigger Batch API to initiate processing immediately. Without this call, DOKU's internal scheduler will automatically pick up and process the file at its next polling interval.

Endpoint:

	Sandbox	Production
Method	POST	POST
URL	https://api-sandbox.doku.com/batch-upload/v1/notify	https://api.doku.com/batch-upload/v1/notify

Request Headers:

Header	Description
Client-Id	Client ID from DOKU Back Office
Request-Id	Unique random string, max 128 characters
Request-Timestamp	ISO 8601 UTC+0 format. For WIB (UTC+7), subtract 7 hours — e.g., 08:51 WIB = 2020-09-22T01:51:00Z
Signature	HMAC-SHA256 signature generated on merchant backend

Request Body:

{
  "file_name": "TKN_202510ABC.TXT"
}

Parameter	Type	Required	Description
file_name	String	✅	Exact filename as uploaded to the SFTP /download folder, including the TKN_ prefix and .TXT extension

Response Scenarios:

✅ In Process

HTTP 201 — File accepted for processing.

{
  "name": "TKN_202510ABC.TXT",
  "status": "IN_PROCESS"
}

DOKU has received the trigger and is processing the file. Monitor the SFTP /upload folder for the result report and wait for the DOKU notification callback.

❌ Invalid Signature

❌ Invalid Parameter

❌ Duplicate File Name

5

Receive DOKU Processing Notification

When DOKU finishes processing the batch file, it sends a notification to your configured merchant endpoint. This is the signal that the result report is ready to download.

DOKU sends a POST request to your notification URL with:

{
  "service": {
    "id": "BATCH_UPLOAD"
  },
  "batch_file": {
    "name": "TKN_202510ABC.TXT",
    "status": "DONE",
    "date": "2025-10-05T13:52:53Z"
  }
}

Field	Description
service.id	Always BATCH_UPLOAD for batch processing notifications
batch_file.name	The filename that was processed
batch_file.status	DONE — processing is complete. The result report is ready in the SFTP /upload folder
batch_file.date	Timestamp when processing completed, ISO 8601 UTC+0

Configure your notification endpoint URL under Settings → Account Billing → Bill Detail Setting → URL Notification.

6

Download and Reconcile the Report

After receiving the DOKU notification, download the result report from the SFTP /upload folder.

For the full report file structure, field definitions, and BANK CODE lookup table → Connectivity & File Security — Report File

Reconciliation triage — how to handle FAILED records:

Failure Type	Signal in Report	Action
Insufficient funds	FAILED + bank declined response code	Token is still valid — retry the customer in the next billing cycle file
Expired or invalid token	FAILED + token-related response code	Token is no longer usable — initiate a new First Payment with the customer to obtain a new token, then use the new token in the next cycle
Card blocked / stolen	FAILED + bank restriction response code	Contact customer for a new payment method — initiate new First Payment once resolved
Invalid execute date	FAILED + INVALID EXECUTE DATE	Correct the EXECUTE DATE in your next file — must not be a past date
Already paid	ALREADY_PAID	Send One Bill/Month is active and the customer was already charged this month — no action needed
Decryption failure	File in /upload/failed, no per-record report	Re-encrypt with the correct DOKU public key and re-upload with a new filename

---

Use Cases

Insurance

	Details
Description	An insurance company collects quarterly premium payments from thousands of policyholders on the same date. Their policy management system manages all customer data and tokens internally.
Solution	On each quarterly billing date, the policy system generates a .TXT batch file with all active policyholder tokens and uploads to DOKU SFTP. DOKU processes all charges in one operation.
How It Works	System generates billing file → encrypt → upload to SFTP /download → Trigger API (optional) → DOKU processes charges → report in /upload → merchant downloads and reconciles
Features Used	Merchant Hosted Scheduler, SFTP Batch Processing, Consolidated Report

Utility

---

Merchant & Customer Experience

Merchant View

• Manage customer tokens internally — obtain via First Payment, store per customer record

• Prepare and upload batch .TXT billing file to SFTP /download folder on each billing cycle

• Optionally call Trigger API to initiate immediate processing

• Receive DOKU notification when report is ready

• Download result report from SFTP /upload folder

• Triage failed records: retry with same token (insufficient funds), or initiate new First Payment (expired/invalid token)

Customer View

• Completes a First Payment once during onboarding to authorize recurring charges

• Receives a payment success or failure notification after each charge attempt

• If card expires: goes through checkout again for a new card — merchant handles the rest

---

Terms & Conditions

• Merchants are responsible for securely storing and managing customer tokens

• Batch files must use TKN_ prefix in filename and .TXT extension — files not matching this convention will not be processed

• EXECUTE DATE must not be a past date — past dates generate per-record failures placed in /upload/failed

• SFTP access requires IP whitelisting — Connectivity & File Security

• Raw card numbers must never appear in batch files — use DOKU-issued tokens only

---

FAQ

What is a token and how do I get one?

A token is a secure reference to a customer's payment credential — it represents their card or bank account without exposing the raw numbers. Tokens are obtained by having the customer complete a First Payment through the supported payment methods (Credit Card, Direct Debit BRI, or E-Wallet OVO). After the First Payment completes, call the Get Token List API to retrieve the token bound to that customer ID. Store the token in your system — it is reusable for all future billing cycles against the same payment method.

Can I reuse the same token across multiple billing cycles?

Yes. A token is persistent and remains valid as long as the underlying payment method is active. You do not need a new token each cycle — include the same token in every batch file until the card expires, is cancelled, or the customer's payment method changes.

What happens if a customer's card expires?

The token bound to the expired card becomes invalid. The charge will fail with a token-related error in the batch report. You must initiate a new First Payment with the customer so they can register their replacement card — then call Get Token List API to obtain the new token and use it in subsequent batch files. Do not continue submitting the expired token — it will fail every cycle until replaced.

Can I retry a failed charge with the same token after an insufficient funds failure?

Yes. An insufficient funds failure does not invalidate the token — the card itself is still active, it simply lacked balance at the time of the charge attempt. You can include the same token in your next billing cycle's batch file for a retry.

What happens if I omit EXECUTE DATE from a record?

The record is executed immediately when DOKU processes the batch file. If you need charges to run on a specific future date, set EXECUTE DATE to that date in YYYYMMDD format. If you omit it entirely, the charge runs as soon as the file is processed.

What happens if EXECUTE DATE is set to a past date?

The file is placed in the SFTP /upload/failed folder and DOKU sends a failure notification to your endpoint. No charges are executed for any record in the file. Correct the EXECUTE DATE to today or a future date, re-encrypt, and re-upload with a new filename.

What happens if some records in my batch file fail but others succeed?

Record-level failures (insufficient funds, invalid token, etc.) do not affect other records in the same file. Valid records are charged; failed records are flagged in the result report with their specific error reason. Review the report to triage each failure and take the appropriate action per record.

If I don't call the Trigger API, when will DOKU process my file?

DOKU has an internal scheduler that automatically polls the SFTP /download folder at pre-defined intervals. Your file will be processed even without the Trigger API call — the trigger only allows you to initiate processing immediately rather than waiting for the next polling interval. Contact your DOKU Account Manager for the specific polling interval applicable to your account.

What does the duplicate file name error on the Trigger API mean?

The Trigger API uses the file_name as an idempotency key — the same filename cannot be submitted twice. If you receive this error, the file has already been triggered for processing. Do not resubmit. Check the SFTP /upload folder for the result report. For a new billing batch, always use a unique filename.