Integration Guides
Overview Hosted Fields 3D Secure Customers Recurring Payments Marketplaces Apple Pay Google Pay Webhooks Payment Forms Pin.jsRecurring 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:
- Create a plan object for your customers to subscribe to.
- Store a customer’s billing details as a customer object.
- 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"{
"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-04-18T20:57:27Z",
"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"{
"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"{
"response": {
"state": "active",
"next_billing_date": "2024-04-18T20:57:27Z",
"active_interval_started_at": "2024-04-18T20:57:27Z",
"active_interval_finishes_at": "2024-04-18T20:57:27Z",
"cancelled_at": null,
"created_at": "2024-04-18T20:57:27Z",
"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.
