Payment System Initiated (PSI) Recurring Payments

Overview

This document describes the functionality and flow of Payment System Initiated (PSI) transactions for recurring payments, as implemented in our platform.

Recurring payments allow merchants to automate subscription-based billing for their customers, with the billing process fully managed by the payment processor. This means that the payment processor triggers recurring charges based on the defined billing interval, and the merchant is notified of the outcome (success or failure) via webhooks.

Supported Integration Types

Recurring payments via PSI can be integrated using:

• Web SDK

• Hosted Page

• Direct Payment API

• E-Commerce Plugin (WooCommerce via Paytiko)

Key Constaints

• Price and Currency: Cannot be changed during the recurring payment lifecycle.

• Reference ID: Each transaction has a Reference ID field that groups transactions belonging to the same recurring process. This is useful for tracking and can be shown in the CRM grid (addable through the grid filter if not visible).

Cancellation Options

• CRM users can manually cancel the recurring process. When cancelled, the transaction status updates to "Subscription Cancelled", and a webhook notification is sent to the merchant.

• Merchants can cancel a subscription via the Cancellation Endpoint by providing the merchant order ID. Upon successful cancellation, the transaction status is updated to "Subscription Cancelled", and a webhook notification is also sent to the merchant.

Recurring Payment Flow

1. Initial Transaction Creation

   • Status: Pending.

   • Occurs after the customer completes the first checkout.

2. First Charge Success

   • Status updated to Success.

   • Triggers the start of the recurring billing cycle.

3. Recurring Charges

   • Initiated by the payment processor at each defined interval.

   • Result in a transaction with the corresponding status:

     • Success: Merchant is notified.

     • Rejected: Merchant is notified.

4. Merchant Notifications

   • Sent though transaction update webhooks for each charge attempt.

5. Cancellation

   • CRM users: Can manually cancel the recurring process.

   • Merchant API: Merchants can cancel the subscription via the API Cancellation Endpoint, providing the order ID.

   • In both cases:

     • Status is updated to Subscription Cancelled.

     • Merchant receives a cancellation notification via webhook.

Flow Sequence Diagram

API Usage

Subscription Options Setup

For Web SDK, Hosted Page & Direct Payment, you just need to add subscriptionOptions field to your checkout API request. Below you can find the object structure for subscriptionOptions.

Field	Type	Description	Required
planName*	String	Subscription plan name.
billingInterval.interval*	String	Specifies billing frequency. Either 'Day', 'Week', 'Month' or 'Year'.
billingInterval.intervalCount*	Integer	The number of intervals between subscription billings. For example, interval='Month' and intervalCount=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).

Structured JSON Sample

{
...
    "subscriptionOptions": {
        "planName": "Monthly Plan",
        "billingInterval": {
            "interval": "Month",
            "intervalCount": 1
        }
    }
}

Cancellation Endpoint

POST {CORE_URL_ISSUED_BY_PAYTIKO}/api/psi-subscription/cancel?orderId={orderId}

This endpoint allows merchants to cancel an active Payment System Initiated (PSI) subscription by the provided merchant order identifier.

Headers

Name	Type	Value
X-Merchant-Secret*	String	{MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}
Content-Type*	String	application/json

Query Params

Name	Type	Description	Required
orderId*	String	The merchant order ID linked to the subscription.

Response

200 (OK)

{
  "isSuccess": true
}

400 (Bad Request)

{
  "isSuccess": false,
  "errorMessage": "Authorization header is required."
}

422 (Unprocessable Entity

{
  "isSuccess": false,
  "errorMessage": "The subscription for this order was not found or has already been cancelled."
}

Webhooks

Webhook structure and statuses you can find navigating by this Link.

WooCommerce Usage

Statuses

When using the WooCommerce plugin (Paytiko), subscription-related order statuses are mapped as follows:

• Pending Payment: Order for the subscription is created and awaiting the first payment.

• Completed: Subscription is active — the first payment succeeded, or a subsequent period was paid successfully.

• Failed: Payment for the next subscription period failed (e.g., due to insufficient funds).

• Cancelled: Subscription was manually cancelled via CRM Paytiko.

Feature Setup Instructions

WooCommerce admin dashboard setup instructions for subscriptions you can find Here.