Subscription payments

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 (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 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 and Google Pay. A subset of the methods in Local payment methods 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; 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.

Lifecycle and notifications

• Contract credentials: after the initial subscription succeeds, store the contractId and tokenId from the subscription payment webhook; 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.
• Lifecycle events: initial purchase, renewal, card replacement, change, cancellation, expiration, and contract status are determined by the scenarios field and the subscriptionStatus field 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.
  • 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 (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 and 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:

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.

Payment retries are separate from webhook redelivery; see 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