Introduction to Subscriptions

Subscriptions is the preffered way to automate recurring withdrawals from your customers.

Subscription flow

1. Create a new subscription
2. Authorize subscription using a link
3. Create a recurring payment

1. Create a new subscription in CoolPay

First step is to create a new subscription entity in CoolPay.

On a new subscription you are required to include a unique order id, the currency and a description of the subscription.

Selected parameters. See more in the API documentation.

Example request:

1
2
3
4
5
6

curl -u ':APIKEY \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X POST \
     -d '{"order_id":"sub10003","currency":"eur","description":"shoe-sub"}' \
     https://api.coolpay.com/subscriptions

Example response (snippet):

1
2
3
4
5
6
7
8
9
10

{
  "id":97629173,
  "merchant_id":1234,
  "order_id":"sub10004",
  "accepted":false,
  "type":"Subscription",
  "currency":"EUR",
  "state":"initial"
  ...
}

2. Authorize the subscription

Next step is to authorize the subscription.

The recommended way is to request the CoolPay API for a payment link, where your customer can fill in their card information.

Selected parameters. See more in the API documentation.

Example request:

1
2
3
4
5
6

curl -u ':APIKEY' \
	   -H 'content-type:application/json' \
	   -H 'Accept-Version:v10' \
	   -X PUT \
	   -d '{"amount":1000}' \
	   https://api.coolpay.com/subscriptions/97629173/link

Example response:

1
2
3

{
  "url":"https://payment.coolpay.com/subscriptions/26d41592d35c1415ed291c87da1890e1903941ac782e4727ffb18c303d085cde"
}

When your customer has filled in the card information using the link, the subscription is now authorized.

No funds are withdrawn from your customer yet.

3. Create recurring payment

As of now the customers card is authorized, but no funds has been withdrawed from their account.

Each time the customers card should be charged, your system will need to create a recurring payment. A recurring payment is just like a regular payment, but is automatically authorized using the subscription card.

Selected parameters. See more in the API documentation.

Example request:

1
2
3
4
5
6


curl -u ':APIKEY' \
	   -H 'content-type:application/json' \
	   -H 'Accept-Version:v10' \
	   -X POST \
	   -d '{"amount":1000,"order_id":"rec10001"}' \
	   https://api.coolpay.com/subscriptions/97629173/recurring

Example response (snippet):

1
2
3
4
5
6
7
8
9

{
  "id":97629687,
  "merchant_id":1234,
  "order_id":"rec10001",
  "accepted":false,
  "type":"Payment",
  "state":"pending"
  ...
}

In the response the payments state is pending, as the authorize is not yet approved or rejected by your acquirer.

Use GET /payments/97629687 to check the payment status, by looking at the accepted parameter.

If you are selling a digital products, you can include "auto_capture":"true" in the recurring request, to capture the payment automatically after the authorize.

If you are selling a physical product, you can capture the payment using POST /payments/{id}/capture when you are ready to ship the product.