Subscriptions – Initial payments, trials, token-based subscriptions and subscription management

This document summarizes the expected behaviour and Backoffice capabilities for the new Subscriptions / Coverage Plans model, with a particular focus on initial payments, trial periods, token-based subscription creation, recurring payments, events, refunds, and subscription management.

1. Token-based subscriptions – Initial payment and trial period

1.1 Initial charge without a trial period

When you create a subscription using token-based creation and no trial period is configured, the initial charge is executed immediately when the subscription is created.

The initial charge is not deferred by the configuration of the plan.

If the initial payment is successful, the subscription is created and becomes active.

If the initial payment fails, the subscription becomes expired. The first token-based payment attempt cannot be retried.

1.2 Initial charge with a trial period

A trial period does not automatically mean that the initial payment is skipped.

The amount configured for the trial is charged at the time the subscription is created. This amount can be either 0 or the amount the amount configured for the trial in the plan.

Plan configuration	overwrite.initialAmount	Initial amount charged
Trial amount = 0	Not provided	0
Trial amount = 10	Not provided	10
Trial amount = 10	0	0
Trial amount = 10	5	5

If you provide overwrite.initialAmount, it overrides the amount configured for the trial in the plan.

Once the trial period ends, the subscription starts charging the normal plan amount according to the configured subscription frequency.

1.3 overwrite.initialAmount

overwrite.initialAmount allows you to make an exception to the initial charge defined by the plan.

The overwrite takes precedence over the amount configured in the plan, whether or not a trial period exists.

It is not mandatory.

You can use it when you need to apply a different initial charge for a specific subscription without changing the plan configuration.

If there is no trial period, you can use the same field to override the initial charge that would otherwise apply at subscription creation.

1.4 overwrite.initialAmount: 0

If you set overwrite.initialAmount to 0 and there is no trial period, the system generates an initial payment with an amount of 0.

This is still processed as the initial payment; it is not interpreted as "skip the initial payment and charge at the first renewal."

For the zero-value payment to succeed, the PSP must be configured in the Backoffice to accept a charge of 0.

If the zero-value payment is successfully accepted:

• The subscription is created.

• The subscription becomes active

• The subscription is in cycle 0

• The subscription.createdevent is sent.

1.5 Initial payment failure

For token-based subscription creation, the first token-based payment attempt cannot be retried.

If the initial payment fails:

• The subscription becomes expired

• The payment attempt cannot be retried.

• The subscription does not proceed to the recurring payment cycles.

In other words, the subscription is effectively created in an immediately expired state.

2. Subscription frequency and first recurring payment

The subscription payment frequency is configured within the Plan in the Revup Backoffice.

You can define different frequencies for different plans. For example:

• Monthly
• Annual
• Custom frequency

A custom frequency can also be configured.

You can configure the time of the payment attempt independently, but this configuration applies to all recurring payment attempts. You cannot configure a different payment time specifically for the first recurring payment.

Trial configuration

You can configure a trial period for a plan.

The number of trial days is configured within the plan. Once the trial period ends, the subscription begins charging the normal plan amount according to the configured frequency.

For example, you can configure the following flow:

Initial payment of 0 → 14-day trial period → First recurring payment → Monthly recurring payments

The trial duration is configured at plan level.

3. Token-based subscriptions – Payment tokenization

The Base Payment Token is used to support recurring payments without requiring you to store sensitive card information in your systems.

3.1 Token lifecycle

The token is created as part of the subscription creation process.

The general lifecycle is:

1. You create the subscription and the token is generated as part of the subscription.
2. Recurring payments are subsequently processed using that token.
3. When you cancel the subscription, the token remains available until it expires.
4. There is currently no delete token operation.

3.2 PSP or payment-method limitations

There are no additional limitations on the Revup side depending on the PSP, such as Stripe or Worldpay.

3.3 Additional configuration

No additional configuration is required to enable recurring payments through the token.

You only need to follow the required steps for token-based subscription creation described in the Revup documentation:

Token-Based Subscription Creation | Revup

4. Token-based subscriptions – paymentDetails configuration

For the token-based subscription flow, you do not need to send:

{ "paymentDetails": { 
  "type": "recurrence", 
  "sequence": "initial" 
  } 
}

when generating the token for a Base Payment Token subscription.

This configuration is currently used for Split Payments, whereas the Base Payment Token subscription flow follows the token-based subscription creation process.

5. Subscription events and notifications

Revup provides events for the different stages of the subscription lifecycle and its associated payment activity.

The following events are available:

Event	Available
Subscription created	Yes
Subscription updated	Yes
Subscription paused	Yes
Subscription resumed/reactivated	Yes
Subscription cancelled	Yes
Refund	Yes
Recurring payment successful	Yes
Recurring payment failed	Yes
Dispute	Yes

You can find the complete list and payload definitions in the Revup documentation:

Subscription Events | Revup

5.1 Payment events and subscription lifecycle events

Once the subscription has been created and recurring payments begin, the corresponding events are sent as part of the payment/subscription activity.

5.2 Event information

Depending on the event, the notification can contain information such as:

• Event type
• Subscription information
• Associated transactions
• Customer information
• Next payment date
• Payment information and status

You can find the detailed payload for each event in the subscription event documentation.

5.3 Identifying the subscription and payment

The subscriptionId provides the unique identifier for the subscription and allows you to reliably associate events with the relevant subscription.

The initial payment is also available directly within the event payload.

For example:

{ 
"originator": { 
  "type": "PAYMENT", 
  "data": { 
    "paymentId": "01902a68-add8-77c2-8e39-b3ebcc603293", 
    "orderId": "core order id", 
    "type": "INITIAL", 
    "status": "ACCEPTED", 
    "attempt": 1, 
    "money": { 
      "amount": 9.98, 
      "currency": "USD" 
      } 
    } 
  } 
}

You can find a complete example here:

Created | Revup

6. Refunds and subscription cancellation

You can manage refunds for payments associated with subscriptions directly from the Revup Backoffice.

When initiating a refund, the Backoffice also gives you the option to cancel the associated subscription.

6.1 Refund history

Within the subscription, you can see the transactions and payments associated with that subscription.

This allows you to review the recurring payment activity and its associated transaction history.

6.2 Does a refund automatically cancel the subscription?

No.

Processing a refund does not automatically cancel the subscription.

There is currently no configuration that automatically cancels the subscription whenever a refund is processed.

6.3 Cancelling after a refund

If you want to cancel the subscription after a refund, you can:

1. Receive the refund event.
2. Process the refund according to your business logic.
3. Cancel the subscription through the Subscription API.

You can find the cancellation endpoint here:

Cancel Subscription | Revup

This allows you to ensure that, after a refund and subsequent cancellation, no further recurring charges are generated for the subscription.

7. Subscription management in the Backoffice

The Revup Backoffice provides several capabilities for managing and monitoring subscriptions.

7.1 Search and view subscriptions

You can search for and view an individual subscription in the Backoffice.

You can view the subscription's:

• Current status
• Current plan

7.2 Subscription payment history

Within the subscription, you can access a section containing all payment attempts associated with that subscription.

The transaction history allows you to identify the current status of transactions and refunds, including successful, failed, and refunded transactions.

7.3 Subscription actions

You can manage subscriptions directly from the Backoffice.

The following actions are available:

• Cancel a subscription
• Pause a subscription
• Resume/reactivate a subscription

There is an important distinction regarding reactivation:

• You can resume a subscription that you manually paused

• You cannot resume a subscription that has expired

• You cannot resume a subscription that has been manually cancelled

If an expired or cancelled subscription needs to be activated again, you need to create a new subscription.

8. Token-based subscriptions – Lifecycle examples

8.1 Standard subscription

Plan: Monthly Trial: None Initial amount: €10

Flow:

Subscription creation → Initial payment (€10) → Subscription created → Cycle 0 / Active → Monthly recurring payments

8.2 Token-based subscription with a trial

Plan: Monthly Trial: 14 days Trial amount: €0

Flow:

Subscription creation → Initial payment (€0) → Subscription created → Cycle 0 / Active → 14-day trial → First recurring payment → Monthly recurring payments

8.3 Token-based subscription with an overwritten initial amount

Plan: Monthly Trial amount: €10 overwrite.initialAmount: €5

Flow:

Subscription creation → Initial payment (€5) → Subscription created → Cycle 0 / Active → Trial period → First recurring payment → Monthly recurring payments

The overwrite takes precedence over the amount configured in the plan.

8.4 Token-based subscription with zero initial amount and no trial

Plan: Monthly overwrite.initialAmount: €0

Flow:

Subscription creation → Initial payment (€0) → Subscription created → Cycle 0 / Active → First recurring payment → Monthly recurring payments

The PSP must be configured to accept zero-value payments.

8.5 Token-based subscription with a failed initial payment

Initial payment: Failed

Flow:

Subscription creation → Initial payment fails → Subscription becomes expired

The initial token-based payment attempt cannot be retried, and the subscription does not proceed to recurring payments.

9. Key takeaways

• The initial payment is processed immediately during token-based subscription creation.

• A trial period does not inherently remove the initial payment.

• The trial amount can be 0 or another amount configured in the plan.

• overwrite.initialAmount overrides the initial/trial amount configured in the plan.

• overwrite.initialAmount: 0 results in an actual zero-value initial payment attempt.

• Zero-value payments require the PSP to be configured to accept them.

• A successful initial payment, including a successful 0 payment, creates the subscription and triggers subscription.created

• The newly created subscription is active and starts in cycle 0

• A failed initial token-based payment cannot be retried and results in an expired subscription.

• You can configure the subscription frequency at Plan level in the Revup Backoffice

• You can configure different or custom payment frequencies for different plans.

• You can configure a trial duration at Plan level.

• You can configure the time of the recurring payment attempt, but this applies to all recurring payments.

• The Base Payment Token is created as part of the subscription and remains until it expires; there is currently no token deletion operation.

• No additional Revup configuration is required to enable recurring payments through the token.

• For Base Payment Token subscriptions, you do not need to provide the paymentDetails

  configuration used for Split Payments.

• You can manage refunds directly from the Backoffice.

• Refunds do not automatically cancel a subscription.

• You can cancel a subscription through the Backoffice or API.

• You can pause and resume subscriptions from the Backoffice.

• You can only resume subscriptions that you manually paused.

• Expired or manually cancelled subscriptions cannot be reactivated; you need to create a new subscription.