Operations¶

In this guide

Every SDK action beyond hosted checkout: S2S card payment, status checks, capture, void, refund, merchant transactions, and recurring charges.

Operations are SDK actions such as S2S card payment, status checks, capture, void, refund, and recurring charges.

Two callback types

payWithCard() is interactive — it can open a 3-D Secure screen and returns through PaymentCallback. Every other operation on this page returns through OperationCallback<T>.

paymentId is the checkout sessionId

For status, capture, void, and refund, pass the sessionId from the original PaymentResult as the paymentId.

Callback Helpers¶

The examples below use small callback helpers to keep each operation focused.

KotlinJava

private fun paymentCallback() = object : PaymentCallback {
    override fun onSuccess(result: PaymentResult) {
        // Store IDs and update your order state.
    }

    override fun onFailure(error: PaymentError) {
        // Show error.message and log error.code.
    }

    override fun onCancelled() {
        // Let the user retry.
    }
}

private fun <T> operationCallback(onSuccess: (T) -> Unit) =
    object : OperationCallback<T> {
        override fun onSuccess(result: T) = onSuccess(result)
        override fun onFailure(error: PaymentError) {
            // Handle operation errors.
        }
    }

import java.util.function.Consumer;

private PaymentCallback paymentCallback() {
    return new PaymentCallback() {
        @Override
        public void onSuccess(PaymentResult result) {
            // Store IDs and update your order state.
        }

        @Override
        public void onFailure(PaymentError error) {
            // Show error.getMessage() and log error.getCode().
        }

        @Override
        public void onCancelled() {
            // Let the user retry.
        }
    };
}

private static <T> OperationCallback<T> operationCallback(Consumer<T> onSuccess) {
    return new OperationCallback<T>() {
        @Override
        public void onSuccess(T result) {
            onSuccess.accept(result);
        }

        @Override
        public void onFailure(PaymentError error) {
            // Handle operation errors.
        }
    };
}

S2S Card Payment¶

Use DigetPay.payWithCard() when the app collects card details and sends them through the SDK.

KotlinJava

val request = CardPaymentRequest(
    orderId = "ORDER-${System.currentTimeMillis()}",
    amount = 125.0,
    currency = "SAR",
    customer = Customer(
        name = "Ahmed Ali",
        email = "ahmed@example.com",
        phone = "+966501234567"
    ),
    card = Card(
        cardNumber = "4111111111111111",
        cardHolder = "AHMED ALI",
        cardExpiryMonth = "08",
        cardExpiryYear = "2028",
        cardCvv = "123"
    ),
    auth = false,
    recurringInit = false
)

DigetPay.payWithCard(
    activity = this,
    request = request,
    callback = paymentCallback()
)

Customer customer = new Customer(
    "Ahmed Ali",
    "ahmed@example.com",
    "+966501234567",
    "",
    "",
    ""
);

Card card = new Card(
    "4111111111111111",
    "AHMED ALI",
    "08",
    "2028",
    "123"
);

CardPaymentRequest request = new CardPaymentRequest(
    "ORDER-" + System.currentTimeMillis(),
    125.0,
    "SAR",
    customer,
    card,
    false,
    false,
    CheckoutRequest.DEFAULT_SUCCESS_URL,
    CheckoutRequest.DEFAULT_FAILURE_URL
);

DigetPay.payWithCard(this, request, paymentCallback());

Warning

S2S card payment sends full card data from the device. Use hosted checkout unless your app is ready for the compliance and security responsibility.

S2S Payment With Recurring Init¶

To make the first S2S payment start a recurring agreement, set recurringInit = true.

KotlinJava

val recurringInitRequest = CardPaymentRequest(
    orderId = "ORDER-${System.currentTimeMillis()}",
    amount = 125.0,
    currency = "SAR",
    customer = customer,
    card = card,
    auth = false,
    recurringInit = true
)

DigetPay.payWithCard(
    activity = this,
    request = recurringInitRequest,
    callback = paymentCallback()
)

CardPaymentRequest recurringInitRequest = new CardPaymentRequest(
    "ORDER-" + System.currentTimeMillis(),
    125.0,
    "SAR",
    customer,
    card,
    false,
    true,
    CheckoutRequest.DEFAULT_SUCCESS_URL,
    CheckoutRequest.DEFAULT_FAILURE_URL
);

DigetPay.payWithCard(this, recurringInitRequest, paymentCallback());

After this payment succeeds, store the original paymentId and the recurringToken delivered to your backend by webhook. Use both later with DigetPay.recurring().

Transaction Status¶

Use the checkout sessionId as paymentId.

KotlinJava

DigetPay.getTransactionStatus(
    paymentId = "PAYMENT_ID",
    callback = operationCallback { result ->
        val status = result.paymentStatus ?: result.transactionStatus
        val orderId = result.orderId
        val declineReason = result.declineReason
    }
)

DigetPay.getTransactionStatus(
    "PAYMENT_ID",
    operationCallback(result -> {
        String status = result.getPaymentStatus() != null
            ? result.getPaymentStatus()
            : result.getTransactionStatus();
        String orderId = result.getOrderId();
        String declineReason = result.getDeclineReason();
    })
);

Capture¶

Capture a payment that was authorized with auth = true.

Use PaymentResult.sessionId as paymentId.

Authorize first

Capture only works on payments created with auth = true. A normal sale is already captured and cannot be captured again.

KotlinJava

DigetPay.capture(
    paymentId = "PAYMENT_ID",
    amount = 125.0,
    callback = operationCallback { result ->
        val status = result.status
        val message = result.message
    }
)

DigetPay.capture(
    "PAYMENT_ID",
    125.0,
    operationCallback(result -> {
        String status = result.getStatus();
        String message = result.getMessage();
    })
);

Void¶

Void a payment before it is settled.

Use PaymentResult.sessionId as paymentId.

Void vs. Refund

Use void to cancel a payment before settlement, and refund after it settles. A payment can be voided only while it is still unsettled.

Java naming

Java callers must use DigetPay.voidPayment(...) because void is a reserved keyword in Java.

KotlinJava

DigetPay.void(
    paymentId = "PAYMENT_ID",
    callback = operationCallback { result ->
        val status = result.status
    }
)

DigetPay.voidPayment(
    "PAYMENT_ID",
    operationCallback(result -> {
        String status = result.getStatus();
    })
);

Refund¶

Refund all or part of a settled payment.

Use PaymentResult.sessionId as paymentId.

KotlinJava

DigetPay.refund(
    paymentId = "PAYMENT_ID",
    amount = 50.0,
    callback = operationCallback { result ->
        val refundId = result.refundId
        val message = result.message
    }
)

DigetPay.refund(
    "PAYMENT_ID",
    50.0,
    operationCallback(result -> {
        String refundId = result.getRefundId();
        String message = result.getMessage();
    })
);

Merchant Transactions¶

Fetch merchant-wide POS transactions.

KotlinJava

DigetPay.getMerchantTransactions(
    page = 1,
    pageSize = 50,
    dateFrom = "2026-01-01",
    dateTo = "2026-01-31",
    status = "SUCCESS",
    callback = operationCallback { result ->
        val transactions = result.items
        val total = result.pagination?.total
    }
)

DigetPay.getMerchantTransactions(
    1,
    50,
    "2026-01-01",
    "2026-01-31",
    "SUCCESS",
    operationCallback(result -> {
        List<MerchantTransaction> transactions = result.getItems();
        Integer total = result.getPagination() != null
            ? result.getPagination().getTotal()
            : null;
    })
);

Recurring Transactions¶

Fetch available recurring records and read the paymentId source record plus the recurringToken values needed to run the next recurring charge.

KotlinJava

DigetPay.getRecurringTransactions(
    callback = operationCallback { result ->
        result.data.forEach { transaction ->
            val token = transaction.recurringToken
            val paymentId = transaction.transactionId
        }
    }
)

DigetPay.getRecurringTransactions(
    operationCallback(result -> {
        for (RecurringTransaction transaction : result.getData()) {
            String token = transaction.getRecurringToken();
            String paymentId = transaction.getTransactionId();
        }
    })
);

Run Recurring Charge¶

Use DigetPay.recurring() to charge a stored recurring token. This is the actual recurring payment operation after the first S2S payment was created with recurringInit = true.

KotlinJava

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
        val message = result.message
    }
)

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();
        String message = result.getMessage();
    })
);

The values come from the recurring setup flow:

paymentId: Original payment created with recurringInit = true.
recurringToken: Delivered to your backend by webhook after the initial payment.
orderId: New order id for this recurring charge.
orderNumber: Your internal recurring order number.

Card data safety

S2S card payment sends full card data from the device. Prefer Hosted Checkout unless your app is ready for the PCI DSS compliance and security responsibility. Never log card fields.