> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm the payment

> Collect the card, authorize, and handle the result with confirmPayment

## Overview

One call collects the card securely, runs 3D Secure, and authorizes. It resolves once with the final result, so it is safe to call a single time per confirm.

```javascript theme={null}
const result = await modulus.confirmPayment({
  elements,
  billingDetails: {
    firstName: 'Juan', lastName: 'Dela Cruz',
    email: 'juan@example.com', phone: '+639171234567',
    address: {
      line1: 'General Luna', city: 'General Luna',
      state: { code: 'SDN', name: 'Surigao del Norte' },
      postalCode: '8419', country: 'PH',
    },
  },
  onStatusChange: (s) => console.log(s), // optional lifecycle hook
});

if (result.status === 'SUCCEEDED') {
  // result.receipt.transaction_id, result.receipt.approval_code, result.receipt.card_last_four ...
}
```

## confirmPayment(options)

| Field            | Type     | Required | What it does                                                                                                                                                                                                                             |
| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `elements`       | Elements | yes      | The mounted group of card fields.                                                                                                                                                                                                        |
| `billingDetails` | object   | yes      | Cardholder name, email, and address. See below.                                                                                                                                                                                          |
| `idempotencyKey` | string   | no       | De-duplicates a retried confirm so the customer is never double-charged. If supplied, it must match `^[A-Za-z0-9._-]{8,60}$`; an invalid value resolves as `FAILED` with `INVALID_IDEMPOTENCY_KEY`. When omitted, the SDK generates one. |
| `acsWindowSize`  | string   | no       | 3DS challenge window size, `"01"` to `"05"` (default `"05"`). See [3D Secure](/docs/ecom/jssdk/3d-secure).                                                                                                                               |
| `onStatusChange` | function | no       | Called as the payment progresses so you can update your UI. See [3D Secure](/docs/ecom/jssdk/3d-secure).                                                                                                                                 |
| `threeDS`        | object   | no       | 3DS rendering options, for example `{ container }`. See [3D Secure](/docs/ecom/jssdk/3d-secure).                                                                                                                                         |

## billingDetails

| Field                | Type   | Required    | Notes                                                                                                                                                                                        |
| -------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstName`          | string | yes         | Cardholder given name. Max 60 characters.                                                                                                                                                    |
| `lastName`           | string | yes         | Cardholder family name. Max 60 characters.                                                                                                                                                   |
| `email`              | string | yes         | For the receipt and fraud checks. Max 255 characters.                                                                                                                                        |
| `phone`              | string | no          | Max 20 characters. After removing spaces, hyphens, and parentheses it must match `^\+?[1-9]\d{5,14}$` (E.164), e.g. `+639171234567`.                                                         |
| `address.line1`      | string | yes         | Street address. Max 60 characters.                                                                                                                                                           |
| `address.line2`      | string | no          | Unit / building. Max 60 characters.                                                                                                                                                          |
| `address.city`       | string | no          | City / municipality. Max 50 characters.                                                                                                                                                      |
| `address.state`      | object | conditional | `{ code, name }`, the province. Required for US, CA, and CN. When present, both `code` and `name` are required, each max 20 characters; for US/CA/CN the `code` must be a valid subdivision. |
| `address.postalCode` | string | no          | ZIP / postal code. Max 10 characters.                                                                                                                                                        |
| `address.country`    | string | yes         | ISO 3166-1 alpha-2 code, e.g. `PH`. Lowercase is accepted and sent uppercase.                                                                                                                |

## Result and error handling

`confirmPayment` resolves with a typed status. Switch on `result.status` (the enum value), not on the wording of any message. Message text can be reworded in any release.

| `result.status` | What to do                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `SUCCEEDED`     | Paid. Read `result.receipt` and release the booking or order.                                                                              |
| `DECLINED`      | Issuer declined. Show `result.userMessage` and let them try another card.                                                                  |
| `PROCESSING`    | Outcome uncertain (network / timeout). Do not retry blindly, the payment may still complete. Show a "we're confirming your payment" state. |
| `EXPIRED`       | The intent's payment window lapsed before it was confirmed. Create a fresh intent and re-mount.                                            |
| `FAILED`        | Could not complete. See `result.error.code` and `result.error.message`.                                                                    |

## result.receipt

Returned on `SUCCEEDED`. Fields marked optional are present only when the processor returns them.

| Field                         | Type              | Meaning                                                                     |
| ----------------------------- | ----------------- | --------------------------------------------------------------------------- |
| `approval_code`               | string            | Issuer authorization code.                                                  |
| `transaction_id`              | string            | Modulus transaction reference, used to track the payment in your dashboard. |
| `reconciliation_id`           | string            | Settlement / reconciliation reference (the processor reference number).     |
| `acquirer_transaction_number` | string (optional) | Acquirer's transaction reference. Present when available.                   |
| `card_scheme`                 | string (optional) | Card brand, `VISA` or `MASTERCARD`.                                         |
| `card_last_four`              | string (optional) | Last four digits of the card used.                                          |
| `order_reference`             | string (optional) | Your order reference associated with the payment, echoed back when present. |
| `description`                 | string (optional) | The `description` from the payment, echoed back.                            |
| `completed_at`                | string (optional) | ISO 8601 timestamp when the payment completed.                              |
| `batch_number`                | string (optional) | Settlement batch number.                                                    |
| `invoice_number`              | string (optional) | Modulus invoice number for this payment.                                    |