Skip to content

Card Payment Flow

In this guide

The server-to-server card flow, authorize-then-capture, and recurring initialization.

DigetPay.payWithCard() starts a server-to-server card payment from the device. Use it only when your app is designed to handle card data and the related PCI DSS responsibility.

sequenceDiagram
    participant App as Merchant App
    participant SDK as DigetPay SDK
    participant API as DigetPay API
    participant ThreeDS as 3-D Secure

    App->>SDK: payWithCard(activity, request, callback)
    SDK->>SDK: Generate request hash
    SDK->>API: S2S sale request
    API-->>SDK: Sale response or 3DS HTML
    SDK->>ThreeDS: Open authentication page
    ThreeDS-->>SDK: Redirect outcome
    SDK-->>App: PaymentCallback result

PCI scope

This flow sends full card data from the Android app. Prefer hosted checkout unless you have a clear compliance reason to use direct card payment.

Sale Request

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
)

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
);

Authorization Then Capture

Set auth = true to reserve funds first. Capture later using DigetPay.capture().

When to authorize first

Use authorize-then-capture when you ship or confirm goods later (for example, stock checks or delayed fulfillment). Capture the exact or a lower amount.

val authRequest = request.copy(auth = true)

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

Recurring Initialization

Set recurringInit = true on the first successful sale to start a recurring agreement. The recurring token is normally delivered to your backend through webhook.

val recurringInitRequest = request.copy(
    recurringInit = true,
    auth = false
)

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