# Subscription payments

> Choosing between managed and self-managed subscriptions, contract credentials and lifecycle notifications, renewals and plan changes, and the parameter differences across integration methods.

A subscription creates a contract with the first payment and charges repeatedly by billing cycle. The initial subscription can be completed through Checkout, the Web SDK, or the Direct API; self-managed renewals and managed plan changes are initiated by your server through the Direct API.

## Concepts and choices

The billing model is determined by `subscription.selfExecute` and chosen at the initial subscription:

- **Managed subscriptions** (`selfExecute=1`): Onerway automatically collects each cycle according to the subscription plan and sends a webhook for every payment. When `notificationEmail` is configured, Onerway emails the customer subscription confirmations and billing notices, and the customer can self-manage the subscription through the `subscriptionManageUrl` returned in the response.
- **Self-managed subscriptions** (`selfExecute=2`): you maintain the billing schedule and collect each cycle through [Create direct transaction](/payments/api-reference/endpoints/direct-create-transaction) (`subscription.requestType=1`) using the `contractId` and `tokenId` returned by the initial subscription; only `frequencyType=D` is supported, but that does not limit you to daily billing: the [`subscription.frequencyPoint` field](/payments/api-reference/endpoints/direct-create-transaction#request-subscription-frequencyPoint) states the billing cycle in days (for example, you can submit `30` for a monthly subscription or `365` for an annual subscription). This value is informational only; you determine when to initiate renewal charges. Whether you make the first charge depends on `subscription.mode` — under the default `2`, Onerway collects it once the customer has authorized.

Both cards and wallets can be used for subscriptions, and both billing models apply to Apple Pay and Google Pay. How a wallet subscription is started and how it differs from a card subscription are covered in [Apple Pay](/payments/online-payments/payment-methods/apple-pay#wallet-subscriptions) and [Google Pay](/payments/online-payments/payment-methods/google-pay#wallet-subscriptions). A subset of the methods in [Local payment methods](/payments/online-payments/payment-methods/local-payment-methods#local-payment-method-subscriptions) can also be used for subscriptions, but only as self-managed subscriptions, and the subscription authorization produces a notification of its own.

The billing cycle, cycle count or end date, and trial period are all defined in the [`subscription` field](/payments/api-reference/endpoints/direct-create-transaction#request-subscription); see the API Reference for field definitions. The customer identifier is submitted in the top-level `merchantCustId` (`subscription.merchantCustId` is optional and must match when submitted), with the same requirements as in [Saved payment methods](/payments/online-payments/scenarios/saved-payment-methods#concepts-and-choices).

## Lifecycle and notifications

- **Contract credentials**: after the initial subscription succeeds, store the `contractId` and `tokenId` from the [subscription payment webhook](/payments/api-reference/webhooks/subscription-payment); they are the credentials for later billing, queries, and cancellation. This `tokenId` is a subscription token and must not be mixed with card tokens; see [Scenario overview](/payments/online-payments/scenarios#three-kinds-of-tokens).
- **Lifecycle events**: initial purchase, renewal, card replacement, change, cancellation, expiration, and contract status are determined by the [`scenarios` field](/payments/api-reference/webhooks/subscription-payment#webhook-scenarios) and the [`subscriptionStatus` field](/payments/api-reference/webhooks/subscription-payment#webhook-subscriptionStatus) of the subscription payment webhook.
- **Self-managed renewal**: your server submits `contractId`, `tokenId`, `merchantCustId`, and the amount for this cycle, with no card data, so renewals carry no PCI DSS requirement. You specify the amount for each cycle; it is not constrained by the initial subscription amount. A successful charge produces a webhook with `scenarios=SUBSCRIPTION_RENEWAL`; reconciling with Onerway is your responsibility.
- **Managed renewal**: Onerway charges the amount of the plan in effect, which is the initial subscription amount until you change the plan. An individual automatic charge cannot be adjusted; to change future amounts, update the plan as described below.
- **Managed plan changes**: initiated with the stored `contractId` and `tokenId` (`requestType=2`); when the change takes effect is controlled by `subscription.changeMode`. A successful update produces a webhook with `scenarios=SUBSCRIPTION_CHANGED`. Once the change takes effect, Onerway continues automatic billing at the new plan amount.

  - `changeMode=1`, apply immediately: Onerway prorates by the remaining days of the current cycle (`prorationMode=1`, the default), or you calculate the prorated amount and submit it in `proration` (`prorationMode=0`). Upgrades charge the difference immediately; for downgrades, refund any difference owed to the customer through [Create or cancel refund](/payments/api-reference/endpoints/create-or-cancel-refund).
  - `changeMode=2`, apply from the next billing cycle: no immediate charge, suitable for price increases that require advance notice.
- **Subscriptions that also save the card**: when a managed card subscription submits `subscription.bindCard=true`, two transactions and two separate notifications are created: the [saved payment method result webhook](/payments/api-reference/webhooks/payment-method-result) (`txnType=BIND_CARD`) returns the card token usable for later token payments, and the subscription payment webhook (`txnType=SALE`) returns the subscription-side `contractId` and `tokenId`. The two notifications carry different `transactionId` values and must be handled idempotently on their own.
- **Query and cancel**: see [Query subscription details](/payments/api-reference/endpoints/query-subscription-details) and [Cancel subscription contract](/payments/api-reference/endpoints/cancel-subscription-contract).

## Failed payments and retries

For self-managed subscriptions (`selfExecute=2`), you decide whether, how many times, and how often to retry, and submit each retry as a renewal charge (`requestType=1`) through the Direct API.

For managed subscriptions (`selfExecute=1`), Onerway retries automatically: at most **3 attempts per cycle, including the initial charge**, so up to 2 retries. The interval depends on the billing cycle:

| Billing cycle | Retry interval |
| --- | --- |
| Daily | 1 hour |
| Every 2–3 days | 12 hours |
| Longer than 3 days | 24 hours |

While retries are pending, `subscriptionStatus` is `pastdue`; if all 3 attempts fail, it becomes `paused` while the contract stays enabled (`dataStatus=1`). Both fields are returned by the subscription payment webhook and [Query subscription details](/payments/api-reference/endpoints/query-subscription-details).

Payment retries are separate from webhook redelivery; see [Acknowledge and retries](/payments/get-started/webhooks#acknowledge-and-retries).

## Replacing the subscription card

Only managed subscriptions (`selfExecute=1`) support card replacement, and only by the customer on the subscription management page at `subscriptionManageUrl`; there is no API for it. The result is reported by the subscription payment webhook with `scenarios=SUBSCRIPTION_CARD_REPLACEMENT`.

## Parameters by integration method

| Integration method | Endpoint | Key parameters | Differences | Integration guide |
| --- | --- | --- | --- | --- |
| Checkout | [Create checkout payment](/payments/api-reference/endpoints/create-checkout-payment) | `subProductType=SUBSCRIBE`, `subscription` (`requestType=0`) | Initial subscription only; a top-level `merchantCustId`, if submitted, must match `subscription.merchantCustId` | [Checkout integration](/payments/online-payments/checkout#subscriptions) |
| Web SDK | [Create SDK transaction](/payments/api-reference/endpoints/sdk-create-transaction) | `subProductType=SUBSCRIBE`, `subscription` (`requestType=0`) | Initial subscription only; keep the allowed plan mapping on your server | [Web SDK integration](/payments/online-payments/sdk#saved-cards-and-subscriptions) |
| Direct API | [Create direct transaction](/payments/api-reference/endpoints/direct-create-transaction) | `subProductType=SUBSCRIBE`, `subscription.requestType` | Initial subscription, renewal, and plan changes all use this endpoint, distinguished by `requestType` `0` / `1` / `2` | [Direct API integration](/payments/online-payments/api#subscriptions) |