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 https://api.pinpayments.com/1/plans -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-12-11T05:27:13Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_permissions": [
      "cancel"
    ],
    "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 https://api.pinpayments.com/1/customers -u your-secret-api-key: \
 -d "email=roland@pinpayments.com" \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w"
201 Created
{
  "response": {
    "token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "email": "roland@pinpayments.com",
    "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 https://api.pinpayments.com/1/subscriptions -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-12-11T05:27:13Z",
    "active_interval_started_at": "2024-12-11T05:27:13Z",
    "active_interval_finishes_at": "2024-12-11T05:27:13Z",
    "cancelled_at": null,
    "created_at": "2024-12-11T05:27:13Z",
    "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.

Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.