PayGateway - subscription

The subscription module provided by PayGateway is an ideal solution for recurring payments when there is a periodical need to charge the buyer for access to a service like newspapers,magazines, online games, etc. Successive renewals can be hourly, daily, monthly, annually etc.

The solution for subscriptions delivered by PayGateway is based on the preparation of an order template, from which subsequent renewals will inherit data. Subsequent renewals may have different amounts or VAT rates to ensure maximum flexibility of the solution.

What this module does not provide?

  • management of offers / terms of subscription

  • scheduler to trigger automatic renewal of subscriptions

  • module that manages access to content

If you would like to integrate PayGateway subscription module with your system, please contact USP team. We will provide you with the necessary information and help you with the integration process.

How to init new subscription:

Subscription flow

To initialize a new subscription transaction, you need to send a request to /init_transaction endpoint with the following parameters:

  • trans_ext_id - your id subscription

  • is_subscription - set to true

  • payment.ext_id - your id of payment

trans_ext_id is a unique identifier of the subscription. It is used to identify the subscription in TMS. It is recommended to use a random string here followed by static prefix to avoid conflicts, for example, MYSHOP_cRw8Na6OFX.

After the subscription is initialized, user will be redirected to the PayGateway page, where client can tokenize the credit card and after successful payment, the subscription will be activated.

How to renew subscription:

PayGateway provides a simple way to renew a subscription. You need to send a json-rpc call with method charge_subscription from paysystem.tms.onetapi.pl Opal interface with the following parameters:

Parameter

Type

Required

Description

merchant_id

int

yes

Merchant ID

subscription_id

string

yes

Subscription ID

order_ext_id

string

yes

Order ID

articles

list

yes

List of articles

payment_ext_id

string

no

Payment ID

ip

string

no

IP address

This is asynchronous method and returns status response 1 if the request was successful and your job has been queued and -1 if the request failed. Next, there will be an attempt to charge the payment method associated with this subscription. After successful payment, the subscription will be renewed.

Sample request:

{
    "jsonrpc": "2.0",
    "method": "charge_subscription",
    "params": {
        "merchant_id": 1,
        "subscription_id": "MYSHOP_cRw8Na6OFX",
        "order_ext_id": "dbPFaTNckB",
        "articles": [
            {
                "name": "Subscription",
                "quantity": 1,
                "price": 10.00,
                "vat_rate": 23
            }
        ],
        "payment_ext_id": "mqzjLl8v",
        "ip": null
    }
}

If you want to retry the renewal payment you can use the same method charge_subscription with the same payment_ext_id. It is important to remember that the subscription will be renewed only if the payment is successful. If the payment fails, the subscription will not be renewed and subscription status will be set to WONT_RENEW.

It’s important to send correct vat rates for every renewals. This responsibility is on merchant side, because PayGateway / TMS doesn’t have detailed knowledge about the products you sell in your store.

To achieve this, you have some options:

  • store vat rates in your system and send them with every renewal, it’s necessary in most cases.

  • get a list of vat rates from first notification and store them in your system, then use them in every renewal. It may be useful in case of selling products abroad and an invoice is required.

How to cancel subscription:

To cancel a subscription, you need to send a json-rpc call with method unsubscribe from paysystem.tms.onetapi.pl Opal interface with the following parameters:

Parameter

Type

Required

Description

order_ext_id

string

yes

Subscription ID

client_ip

string

no

IP address

This is method marks the subscription as CANCELED and returns status response 1 if the request was successful and -1 if something went wrong.

Sample request:

{
    "jsonrpc": "2.0",
    "method": "unsubscribe",
    "params": {
        "order_ext_id": "MYSHOP_cRw8Na6OFX",
        "client_ip": null
    }
}

Notifications:

PayGateway provides notifications about the status of the subscription. They will be send as JSON-RPC request to an endpoint provided by client. You can receive notifications about the following events:

  • subscription_start - subscription was created in PayGateway / TMS

  • subscription_charge - subscription was charged / renewed successfully

  • subscription_charged_failed - subscription charge / renewal failed

  • subscription_cancelled - subscription was canceled

Every notification contains the information about the subscription and the order. You can use this information to update the status of the subscription in your system and may contain additional information like: payment details or articles.

Example of subscription charge notification:

{
    "jsonrpc": "2.0",
    "id": "1718959210subscription_charge",
    "method": "subscription_charge",
    "params": {
        "user_id": "1111111",
        "user_email": "test@test.pl",
        "amount": "990",
        "currency": "PLN",
        "order_id": "RC18BV68F5SZ##UPMARJBPDKMA",
        "signature": "464025316f7219395aae74902d455e71a5ec3b65",
        "payment_ext_id": "UPMARJBPDKMA",
        "additional_data": {
            "articles": [
                {
                    "id": 1012070739,
                    "prod_ext_id": 52668,
                    "date_created": "2024-06-2110: 39: 46",
                    "date_updated": "2024-06-2110: 39: 46",
                    "name": "Plan miesięczny;",
                    "quantity": 1,
                    "mer_ext_id": null,
                    "pricenet": 916.666667,
                    "vat": 8,
                    "crn": "PLN",
                    "orderId": 1005157660507270,
                    "prodSHID": 45001571,
                    "prodMPK": 101112,
                    "config": {
                        "base_price": 1990
                    },
                    "parent_art_id": null
                }
            ],
            "payments": [
                {
                    "id": 1000000012171548,
                    "aa_id": 9005,
                    "amount": 0.0,
                    "amount_pln": 0.0,
                    "account_id": "315cb837150cc22b28ca89bcf7933",
                    "ext_id": "UPMARJBPDKMA",
                    "date_created": "2024-06-2110: 39: 46.551314",
                    "date_updated": "2024-06-2110: 39: 46.551314",
                    "crn": "PLN",
                    "ps_id": 0,
                    "config": {},
                    "report_exported": false
                }
            ],
            "subscription": {
                "order_id": 1005157659577590,
                "subscription_ext_id": "RC18BV68F5SZ",
                "status": "ACTIVE"
            }
        }
    }
}

If TMS receives http status code different than 200, it will retry sending the notification every few minutes until it gets accepted or it would be expired after 10.

Are you interested in receiving other types of notifications? Please contact USP team.

Integration with OnetKonto dashboard:

It’s possible to integrate PayGateway with OnetKonto dashboard. This will allow you to manage subscriptions directly from the dashboard. To achieve this, you need to provide the following information:

  • REST API endpoint which delivers information about the subscription (subscription details, expiration date, etc.)

Sample response with subscription details:

{
    "jsonrpc": "2.0",
    "id": "23131231231",
    "result": [
        {
            "plan": [
                {
                    "billingPeriod": "1 month",
                    "isTrial": false,
                    "price": 9.9,
                    "cycles": null
                }
            ],
            "merchantId": "<merchant_id>",
            "subscriptionId": "<subscription_id>",
            "expireDate": null,
            "nextChargeDate": 1751190209,
            "nextChargePrice": 9.9,
            "resourceName": "<resource_name>",
            "termName": "<term_name>",
            "renewOffUrl": "<renew_off_url>",
        }
    ]
}