© 2026 Billplz Sdn Bhd

Auto-Deduct

Updated 19 hours ago

Auto-Deduct lets you charge a customer's card on demand using a V5 Agreement, without requiring them to enter card details each time (also known as card-on-file payments). The customer authorizes their card once through a secure Billplz page (tokenization), and you charge it whenever a payment is due via API. For the full API reference, see the V5 Agreement API documentation.

How Auto-Deduct works

Auto-Deduct uses the V5 Agreement API. The process has two parts: a one-time setup and repeatable charges.

One-time setup (tokenization)

  1. You create an Agreement via the API, providing the customer's name, email, and phone number.
  2. Billplz returns an authorize_consent_url. Redirect the customer to this URL.
  3. The customer enters their card details (card number, expiry, security code, cardholder name) on a secure Billplz-hosted page and clicks Authorize.
  4. Once authorized, the card is tokenized. Billplz stores the card securely; you receive an agreement_id with status authorised.

The customer only does this once.

Charging (Auto-Deduct)

Once an Agreement is authorized, you can charge the customer's card at any time:

  1. Create a Bill via the existing Billplz API (v3) with the amount you want to charge.
  2. Call the Auto-Deduct endpoint with the bill_id and the agreement_id.
  3. Billplz charges the tokenized card. No customer action is needed.
  4. Billplz sends a callback to the bill's callback_url with the payment result.

You decide when and how much to charge. There is no built-in scheduler; each charge is triggered by your system via API.

Stopping charges (Revoke)

To stop future charges on an Agreement, call the Revoke endpoint with the agreement_id. The Agreement status changes to revoked, the token is invalidated, and any future Auto-Deduct attempts return a 422 error.

Either the merchant or the customer can initiate a revoke. Customers can revoke from the Billplz dashboard under Settings > Credit Cards.

Agreement statuses


Status

Meaning

draft

Agreement created, customer has not yet visited the authorization page.

pending_authorisation

Customer is on the authorization page.

authorised

Customer has authorized. Card is tokenized and ready for Auto-Deduct.

failed

Authorization failed (customer rejected, card declined, or error).

revoked

Agreement revoked. Card can no longer be charged.

Who Auto-Deduct is for

Auto-Deduct is suited for merchants who charge customers repeatedly and want to remove friction from each payment:

  • Instalments: split a purchase into multiple card charges over time
  • Membership renewals: charge members monthly or annually without chasing payment
  • Repeat invoicing: charge retainer clients or regular service customers on your schedule
  • Utilities and fees: collect recurring fees (tuition, rent, contributions) from a saved card

Rates

Auto-Deduct transaction fees vary by membership tier and card origin (local vs foreign). See the Billplz pricing page for current rates.



Basic

Standard

Auto-Deduct MYR

2.3% + MYR 1.25

2% + MYR 0.75

Auto-Deduct Non-MYR

4.2% + MYR 1.25

4% + MYR 0.75

Payout

T+2 business days

T+2 business days

Limitations

  • Card only. Auto-Deduct currently supports card tokenization (billplz_card) only. FPX, Wallet, and other payment methods are not supported.
  • API only. Auto-Deduct is available through the V5 Agreement API. There is no dashboard interface for creating agreements or triggering charges.
  • No built-in scheduling. Your system triggers each charge. Billplz does not schedule or automate the timing of deductions.
  • Beta access. Auto-Deduct requires activation by Billplz. Contact [email protected] to request access.

Common issues

Was this article helpful?