PayGateway - subscription¶

How to init new subscription:¶

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:

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:

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>",
        }
    ]
}