> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PaymentMethod

> PaymentMethod is the Schema for the paymentmethods API.

<Note>
  API resource reference for **PaymentMethod**, part of the [Billing service](/api/billing/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                        |
| ------- | ---------------------- |
| Group   | `billing.miloapis.com` |
| Version | `v1alpha1`             |
| Kind    | `PaymentMethod`        |
| Scope   | Project                |

## Overview

A `PaymentMethod` associates a payment instrument — such as a credit card or US bank account — with a `BillingAccount`. You create one carrying only a reference to the billing account and a human-readable display name. The billing service then injects the `PaymentMethodClass` that selects the provider, and the provider controller drives the setup flow and reports the confirmed instrument back on `status` once it is active.

Use it when you need to register a new way to pay for a billing account within a Project.

## Spec fields

| Field                             | Type   | Required | Description                                                                                                                                                                               |
| --------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec.billingAccountRef`          | Object | Yes      | References the `BillingAccount` this payment method belongs to. The BillingAccount must reside in the same Project.                                                                       |
| `spec.billingAccountRef.name`     | string | Yes      | The name of the `BillingAccount`.                                                                                                                                                         |
| `spec.displayName`                | string | Yes      | A human-readable label shown in the portal and on invoices (e.g., `Corporate Visa`).                                                                                                      |
| `spec.paymentMethodClassRef`      | Object | No       | Selects the `PaymentMethodClass` — and through it the provider controller — that owns the setup flow. Left unset by consumers and injected by the defaulting webhook. Immutable once set. |
| `spec.paymentMethodClassRef.name` | string | No       | The name of the `PaymentMethodClass`.                                                                                                                                                     |

## Status fields (read-only)

| Field                          | Type      | Description                                                                                                       |
| ------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `status.phase`                 | string    | Current lifecycle phase: `Pending`, `AwaitingConfirmation`, `Active`, or `Failed`.                                |
| `status.details`               | Object    | Normalized, provider-agnostic description of the confirmed instrument. Populated once the phase reaches `Active`. |
| `status.details.type`          | string    | The instrument category: `card` or `usBankAccount`.                                                               |
| `status.details.card`          | Object    | Card details, populated when `type` is `card`.                                                                    |
| `status.details.usBankAccount` | Object    | US bank account details, populated when `type` is `usBankAccount`.                                                |
| `status.failureReason`         | string    | Short, machine-parseable failure code (e.g., `card_declined`). Set when phase is `Failed`.                        |
| `status.failureMessage`        | string    | Human-readable description of the failure.                                                                        |
| `status.conditions`            | \[]Object | Latest available observations of the payment method's state.                                                      |
| `status.observedGeneration`    | integer   | Most recent generation observed by the reconciling controller.                                                    |

## Usage

```yaml theme={null}
apiVersion: billing.miloapis.com/v1alpha1
kind: PaymentMethod
metadata:
  name: corporate-visa
spec:
  billingAccountRef:
    name: acme-billing
  displayName: Corporate Visa
```

```bash theme={null}
datumctl apply -f paymentmethod.yaml --project my-project
datumctl get paymentmethods --project my-project
datumctl describe paymentmethod corporate-visa --project my-project
```

<Tip>
  Run `datumctl explain paymentmethods --recursive` to see the full, live field tree for this resource.
</Tip>