> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/codapay/recurring-payments/key-concepts.md).

# Key Concepts

Before integrating with the recurring payment product, it is essential to understand the core entities involved in the payment flow. These concepts form the foundation of our API and are referenced throughout this documentation.

Payment Types:

* **Customer-Initiated Transaction** (CIT): The shopper is present and actively authorizes the charge (e.g., a manual top-up).
* **Merchant-Initiated Transaction** (MIT): The merchant processes the charge automatically (e.g., a monthly subscription fee).

### Shoppers

A shopper represents the end-user who performs transactions using stored payment methods. In the context of recurring payments, a shopper acts as the root container for one or multiple linked payment methods.

**Shopper Identification**

Each shopper is uniquely identified by several attributes, including identifiers, status, and verified billing information.

```json
{
  "id": "shp_mcbis34tnsy8la6m19",
  "created_at": "2024-02-17T10:00:00Z",
  "finalized_at": "2024-02-17T10:30:00Z",
  "status_code": "enabled",
  "partner_shopper_id": "user001",
  "email": "user001@example.com",
  "phone_number": "+1234567890",
  "zip_code": "10001",
  "billing_first_name": "John",
  "billing_last_name": "Doe",
  "billing_document_type": "passport",
  "billing_document_id": "A12345678",
  "billing_country": "US",
  "billing_address": "123 Payment St.",
  "billing_region": "New York",
  "billing_city": "New York"
}
```

**Why it matters:**

* Data Retrieval: Shopper IDs are required to fetch stored payment methods for recurring transactions.
* Flexibility: A single shopper can maintain multiple saved payment methods across different providers.
* Eligibility: The `status_code` determines if the shopper is currently eligible for payment processing.
* Compliance: Detailed billing information may be required for document verification or regional regulatory requirements.

### Payment Methods

A payment method is the specific financial instrument (e.g., a credit card) used for transactions. Note that while our system supports various types, recurring features are currently limited to cards.

**Payment Method Identification**

Each method is identified by its type and its specific support for different transaction flows.

```json
{
  "id": "pmt_mcbis34tnsy8la6m19",
  "created_at": "2024-02-17T10:00:00Z",
  "shopper_id": "shp_mcbis34tnsy8la6m19",
  "type": "card",
  "save_payment_method": true,
  "card": {
        "id": "crd_mcbis34tnsy8la6m19",
        "created_at": "2024-02-17T10:00:00Z",
        "country_code": "MX",
        "payment_method_id": "pmt_mcbis34tnsy8la6m19",
        "last_four": "1234",
        "first_six": "123456",
        "holder_name": "John Doe",
        "expiration_month": "12",
        "expiration_year": "2040"
    }
}
```

**Why it matters:**

* Multi-method Support: Shoppers can save various cards and wallets to their profiles. Each payment method belongs to unique payment method type e.g. `card` , `wallet` etc.
* Storage: The `save_payment_method` field indicates the method stored safely for future use.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coda.co/codapay/recurring-payments/key-concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.