> 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/use-cases-and-flows.md).
# Use Cases and Flows
This section describes the different use cases and transaction flows for recurring payments. These flows cover both customer-initiated payments and merchant-initiated payments while handling scenarios such as first-time payments, returning users, and subscription billing.
#### Key Scenarios
1. **First-Time Payment & Saving a Payment Method:** A new shopper completes a payment and opts to save their details.
2. **Merchant-Initiated Recurring Payment:** The merchant charges a saved payment method automatically for subscriptions.
3. **Shopper Removes a Saved Payment Method:** A shopper removes a stored payment method from their account.
### First-Time Payment & Saving a Payment Method
**Description**
A new shopper (customer) completes a payment and given the option to save their payment method for future transactions.
```mermaid
sequenceDiagram
Title First-Time Payment & Saving Payment Method (CIT for MIT)
actor Customer
participant Merchant
participant Coda API
participant Coda Hosted Page
participant Payment Provider
Merchant ->>+ Coda API: Initiate Payment API (/v2.0/Payment/init.json)
[userInitiated=true, offSessionReuse=true, offSessionType]
Coda API -->> Merchant: Return Transaction ID (txnId)
Merchant ->> Customer: Redirect to Coda Hosted Page
Customer ->> Coda Hosted Page: Enter payment details and select "Save for future use"
Coda Hosted Page ->> Payment Provider: Process Payment authorization
Payment Provider -->> Coda Hosted Page: payment authorization result
Coda Hosted Page -->> Customer: Display payment completion
Coda API -->> Merchant: Send PAYMENT_METHOD_ADDED webhook (success payment only)
Coda API -->> Merchant: Send payment result webhook (with saved payment method id)
```
**Flow Details**
1. The merchant initiates a payment request via `/v2/Payment/init`, passing shopper info, transaction details, and `savePaymentMethod: true` and respective parameters:
1. `offSessionType` type of future off session payment (Unschedule, Subscriptions, Instalments) for this account binding
2. The shopper is redirected to the hosted payment page
3. The shopper enters payment details and selects to save the payment method
4. The payment is processed, undergoing authentication and fraud checks (e.g., SCA)
5. Upon success:
* A shopper profile is created (if it doesn't exist)
* A payment method token is generated and stored
* The merchant receives a notification confirming the saved method
6. The merchant receives the payment success response along with the tokenized payment method
You can refer to the [Hosted Payment Page Integration: Initiate a Payment Request](/codapay/hosted-component-integration/cards/initiate-a-payment-request.md) and [Saving Card Details](/codapay/hosted-payment-page-integration/saving-card-details.md) references for more details on each APIs.
### Merchant-Initiated Recurring Payment
**Description**
The merchant charges a shopper automatically without their presence (off-session), using a previously saved payment method.
```mermaid
sequenceDiagram
Title Merchant-Initiate Payment (Recurring, Subscriptions, Unscheduled)
participant Merchant
participant Coda API
participant Payment Provider
Merchant ->>+ Coda API: Charge with tokenized payment mehtod (/v1.0/payment/token/charge)
[payment_method_id]
Coda API -->> Merchant: Return Transaction ID (txnId) - acknowledged
Coda API ->> Payment Provider: Process Payment authorization
Payment Provider -->> Coda API: Payment authorization result
Coda API -->> Merchant: Send payment result webhook
```
**Flow Details**
1. The merchant initiates a charge via `/v1/payment/token`, passing:
* `paymentMethodId` saved payment method of the particular partnerShopperId
* `offSessionType` type of offSession binding the user was authorised in First-time payment when saving the payment method with consent
2. The merchant will receives acknowledgement response with resultCode `431`
3. The system processes the payment using the stored payment method.
4. The transaction undergoes standard authentication, fraud checks, and processing.
5. The merchant receives a payment success notification callback.
1. Optionally, merchant can query the payment result with [v2.0 Inquiry API](https://docs.coda.co/codapay/hosted-payment-page-integration/check-a-transaction-status#endpoint)
You can refer to the [Hosted Payment Page Integration: Initiate a Payment Request](/codapay/hosted-component-integration/cards/initiate-a-payment-request.md) and [Saving Card Details](/codapay/hosted-payment-page-integration/saving-card-details.md) references for more details on each APIs.
---
# 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/use-cases-and-flows.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.