Recurring Payments with our Subscription API

Pin Payments includes APIs to create and manage customers, plans, and subscriptions. These APIs can be used to create and manage subscriptions to recurring payment plans.

The process to integrate subscription billing is as follows:

  1. Create a plan object for your customers to subscribe to.
  2. Store a customer’s billing details as a customer object.
  3. Subscribe the customer to the corresponding plan.

1. Create a recurring payment plan

Use the plans API to create a plan for your customers to subscribe to:

curl -u your-secret-api-key: \
 -d "name=Coffee Plan" \
 -d "amount=1000" \
 -d "currency=USD" \
 -d "interval=30" \
 -d "interval_unit=day" \
 -d "intervals=6" \
 -d "setup_amount=0" \
 -d "trial_amount=0" \
 -d "trial_interval=7" \
 -d "trial_interval_unit=day" \
 -d "customer_permissions[]=cancel"
201 Created
  "response": {
    "name": "Coffee Plan",
    "amount": 1000,
    "currency": "USD",
    "setup_amount": 0,
    "trial_amount": 0,
    "interval": 30,
    "interval_unit": "day",
    "intervals": 6,
    "trial_interval": 7,
    "trial_interval_unit": "day",
    "created_at": "2024-02-28T09:03:25Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_permissions": [
    "subscription_counts": {
      "trial": 0,
      "active": 0,
      "cancelling": 0,
      "cancelled": 0

2. Store a customer’s billing information

When building your customer-facing subscription flow, you can use Hosted Fields to securely store a customer’s billing information as a card token.

With the customer’s email and a card token representing their billing information, you can create a customer token:

curl -u your-secret-api-key: \
 -d "" \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w"
201 Created
  "response": {
    "token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "email": "",
    "first_name": "Roland",
    "last_name": "Robot",
    "phone_number": "1300 364 800",
    "company": "Pin Payments",
    "notes": "Account manager at Pin Payments",
    "created_at": "2023-06-22T06:27:33Z",
    "card": {
      "token": "card_nytGw7koRg23EEp9NTmz9w",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2025,
      "name": "Roland Robot",
      "address_line1": "42 Sevenoaks St",
      "address_line2": "",
      "address_city": "Lathlain",
      "address_postcode": "6454",
      "address_state": "WA",
      "address_country": "Australia",
      "network_type": null,
      "network_format": null,
      "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
      "primary": true

3. Subscribe the customer to the plan

You can now subscribe the customer to the corresponding plan, using the customer token you just created:

curl -u your-secret-api-key: \
 -d "plan_token=plan_ZyDee4HNeUHFHC4SpM2idg" \
 -d "customer_token=cus_XZg1ULpWaROQCOT5PdwLkQ" \
 -d "include_setup_fee=false"
201 Created
  "response": {
    "state": "active",
    "next_billing_date": "2024-02-28T09:03:25Z",
    "active_interval_started_at": "2024-02-28T09:03:25Z",
    "active_interval_finishes_at": "2024-02-28T09:03:25Z",
    "cancelled_at": null,
    "created_at": "2024-02-28T09:03:25Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"

The customer’s card will be billed according the plan’s billing schedule. If successful, the customer will be subscribed to your plan, and they will receive an email confirming their subscription. A corresponding webhook event is also created.

Managing subscriptions in your dashboard

You can see the state of all customer subscriptions in your dashboard. Learn more about managing subscriptions in your dashboard.