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:
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"{
"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": "2023-04-01T10:30:00Z",
"token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_permissions": [
"cancel"
],
"subscription_counts": {
"trial": 0,
"active": 0,
"cancelling": 0,
"cancelled": 0
}
}
}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"{
"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": "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": 2024,
"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
}
}
}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"{
"response": {
"state": "active",
"next_billing_date": "2023-04-01T10:30:00Z",
"active_interval_started_at": "2023-04-01T10:30:00Z",
"active_interval_finishes_at": "2023-04-01T10:30:00Z",
"cancelled_at": null,
"created_at": "2023-04-01T10:30:00Z",
"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.
You can see the state of all customer subscriptions in your dashboard. Learn more about managing subscriptions in your dashboard.