> 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-coming-soon/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.