Skip to content

Recurring Payments Flow

In this guide

How to create a recurring agreement, where the token comes from, and how to charge it for subscriptions or installments.

Recurring payments charge a stored card using a token created from an earlier successful payment.

Two-step setup

Recurring is always two steps: (1) an initial payment with recurringInit = true produces a token, then (2) later charges use that token with DigetPay.recurring().

sequenceDiagram
    participant App as Merchant App
    participant SDK as DigetPay SDK
    participant API as DigetPay API
    participant Backend as Merchant Backend

    App->>SDK: payWithCard(recurringInit = true)
    SDK->>API: Initial sale
    API-->>Backend: Webhook with recurring token
    Backend->>Backend: Store token + original payment id
    App->>Backend: Request next subscription charge
    Backend-->>App: Tokenized charge data
    App->>SDK: DigetPay.recurring(request, callback)
    SDK->>API: Recurring charge
    SDK-->>App: OperationCallback<RecurringResult>

Required Data

paymentId
Original successful recurring-init payment.
recurringToken
Delivered to your backend by webhook.
orderId
New order for this recurring charge.
amount
Amount to charge now.
orderNumber
Internal order number.

Charge a Recurring Token

val request = RecurringRequest(
    paymentId = "PAYMENT_ID",
    orderId = "ORDER-${System.currentTimeMillis()}",
    recurringToken = "RECURRING_TOKEN_FROM_WEBHOOK",
    amount = 125.0,
    currency = "SAR",
    orderNumber = "REC-${System.currentTimeMillis()}",
    orderDescription = "Monthly subscription"
)

DigetPay.recurring(
    request = request,
    callback = operationCallback { result ->
        val status = result.status
        val transactionId = result.transactionId
    }
)

RecurringRequest request = new RecurringRequest(
    "PAYMENT_ID",
    "ORDER-" + System.currentTimeMillis(),
    "RECURRING_TOKEN_FROM_WEBHOOK",
    125.0,
    "SAR",
    "REC-" + System.currentTimeMillis(),
    "Monthly subscription"
);

DigetPay.recurring(
    request,
    operationCallback(result -> {
        String status = result.getStatus();
        String transactionId = result.getTransactionId();
    })
);

Important

Store recurring tokens on your backend, not only on the device. The backend should remain the source of truth for subscription state and webhook reconciliation.