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 Quickpay

POST /subscriptions Create subscription

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

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.

Parameter Description Parameter type Data type Required?
order_id Unique order number form string true
currency Currency form string true
description Subscription description form string true

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.quickpay.net/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

PUT /subscriptions/{id}/link Create or update a payment link

Next step is to authorize the subscription.

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

Selected parameters. See more in the API documentation.

Parameter Description Parameter type Data type Required?
id Transaction id path integer true
amount Amount to authorize form integer true

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.quickpay.net/subscriptions/97629173/link

Example response:

1
2
3

{
  "url":"https://payment.quickpay.net/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

POST /subscriptions/{id}/recurring Create subscription 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.

Parameter Description Parameter type Data type Required?
id Subscription id path integer true
amount Amount form integer true
order_id Unique order number form string true
auto_capture When true, payment is captured after authorization. Default is false form boolean false

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.quickpay.net/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.