Payment Gateway SDK — Android

The SDK provides a single entry point through DigetPay for hosted checkout, card payments, recurring payments, transaction operations, and payment result handling.

Requirements

Installation

The DigetPay Android SDK is distributed as an AAR.

Add the SDK to your application and include its required runtime dependencies in your app module.

The AAR does not embed its transitive runtime dependencies, including Retrofit, OkHttp, Coroutines, and AndroidX. Make sure these dependencies are available in your application before using the SDK.

Quick Start

1. Initialize the SDK

Initialize DigetPay once before starting a payment:

DigetPay.initialize(
context = this,
config = DigetPayConfig(
apiKey = "YOUR_API_KEY",
environment = Environment.SANDBOX,
enableLogging = BuildConfig.DEBUG
)
)

Use Environment.SANDBOX while testing and Environment.PRODUCTION for live payments.

Use a mobile-restricted or publishable API key in the application. Never embed a server secret or privileged credential in the Android application.

2. Start Hosted Checkout

Hosted Checkout is the recommended payment flow.

DigetPay.checkout(
activity = this,
request = CheckoutRequest(
merchantOrderId = "ORDER-123",
amount = 125.0,
currency = "SAR",
customerName = "Ahmed Ali",
customerEmail = "[[email protected]](mailto:[email protected])",
customerPhone = "+966501234567"
),
callback = object : PaymentCallback \{

override fun onSuccess(result: PaymentResult) {
actionId.


override fun onFailure(error: PaymentError) {



override fun onCancelled() {
checkout screen.

}
)

The SDK opens the DigetPay-hosted checkout screen, handles the payment flow and 3-D Secure challenge, and returns the final result through PaymentCallback.

Recommended Payment Flow

The standard hosted checkout flow is:

1. Initialize the SDK using DigetPay.initialize().
2. Create a checkout using DigetPay.checkout().
3. Customer completes payment on the DigetPay-hosted checkout screen.
4. SDK verifies the final result and returns it through PaymentCallback.
5. Verify the transaction on your backend before fulfilling the order.

For a successful payment, store the relevant identifiers such as:

• sessionId
• transactionId
• merchantOrderId

Do not rely only on the visual success page. Your backend should verify the final transaction status before marking an order as paid.

Payment Flows

Hosted Checkout

Hosted Checkout keeps the payment experience on DigetPay's hosted payment page.

The SDK handles:

• Checkout initialization
• Hosted payment screen
• Customer payment
• 3-D Secure
• Redirect handling
• Final payment result
• Success, failure, and cancellation callbacks

This is the recommended flow for most Android integrations.

Card Payment

The SDK also supports direct card payments.

This flow collects card information inside the application and submits the payment through the SDK.

Because raw card data is handled by the application, this integration increases your PCI-DSS responsibilities.

Prefer Hosted Checkout unless your integration has been assessed for the required PCI-DSS scope.

Recurring Payments

The SDK supports recurring payment flows and payment tokenization for subsequent charges.

Use recurring functionality only when the required customer consent, token handling, and backend controls are implemented correctly.

Callbacks & Results

Payment results are delivered through PaymentCallback.

Operation requests such as capture, void, and refund use OperationCallback.

Always handle all callback outcomes and avoid treating a missing callback as a successful payment.

Payment Operations

The SDK supports common transaction operations, including:

For payment lifecycle operations, keep the transaction identifiers on your backend and use your server-side integration for business-critical order state management.

SDK Components

The main SDK components include:

Environment Configuration

Use the appropriate environment when initializing the SDK:

Environment.SANDBOX

for testing, and:

Environment.PRODUCTION

for live transactions.

Keep environment selection configurable so that test builds do not accidentally use production credentials.

Security

API Keys

The Android application contains credentials that can potentially be extracted from the APK.

For this reason:

• Use a mobile-restricted or publishable API key.
• Never embed a server secret in the application.
• Do not hard-code privileged backend credentials.
• Rotate a key if it is exposed.
• Keep sensitive and privileged operations behind your backend.

Card Data

Hosted Checkout is preferred because card details are entered on the DigetPay-hosted payment page.

If you use direct card payment, your application handles raw card information and your PCI-DSS scope is increased.

Transaction Verification

Do not fulfill an order based only on the client-side callback.

Your backend should verify the transaction and maintain the authoritative order state.

Versioning & Compatibility

Current SDK Version

Platform Support

Future SDK releases may increase the minimum supported Android or build-tool versions. Check the release notes before upgrading.

Logging

Logging can be enabled during development:

enableLogging = BuildConfig.DEBUG

Keep SDK logging disabled in production unless it is specifically required for troubleshooting.

Never log sensitive payment credentials or raw card information in your own application logs.

Error Handling

DigetPay provides structured payment and operation errors.

Handle errors based on their returned error information rather than assuming every failure is a network failure.

Recommended handling:

1. Display a user-friendly message.
2. Record the technical error on your backend where appropriate.
3. Allow the customer to retry when the error is recoverable.
4. Verify the transaction status before retrying an uncertain payment.

Android Permissions

The SDK requires network access to communicate with DigetPay services.

Make sure your application has the required Internet permission in its Android configuration:

    <uses-permission android:name="android.permission.INTERNET" />

Best Practices

• Initialize the SDK once during application startup.
• Use Sandbox for development and testing.
• Use Hosted Checkout as the default payment flow.
• Never expose server secrets in the mobile application.
• Store sessionId, transactionId, and order identifiers on your backend.
• Verify successful payments server-side.
• Do not log raw card data or sensitive credentials.
• Keep the SDK updated to supported releases.
• Test success, failure, cancellation, and 3-D Secure scenarios before production.

Related

• Payment Gateway Mobile SDKs
• Payment Gateway SDK — Flutter
• Hosted Checkout