Recurring Payments

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 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 "setup_amount=0" \
 -d "trial_amount=0" \
 -d "trial_interval=7" \
 -d "trial_interval_unit=day"
201 Created
{
  "response": {
    "name": "Coffee Plan",
    "amount": 1000,
    "currency": "USD",
    "setup_amount": 0,
    "trial_amount": 0,
    "interval": 30,
    "interval_unit": "day",
    "trial_interval": 7,
    "trial_interval_unit": "day",
    "created_at": "2018-12-14T14:28:07Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "active_subscriptions": 0,
    "trial_subscriptions": 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",
    "created_at": "2012-06-22T06:27:33Z",
    "card": {
      "token": "card_nytGw7koRg23EEp9NTmz9w",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "US",
      "expiry_month": 5,
      "expiry_year": 2019,
      "name": "Roland Robot",
      "address_line1": "42 Sevenoaks St",
      "address_line2": "",
      "address_city": "Lathlain",
      "address_postcode": "6454",
      "address_state": "WA",
      "address_country": "Australia",
      "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 "card_token=card_nytGw7koRg23EEp9NTmz9w" \
 -d "include_setup_fee=false"
201 Created
{
  "response": {
    "state": "active",
    "trial_started_at": "2018-12-14T14:28:07Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:28:07Z",
    "current_period_started_at": "2018-12-14T14:28:07Z",
    "current_period_ends_at": "2018-12-14T14:28:07Z",
    "cancelled_at": "2018-12-14T14:28:07Z",
    "created_at": "2018-12-14T14:28:07Z",
    "updated_at": "2018-12-14T14:28:07Z",
    "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 is owned and operated by
Southern Payment Systems Pty Ltd
ABN: 46 154 451 582
Level 1, 34 Queen St,
Melbourne VIC 3000

Privacy Policy Terms Security Status

Australia