> 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. ### 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": 123456, "created_at": "2024-02-17T10:00:00Z", "created_by": "system", "entity_id": "abc123", "owned_by": "merchant_789", "status_code": "ACTIVE", "email": "user@example.com", "partner_shopper_id": "partner_001", "phone_number": "+1234567890", "finalized_at": "2024-02-17T10:30:00Z", "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": 987654, "created_at": "2024-02-17T10:00:00Z", "created_by": "system", "entity_id": "pm_abc123", "owned_by": "merchant_789", "shopper_id": "shopper_123", "type": "GoPay", "supports_tokenization": true, "supports_UIP": true, "supports_MIP": false } ``` **Why it matters:** * Multi-method Support: Shoppers can save various cards and wallets to their profiles. * Transaction Logic: `supports_UIP` indicates if the method allows one-time, user-authorized transactions. * Recurring Logic: `supports_MIP` indicates if the method allows automated, merchant-initiated billing. * Storage: The `supports_tokenization` field dictates whether the method can be safely stored for future use. ### Tokens A token is a secure, unique reference to a shopper’s saved payment method. To ensure high security, sensitive payment details are replaced by a token ID for all subsequent transactions. Token Usage Types: * User-Initiated Payments (UIP): Tokens enable one-click checkouts, allowing shoppers to pay instantly without re-entering card details. * Merchant-Initiated Payments (MIP): Tokens allow you to charge shoppers automatically for subscriptions or recurring bills. **Token Identification** ```json { "id": 456789, "entity_id": "token_abc123", "owned_by": "merchant_789", "status": "ACTIVE", "payment_method_id": "pm_987654", "provider_id": "GoPay", "token": "secure_token_value", "token_type": "single_use", "token_details": { "masked_card_number": "**** **** **** 1234", "expiry_date": "12/26" }, "is_default": true, "supports_UIP": true, "supports_MIP": false, "created_at": "2024-02-17T10:00:00Z", "created_by": "system", "updated_at": "2024-02-17T12:00:00Z" } ``` **Why it matters:** * Seamless UX: Tokens facilitate friction-free checkout experiences. * Automation: They are the core mechanism for automated subscription billing. * Permissioning: The `supports_UIP` and `supports_MIP` fields explicitly define how a specific token can be used in your payment flows. ### Charges A charge represents an individual payment request made against a saved payment method. Charge Types: * User-Initiated Payments (UIP): The shopper is present and actively authorizes the charge (e.g., a manual top-up). * Merchant-Initiated Payments (MIP): The merchant processes the charge automatically (e.g., a monthly subscription fee). Each charge is linked to a shopper, a tokenized payment method, and a specific amount/currency. **Charge Identification** ```json { "id": 123456, "created_at": "2024-02-17T10:00:00Z", "created_by": "system", "entity_id": "charge_abc123", "owned_by": "merchant_789", "status_code": "PENDING", "amount_currency": "USD", "amount_value": 49.99, "item_code": "item_987654", "item_name": "Premium Subscription", "provider_reference": "txn_123456789", "subscription_id": "sub_56789", "token_id": "token_456789", "partner_reference": "partner_charge_001", "finalized_at": "2024-02-17T10:30:00Z", "partner_custom_data": { "custom_field_1": "value1", "custom_field_2": "value2" }, "settings": { "retry_policy": "smart_retries", "capture_method": "automatic" }, "shopper_agent": { "ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0" }, "provider_custom_data": { "additional_info": "provider-specific data" }, "error_code": "NONE", "tax": { "vat": 2.50, "total_tax": 2.50 } } ``` **Why it matters:** * Audit Trail: Charges track the lifecycle and outcome of every payment attempt. * Error Handling: `error_code` values allow you to diagnose failures and trigger specific retry logic or customer notifications. --- # 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=&goal= ``` `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.