Subscription Initial Purchase


Check our Reference Materials for more details about a payment connector.


This tutorial describes how to implement an initial payment for a customer using the Cleeng Payment API and a payment gateway.

Process Flow

In this section, you can see the whole process flow, from the customer filling the payment data form to payment process completion.


Initial Payment - Example Process Flow



Details of the implementation will depend on a specific payment gateway solution.

Step-by-Step Guide



Each payment in Cleeng should have externalPaymentId (the same as the payment identifier from an external payment gateway system).

Step 1: Select Method & Offer and Create Order

The user chooses the offer and then the order can be created using POST /3.1 /orders.

curl -X POST \ \
  -H 'Content-Type: application/json' \
  -H 'X-Publisher-Token: hsEJu1srZcRzM6BGOCfEtvCZyjktbn0R1c7n-vT0lchtVP11' \
  -d '{

Step 2: Fill in & Submit Payment Form

In this step, the user fills the payment details and after that, a subscription with payment details and orderId can be purchased.

In this step, any relevant (gateway-specific) data should be collected.



Usually, here the standard integration of the payment gateway is used. To see an example, please refer here.

Step 3: Pass Data to Connector

orderId and any relevant (gateway-specific) data should be passed to the connector.

Step 4: Process Payment

This step depends on the remote payment gateway system. In general, you should make a request to the remote payment gateway (the connector should process payment in the payment gateway) (if it is possible, you should split it into two steps, authorise and capture).

Payment amount and currency should be the same as in the order (it is important for reporting purposes).

If it is Cleeng-Managed Recurring Billing - a payment gateway must return a recurring token which is required if recurring payments are to be processed properly later on.

If it is Externally-Managed Recurring Billing - payments connector only listens to events, a recurring token is not required.

In both cases, the connector should also receive a payment identifier from the external payment gateway system (called an externalPaymentId in Cleeng).
An externalPaymentId should be passed to Cleeng. This will guarantee payment and subscription creation at Cleeng.

Step 5: Create Payment Reference

In this step, the connector creates payment in Cleeng using POST /3.1 /payments.

One of two scenarios will apply:

    If the payment finishes successfully, the payment with 'captured' status should be created.

Example of create payment cURL request:

curl -X POST \ \
  -H 'Content-Type: application/json' \
  -H 'X-Publisher-Token: a6xxki_mf493WSBjEs9D-UpN-0kyESWYPUQo9S6nEewTyuL7'
  -d '{
     "orderId": 343967543,
     "status": "captured",
     "paymentDetails": {
        "token": "z7xariumf493GHBjEs9D-UpN-9kyESWYPUQo9S6nEewThuD8",
        "paymentMethodSpecificParams" : {
            "holderName": "Matthew Brown",
            "lastCardFourDigits": "1111",
            "variant": "visa",
            "cardExpirationDate": "10/2019"
     "externalPaymentId": "<external-payment-id>",
     "paymentOperation": "initial-payment"
    If the payment fails, the payment with 'rejected' status should be created.

Example of reject payment cURL request:

curl -X POST \ \
  -H 'Content-Type: application/json' \
  -H 'X-Publisher-Token: a6xxki_mf493WSBjEs9D-UpN-0kyESWYPUQo9S6nEewTyuL7'
  -d '{
     "orderId": 343967543,
     "status": "rejected",
     "paymentOperation": "initial-payment",
     "rejectedReason": "Insufficient balance"

Free Trial

Free trial is a special case of purchase because the order value amounts to zero.
Handling of free trial depends on the payment gateway - whether it supports “zero-payments” or not.

  • Scenario 1: Payment gateway supports “zero” payments
    In this scenario, there is no change of flow. See Step-by-Step Guide for Initial Payment.

  • Scenario 2: Payment gateway doesn’t support “zero” payments
    This process is similar to the Initial Payment Process (see Step-by-Step Guide), with the exception in Step 4 (Process Payment):
    If there is no payment amount, depending on a payment gateway, an alternative API endpoint/method should be used to obtain the recurring token - one that will omit payment creation in the gateway.

    In Step 5 (Create Payment in Cleeng) - payment for “zero” will still be required.