Subscription Initial Purchase

👍

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

Overview

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.

📘

Note

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

Step-by-Step Guide

📘

Note

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 \
  https://api.cleeng.com/3.1/orders \
  -H 'Content-Type: application/json' \
  -H 'X-Publisher-Token: hsEJu1srZcRzM6BGOCfEtvCZyjktbn0R1c7n-vT0lchtVP11' \
  -d '{
    "customerId":"927751142",
    "offerId":"S619117184_US",
    "currency":"USD",
    "country":"US",
    "paymentMethodId":123876432
}'

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.

👍

Tip

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).

Note:
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. This token must be stored as user payment details in Cleeng.

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:

• SUCCESS: CREATE PAYMENT
  If the payment finishes successfully, the payment with captured status should be created.

Example of create payment cURL request:

curl -X POST \
  https://api.cleeng.com/3.1/payments \
  -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"
  }

• FAILURE: CREATE REJECTED PAYMENT
  If the payment fails, the payment with rejected status should be created.

Example of reject payment cURL request:

curl -X POST \
  https://api.cleeng.com/3.1/payments \
  -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.