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
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
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:
Method
POST
POST
URL
https://api-sandbox.doku.com/ab-core-api/v1/billing-registration
https://api.doku.com/ab-core-api/v1/billing-registration
Request Headers:
Client-Id
Client ID retrieved from DOKU Back Office
Request-Id
Unique random string (max 128 characters) generated by the merchant to prevent duplicate requests
Request-Timestamp
Request timestamp in 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 the merchant backend. → Authentication
Request Body:
For order, payment, customer, shipping address, billing address, additional info object, refer to DOKU Checkout Integration Guide
Recurring Object Parameters:
billNumber
String (ANS)
✅
20
Unique bill identifier for reference. Must be unique per merchant account.
billDetail
String
Optional
—
Product or service description.
billType
Enum
Optional
—
BILLING_PAYMENT — if integrated with DOKU Switching (for utility billers). PAYMENT — standard billing.
startDate
Date
✅
—
Recurring schedule start date. ISO 8601 UTC+0 format.
endDate
Date
✅
—
Recurring schedule end date. ISO 8601 UTC+0 format.
executeType
Enum
✅
8
Determines how billing dates are defined. See Execute Type below.
executeDate
String
✅
2048
The dates on which charges are executed. Format depends on executeType. Multiple values separated by semicolons. See Execute Type.
executeMonth
String
Optional
256
Months in which charges are executed. Required when executeType is DATE. Values: JAN;FEB;MAR etc. Omit when executeType is FULLDATE.
flatStatus
Boolean
✅
5
true — fixed billing amount, DOKU uses the order.amount value. false — dynamic amount, DOKU fetches billing_amount from your URL Amount endpoint before each charge.
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.
DAY
Day abbreviations: MON / TUE / WED / THU / FRI / SAT / SUN
Not used
Charges run on specific days of the week
executeDate: "MON;THU" — charge every Monday and Thursday
DATE
Day numbers: 1 through 28
Required — list of months
Charges run on specific dates of the month, for specified months
executeDate: "5;6;7", executeMonth: "JAN;FEB;..." — charge on 5th (primary) + 6th and 7th (retry) each month
FULLDATE
Specific dates in yyyyMMdd format
Leave empty
Charges run on exact calendar dates
executeDate: "20251005;20251105" — charge only on Oct 5 and Nov 5 2025
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
Maximum date value for DATE type is 28. Day 29, 30, and 31 are not supported to ensure consistent execution across all calendar months.
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.
true
order.amount from the registration request — same every cycle
Billing amount is fixed and does not change between cycles
false
Fetched from your URL Amount endpoint before each charge
Billing amount varies per cycle — DOKU queries your system for the current value
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.
Configure the URL Amount endpoint under Settings → Account Billing → Bill Detail Setting → URL Amount.
Additionally, billType determines where DOKU fetches the dynamic amount from:
PAYMENT
DOKU fetches billing_amount from your system via the URL Amount endpoint
BILLING_PAYMENT
DOKU fetches billing_amount from DOKU Switching — used for external billers such as utility or BPJS payments
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.
API Response:
code
Response status. success indicates the bill was registered and the checkout link is ready.
paymentLink
The checkout URL to share with the customer for card registration.
HTTP 200 — Bill registered successfully, checkout link ready.
Share the paymentLink with the customer. The link takes them to the DOKU-hosted card registration checkout page.
HTTP 400 — billNumber already registered.
The billNumber passed in recurring.billNumber has already been used in a previous registration request.
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.
HTTP 401 — Signature validation 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
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.
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.
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.
Customer Registers Card and Pays Registration Fee
On the checkout page, the customer:
Enters their card details (card number, expiry, CVV, cardholder name)
Confirms and submits the form
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:
Standard Setup
startDate is a future date
Registration fee paid and voided. Billing schedule is created but idle. First real charge runs on startDate.
Immediate Setup
startDate is the same day as registration
Registration fee paid and voided. System immediately triggers the first billing fee — 2 charges occur on registration day: the voided registration fee + the first actual billing charge.
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.
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, andexecuteMonthA 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):
billing.bill_number
The billNumber from your registration request — store this as your reference for this customer's recurring billing record.
customerDetail.card_number
Masked card number for display and reconciliation purposes only.
billing.bill_type
S = standard PAYMENT, B = BILLING_PAYMENT (DOKU Switching).
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.
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.
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.
SFTP Registration Flow
Prepare data file — Generate a
.txtfile containing all customer card data and billing configurations for the batch.Encrypt and upload — Encrypt the
.txtfile using AES-256 symmetric key and upload it to the designated/downloadfolder on the DOKU SFTP server.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.
DOKU processes the file — DOKU retrieves, decrypts, and processes the registration data. Card tokens and billing schedules are created for each record.
Report generated — DOKU places a
.txtresult report in the/uploadfolder on the SFTP server and sends a notification to the merchant.Retrieve report — Merchant retrieves the report from SFTP to update internal records with registration outcomes.
→ SFTP Setup and Configuration
TXT File Format
Column definitions:
CUSTOMER ID
Alphanumeric
✅
64
Customer unique ID in the merchant's system
BILLING REF / BILLING NUMBER
Alphanumeric
✅
128
Merchant's unique ID for this billing service
DESCRIPTION
Alphanumeric
Optional
256
Billing description
CURRENCY
Alpha
✅
3
IDR
AMOUNT
Number
✅
12,2
Billing amount. No decimal: 10000. With decimal: 10000.00
CARD NUMBER
Number
✅
16
Customer's credit card number
CARD EXP DATE
Number
✅
4
Card expiry in MMYY format
CARD HOLDER NAME
Alphanumeric
Optional
128
Cardholder name as printed on card
CARD HOLDER EMAIL
ANS
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
START DATE
Number
✅
8
Billing start date in yyyyMMdd format
END DATE
Number
✅
8
Billing end date in yyyyMMdd format
EXECUTE TYPE
Alpha
✅
8
DAY, DATE, or FULLDATE — same logic as CI flow
EXECUTE DATE
Alphanumeric
✅
2048
Billing execution dates — format depends on EXECUTE TYPE, values separated by semicolons
EXECUTE MONTH
Alphanumeric
✅
256
Months for execution — required for DATE type, leave empty for FULLDATE
FLAT STATUS
Alpha
✅
5
TRUE — fixed amount. FALSE — dynamic amount fetched from URL Amount endpoint
Use Cases
Description
A SaaS platform charges customers a monthly fee automatically — customers should not need to log in and pay each month.
Solution
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.
How It Works
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.
Features Used
CI Flow, Register Bill API, Credit Card Tokenization, Payment Execution Callback
Description
A business migrating thousands of existing customers from a legacy recurring billing system to DOKU, without requiring each customer to re-register their card.
Solution
Use Merchant Initiate (MI) flow — prepare a batch .txt file with existing customer card data and upload via SFTP. DOKU processes the file and creates billing schedules for all customers in one operation.
How It Works
Prepare batch file → Encrypt and upload to SFTP → Trigger Batch API (optional) → DOKU processes registrations → Report placed on SFTP → Merchant retrieves and reconciles.
Features Used
MI Flow, SFTP Batch Registration, AES-256 Encryption
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
billNumberreturned in the Registration Callback — this is the primary reference for the customer's recurring billing recordMonitor 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
billNumberas the primary reference for each customer's recurring billing record — card tokens are managed entirely by DOKUMaximum
executeDatevalue is 28 when usingDATEtype — day 29, 30, and 31 are not supportedMI flow (SFTP batch registration) requires SFTP connectivity to be configured — Connectivity & File Security
FAQ
What is the registration fee and why is it charged?
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.
What does the customer see when the registration fee is voided?
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.
What happens if the customer's card is declined during registration?
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.
Do I need to save the card token returned after registration?
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.
What is the difference between executeType DAY, DATE, and FULLDATE?
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.
Can I configure retry dates if the charge fails on the primary billing date?
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.
Last updated
Was this helpful?