# Integration Guide

Integrate the Finix Payment Sheet Android SDK into your own Android app.

**Before you start**, complete the [Getting Started](/android/online/getting-started) guide. You'll need:

- A Finix Application ID (`APxxxxxxxxxxxxx`) for each environment you plan to use.
- API credentials (username and password) if you plan to enable 3D Secure.
- An approved merchant with a Merchant ID (`MUxxxxxxxxxxxxx`) if you plan to enable 3D Secure.


The [Demo App Walkthrough](/android/online/demo-app-walkthrough) is optional but recommended as a working reference before you build your own integration.

## 1. Collect your SDK values

Collect the values specified in the [Getting Started guide](/android/online/getting-started) before you initialize the SDK and start making API calls from your backend. Gather one set of values per environment (Sandbox for development, Production for launch); you'll swap the Production set in when you go live.

Your `applicationId` and the credentials your backend uses must all belong to the same Finix environment. Mixing environments is a common cause of authentication and token errors.

Keep API credentials off the client when possible
API credentials embedded in an APK can be extracted. For the normal tokenization flow the SDK only needs the Application ID - keep your API username and password on your backend and have the backend create Payment Instruments from the tokens returned by the SDK.

Enabling 3D Secure is the exception: the SDK calls `/3d_secure_sessions` directly from the device, so the 3DS-enabled [PaymentSheetConfiguration](/android/online/configuration) requires `merchantId`, `apiUsername`, and `apiPassword`. See [Step 9](#9-enable-3d-secure-optional). Treat those credentials as Sandbox-only or use a scoped, rotatable key for mobile use.

## 2. Install and configure the SDK

### System requirements

| Requirement | Value |
|  --- | --- |
| `minSdk` | 26 |
| `targetSdk` | 36 |
| `compileSdk` | 36 |
| `Compose plugin` | 2.3.0 |
| `Compose Material3` | 1.4.0 |
| `JVM target` | 11 |


### Add the SDK dependency

The library is on [Maven Central](https://central.sonatype.com/artifact/com.finix/finix-android-payment-sheet). Declare the coordinate in your version catalog and reference it from the app module.

```toml gradle/libs.versions.toml
[versions]
finixPaymentSheet = "0.4.7"

[libraries]
finix-android-payment-sheet = { group = "com.finix", name = "finix-android-payment-sheet", version.ref = "finixPaymentSheet" }
```

```groovy app/build.gradle
dependencies {
    implementation libs.finix.android.payment.sheet
}
```

### Configure Jetpack Compose

The SDK is distributed as Compose composables. Apply the Kotlin Compose plugin and enable the `compose` build feature on the app module.

```groovy settings.gradle
pluginManagement {
    plugins {
        id "org.jetbrains.kotlin.plugin.compose" version "2.3.0"
    }
}
```

```groovy app/build.gradle
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.plugin.compose'
}

android {
    compileSdk 36
    defaultConfig {
        minSdk 24
        targetSdk 36
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    buildFeatures {
        compose true
    }
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_11
    }
}
```

### Build a PaymentSheetConfiguration

Build one [PaymentSheetConfiguration](/android/online/configuration) carrying your Application ID and environment. You'll pass it into the payment sheet composable in [Step 4](#4-present-the-payment-sheet).

```kotlin
val configuration = PaymentSheetConfiguration(
    applicationId = "APxxxxxxxxxxxxx",
    environment = PaymentSheetEnvironment.SANDBOX, // use PaymentSheetEnvironment.LIVE for production
    merchantId = null,
    apiUsername = null,
    apiPassword = null,
    threeDSConfiguration = null, // populate in Step 9 to enable 3DS
)
```

## 3. Pick a form type

The SDK ships five form types, each in two visual styles - see the [Form Types](/android/online/form-types) reference for the field matrix. The call shape is identical for every variant; swap the function name to choose a different form.

| Variant | Collects |
|  --- | --- |
| `CompletePaymentSheet` | Name, Card Number, Expiry, CVV, Full Address |
| `PartialPaymentSheet` | Name, Card Number, Expiry, CVV, Zip Code |
| `BasicPaymentSheet` | Name, Card Number, Expiry, CVV |
| `MinimalPaymentSheet` | Card Number, Expiry, CVV |
| `InternationalPaymentSheet` | Name, Card Number, Expiry, Country, Zip Code |


Each variant also has an `*Outlined` cousin (e.g. `CompletePaymentSheetOutlined`) that renders field borders only on focus. See [Form Types](/android/online/form-types) for how the styles compare.

Pick the smallest form that collects the data your checkout needs:

- Use **Complete** when you need full address data for AVS verification.
- Use **Partial** for lightweight Zip-Code-only verification.
- Use **Basic** or **Minimal** for simple card collection with no address fields.
- Use **International** for buyers outside the US.


## 4. Present the Payment Sheet

The payment sheet is a Compose composable. You call it from inside your own composable, gated behind a `Boolean` state flag that each callback resets so the sheet is removed from composition when the buyer interacts with it.

Below is a minimal `Checkout` composable: a button that opens the sheet, plus the SDK call rendered only while `showSheet` is `true`. Replace the placeholder `Hello()` composable in your `MainActivity.kt` with this, passing in the `configuration` you built in [Step 2](#build-a-paymentsheetconfiguration).

```kotlin MainActivity.kt
@Composable
fun Checkout(configuration: PaymentSheetConfiguration) {
    var showSheet by remember { mutableStateOf(false) }

    Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
        Button(onClick = { showSheet = true }) {
            Text("Pay $10.00")
        }
    }

    if (showSheet) {
        CompletePaymentSheet(
            configuration = configuration,
            amount = 1000L,   // $10.00 in cents - smallest currency unit
            currency = "USD",
            onCancel = {
                showSheet = false
            },
            onSuccess = { response ->
                // handle the tokenized result - see Step 5
                showSheet = false
            },
            onFailure = { error ->
                // see the Error Reference
                showSheet = false
            },
        )
    }
}
```

Then wire it into `setContent`:

```kotlin MainActivity.kt
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
        val configuration = PaymentSheetConfiguration(
            applicationId = "APxxxxxxxxxxxxx",
            environment = PaymentSheetEnvironment.SANDBOX,
            merchantId = null,
            apiUsername = null,
            apiPassword = null,
            threeDSConfiguration = null,
        )
        MaterialTheme {
            Surface(Modifier.fillMaxSize()) {
                Checkout(configuration)
            }
        }
    }
}
```

That's enough to render a button that opens the Finix payment sheet when tapped. See the [PaymentSheet](/android/online/payment-sheet) reference for the full parameter list, and the demo app's [`AddCardScreen.kt`](https://github.com/finix-payments/finix-android-payment-sheet-app/blob/main/app/src/main/java/com/finix/sampletokenize/ui/compose/addCard/AddCardScreen.kt) for a richer pattern using a `ViewModel` that tracks multiple sheet variants.

## 5. Get the Token

The `onSuccess` callback fires with a [PaymentSheetResponse](/android/online/token-response) carrying a nested `TokenizedResponse`. `response.tokenizedResponse.id` is the token you forward to your backend to create a Payment Instrument.

Fill in the `onSuccess` body from [Step 4](#4-present-the-payment-sheet):

```kotlin
onSuccess = { response ->
    val tokenId = response.tokenizedResponse.id
    // forward tokenId to your backend for Step 7
    showSheet = false
},
```

Handle `onFailure` by branching on the [FinixErrorCode](/android/online/errors) variants and surfacing `code.message` to the buyer:

```kotlin
onFailure = { code ->
    when (code) {
        FinixErrorCode.NetworkError,
        FinixErrorCode.Timeout,
        FinixErrorCode.PaymentFailed -> {
            // surface code.message to the buyer
        }
        is FinixErrorCode.MissingConfiguration -> {
            // bug in your integration - code.field names the missing field
        }
        is FinixErrorCode.ThreeDSFailed -> {
            // 3DS failed - no liability shift, do not charge
        }
        is FinixErrorCode.Unknown -> {
            // surface code.message to the buyer
        }
    }
    showSheet = false
},
```

Token Expiration
Tokens expire **30 minutes** after creation. Use the token to create a Payment Instrument as soon as your backend receives it.

If you enabled [3D Secure](#9-enable-3d-secure-optional), `response.threeDSResponse?.sessionId` is populated on successful authentication - forward it alongside the token so your backend can reference the authenticated session when creating the Payment Instrument or Authorization.

## 6. Use a Buyer Identity

A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one.

Buyer Identity data
All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier.

Use an existing Buyer
To find and reuse an existing Buyer Identity:

1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login).
2. In the left sidebar, select **Data Resources** → **Identities**.
3. Search for the Buyer Identity you want to use, and confirm its **Role** is **Buyer**.
4. Copy the Buyer Identity ID (for example, `IDjWktr7BPDGhz4amrPJZoXg`).


Create a new Buyer
Send a `POST` request to POST /identities with the `BUYER` role to create a new Buyer Identity.

```shell Buyer Identity Request
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "entity": {
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "finix_example@finix.com",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      }
    },
    "identity_roles": [
      "BUYER"
    ],
    "tags": {
      "key": "value"
    },
    "type": "PERSONAL"
  }'
```

A successful request returns the Buyer Identity. Copy its `id` to use in the following steps.

```json Buyer Identity Response
{
  "id": "IDmkDvJfxZWMEK56FDFtbozo",
  "created_at": "2024-08-09T09:34:36.87Z",
  "updated_at": "2024-08-09T09:34:36.87Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    "ach_max_transaction_amount": 0,
    "amex_mid": null,
    "annual_card_volume": 0,
    "business_address": null,
    "business_name": null,
    "business_phone": null,
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": null,
    "discover_mid": null,
    "dob": null,
    "doing_business_as": null,
    "email": "finix_example@finix.com",
    "first_name": "John",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Smith",
    "max_transaction_amount": 0,
    "mcc": null,
    "ownership_type": null,
    "personal_address": {
      "line1": "741 Douglass St",
      "line2": "Apartment 7",
      "city": "San Mateo",
      "region": "CA",
      "postal_code": "94114",
      "country": "USA"
    },
    "phone": "7145677613",
    "principal_percentage_ownership": null,
    "short_business_name": null,
    "tax_authority": null,
    "tax_id_provided": false,
    "title": null,
    "url": null
  },
  "identity_roles": [
    "BUYER"
  ],
  "tags": {
    "key": "value"
  },
  "type": "PERSONAL",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/verifications"
    },
    "merchants": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/merchants"
    },
    "settlements": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/settlements"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/transfers"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/payment_instruments"
    },
    "associated_identities": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/associated_identities"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/disputes"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}
```

## 7. Create a Payment Instrument with Finix

After tokenization, use the returned token to create a Payment Instrument. Pass the token in the `token` field and set `type` to `TOKEN`.

```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
    "token": "TKiMxe323RE5Dq3wLVtG8kSW",
    "type": "TOKEN"
  }'
```

A successful request returns the newly created Payment Instrument. Copy its `id`; you'll use it to process the payment.

Payment Instrument - Token - Card
```json Payment Instrument - Token - Card
{
  "id": "PImmCg3Po7oNi7jaZcXhfkEu",
  "created_at": "2022-10-10T05:32:17.78Z",
  "updated_at": "2022-10-10T05:32:17.78Z",
  "account_updater_enabled": false,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "instrument_type": "PAYMENT_CARD",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "UNKNOWN",
  "bin": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "USA",
  "last_four": "8210",
  "name": "Amy White",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "UNKNOWN",
  "tags": {
    "card_name": "Business Card"
  },
  "type": "PAYMENT_CARD",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    },
    "updates": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates"
    }
  }
}
```

## 8. Process a payment

With the Payment Instrument created, charge the buyer by creating a Transfer (immediate sale) or an Authorization (reserve funds now, capture later). In both cases, set `source` to the Payment Instrument ID from [Step 7](#7-create-a-payment-instrument-with-finix) and set `merchant` to an `APPROVED` Merchant ID.

### Transfer

Create a Transfer to charge the buyer immediately. Funds move from the Payment Instrument to your merchant in a single call.

Example
```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "source": "PI6iQcTtJNCS8GZAVKYi5Ueb"
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/createTransferMinimalFields",
  "components": {
    "schemas": {
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "source": {
        "type": "string",
        "example": "PIxxxxxxxxxxxxxxxxxx",
        "description": "ID of the `Payment Instrument` where funds get debited."
      },
      "createTransferMinimalFields": {
        "title": "Transfer - Minimal Fields",
        "type": "object",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "merchant": {
            "type": "string",
            "description": "The ID of the `Merchant` under which to create the `Transfer`."
          },
          "source": {
            "$ref": "#/components/schemas/source"
          }
        },
        "required": [
          "amount",
          "currency",
          "merchant",
          "source"
        ]
      }
    }
  }
}
```

A successful request returns the Transfer with its current `state`.

Transfer - Minimal Fields
```json Transfer - Minimal Fields
{
  "id": "TRhGHpgpTkFhNVNQsDX6QdfD",
  "created_at": "2026-09-25T20:06:00.46Z",
  "updated_at": "2026-09-25T20:06:00.46Z",
  "3d_secure_session": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 10000,
  "amount_requested": 10000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "destination": null,
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "153601",
    "acquirer_reference_number": null
  },
  "operation_key": "CARD_NOT_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "processed_at": "2026-09-25T20:06:00.81Z",
  "raw": null,
  "ready_to_settle_at": "2026-09-26T20:06:00.46Z",
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "split_transfers": [],
  "state": "SUCCEEDED", // [!code highlight]
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {},
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "515841cd-5305-409e-90fe-cfa711b3bb10",
  "type": "DEBIT", // [!code highlight]
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhGHpgpTkFhNVNQsDX6QdfD"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhGHpgpTkFhNVNQsDX6QdfD/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhGHpgpTkFhNVNQsDX6QdfD/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRhGHpgpTkFhNVNQsDX6QdfD"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhGHpgpTkFhNVNQsDX6QdfD/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj"
    }
  }
}
```

### Authorization

Create an Authorization to reserve funds now, then capture them later (for example, after you ship the order). Use the same `source` and `merchant` as a Transfer.

Example
```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "source": "PIkxmtueemLD6dN9ZoWGHT44"
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/createAuthorizationMinimalFields",
  "components": {
    "schemas": {
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "source": {
        "type": "string",
        "example": "PIxxxxxxxxxxxxxxxxxx",
        "description": "ID of the `Payment Instrument` where funds get debited."
      },
      "createAuthorizationMinimalFields": {
        "title": "Authorization - Minimal Fields",
        "type": "object",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "merchant": {
            "type": "string",
            "description": "The ID of the `Merchant` that the `Authorization` was created under."
          },
          "source": {
            "$ref": "#/components/schemas/source"
          }
        },
        "required": [
          "amount",
          "currency",
          "merchant",
          "source"
        ]
      }
    }
  }
}
```

A successful request returns an Authorization in the `SUCCEEDED` state with funds reserved but not yet captured. Copy its `id`; you'll pass it to the capture call below.

Authorization - Minimal Fields
```json Authorization - Minimal Fields
{
  "id": "AUibEDBG2DzmPJ3L75pxfFu2",
  "created_at": "2026-09-25T20:05:04.31Z",
  "updated_at": "2026-09-25T20:05:04.31Z",
  "3d_secure_session": null,
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 10000,
  "amount_requested": 10000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "expires_at": "2026-10-05T20:05:04.31Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "766600"
  },
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {},
  "trace_id": "72e93698-4cd9-4ccd-bb1c-a965fb5c9cef",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUibEDBG2DzmPJ3L75pxfFu2"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    }
  }
}
```

#### Capture the Authorization

Send a PUT /authorizations/{id} with the `capture_amount` (in cents) to settle the Authorization. The capture produces a Transfer referenced by the Authorization's `transfer` field.

Example
```shell cURL
curl -i -X PUT \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/authorizations/AUrEnGqdBi5oJs68ChNRcHJ3 \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "capture_amount": 100,
    "fee": 0
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/captureAuthorization",
  "components": {
    "schemas": {
      "capture_amount": {
        "type": "integer",
        "format": "int64",
        "description": "The amount of the  `Authorization`  you would like to capture in cents. Must be less than or equal to the `amount` of the `Authorization`."
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "split_transfers": {
        "type": "array",
        "nullable": true,
        "description": "An array used to detail how funds from the `Transfer` will split and the amount `Merchants` receive.\n\nRules:\n- The combined `amounts` under `split_transfers` must be equal to the `amount` submitted in the parent `Transfer.`\n- Merchants can be based in the United States or Canada.\n- The amount type must be `FIXED`.\n\nFor more information, see:\n- [Split Transactions](../../../../guides/online-payments/payment-features/split-transactions).\n",
        "items": {
          "type": "object",
          "nullable": true,
          "properties": {
            "merchant": {
              "type": "string",
              "description": "- The ID of the `Merchant` that will receive the specified `amount` under the `split_transfers` object.\n- In Split Transactions, the merchants specified in the `split_transfers` object are the ancillary merchants.",
              "nullable": false
            },
            "amount": {
              "type": "integer",
              "format": "int64",
              "description": "- The amount of funds that get split and paid out to the specified `Merchant`.\n- Must be less than or equal to the `amount` of the `Transfer.`",
              "nullable": false
            },
            "fee": {
              "type": "integer",
              "description": "- A processing fee is deducted when the `Merchant` receives their payout, specified in cents.\n- Must be less than or equal to the total amount being split for the designated `Merchant`.\n- By default, this fee is set to `0`.\n",
              "nullable": true
            },
            "tags": {
              "nullable": true,
              "allOf": [
                {
                  "$ref": "#/components/schemas/tags"
                }
              ]
            }
          }
        }
      },
      "captureAuthorization": {
        "title": "Capture Authorization",
        "type": "object",
        "properties": {
          "capture_amount": {
            "$ref": "#/components/schemas/capture_amount"
          },
          "fee": {
            "type": "integer",
            "format": "int64",
            "description": "The minimum amount of the `Authorization` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount`).\n- If the fees applied by the 'Fee Profile' are ***higher*** than the value passed in 'fee', 'fee' will not be applied and have no effect.\n- If the fees applied by the 'Fee Profile' are ***lower*** than the value passed in 'fee', an additional fee is be applied, in addition to the fees generated by the `Fee Profile`.\n- The additional fee is equal to the difference between the value passed in 'fee' and the fees generated by the `Fee Profile`."
          },
          "split_transfers": {
            "description": "- An array used to detail how funds for the created `Transfer` will split and the amount `Merchants` receive.\n- The combined `amounts` under `split_transfers` must be equal to or less than the `amount` submitted in the `Authorization`.\n- For more information, see [Split Transactions](../../../../guides/online-payments/payment-features/split-transactions).",
            "allOf": [
              {
                "$ref": "#/components/schemas/split_transfers"
              }
            ]
          }
        },
        "required": [
          "capture_amount"
        ]
      }
    }
  }
}
```

Captured Authorization
```json Captured Authorization
{
  "id": "AUbWeT4YfQRgjKwfXk1pwb5E",
  "created_at": "2026-09-25T20:36:20.39Z",
  "updated_at": "2026-09-25T20:36:21.28Z",
  "3d_secure_session": null,
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 10000,
  "amount_requested": 10000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "expires_at": "2026-10-05T20:36:20.39Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "004086"
  },
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED", // [!code highlight]
  "supplemental_fee": null,
  "tags": {},
  "trace_id": "6aa71f62-504c-40e3-8598-c074f98b3183",
  "transfer": "TRj2ac3ocT3UKfSCvNt2eGFr", // [!code highlight]
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUbWeT4YfQRgjKwfXk1pwb5E"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "transfer": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRj2ac3ocT3UKfSCvNt2eGFr"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    }
  }
}
```

For the full lifecycle, including voids and partial captures, see [Creating and capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures).

## 9. Enable 3D Secure (Optional)

Enable [3D Secure (3DS)](/guides/online-payments/fraud-and-risk/3d-secure) to run cardholder authentication after tokenization. 3DS adds a session, an optional WebView challenge, and liability-shift metadata to the token response.

Build a [ThreeDSConfiguration](/android/online/configuration#threedsconfiguration) and attach it to `PaymentSheetConfiguration`. When 3DS is enabled, `merchantId`, `apiUsername`, and `apiPassword` are required on `PaymentSheetConfiguration` - the SDK uses them to call `/3d_secure_sessions` from the device.

```kotlin
val configuration = PaymentSheetConfiguration(
    applicationId = "APxxxxxxxxxxxxx",
    environment = PaymentSheetEnvironment.SANDBOX,
    merchantId = "MUxxxxxxxxxxxxx",
    apiUsername = "USxxxxxxxxxxxxx",
    apiPassword = "your-api-password",
    threeDSConfiguration = ThreeDSConfiguration(
        isEnabled = true,
        redirectScheme = "myapp",   // bare scheme, no "://"
    ),
)
```

`redirectScheme` is a bare custom URL scheme that identifies your app. The SDK appends `://3ds-complete` and intercepts the full URL inside its own WebView when the issuer's challenge page redirects.

No AndroidManifest changes required
The redirect does not leave the SDK's WebView, so no `<intent-filter>` in your `AndroidManifest.xml` is required. Use any non-web scheme (not `http` or `https`).

On success, inspect `response.threeDSResponse?.sessionId` from inside `onSuccess` and forward it to your backend alongside the token:

```kotlin
onSuccess = { response ->
    val tokenId = response.tokenizedResponse.id
    val threeDsSessionId = response.threeDSResponse?.sessionId
    // forward tokenId and threeDsSessionId (when non-null) to your backend
}
```

See [PaymentSheetResponse](/android/online/token-response) for the full response shape and the [Error Reference](/android/online/errors) for 3DS failure codes.

## 10. Next steps

- Run the flow end-to-end with sandbox test cards - see [Testing your Integration](/android/online/testing-your-integration).