API Reference

Subscriptions API

The subscriptions API allows you to create subscriptions against plans and retrieve the details of existing subscriptions.

POST /subscriptions

Activate a new subscription and returns its details. The customer’s card will immediately be billed the initial plan amount, unless there’s a trial period.

Parameters

plan_token The token of the plan to subscribe to, as returned from the plans API.
customer_token The token of the customer to be subscribed, as returned from the customers API.
Optional include_setup_fee Whether the setup fee should be applied to this subscription. Default value is true.

Example

curl https://test-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": "2023-05-31T20:21:04Z",
    "active_interval_started_at": "2023-05-31T20:21:04Z",
    "active_interval_finishes_at": "2023-05-31T20:21:04Z",
    "cancelled_at": null,
    "created_at": "2023-05-31T20:21:04Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_request {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters are missing or invalid.",
  "messages": [
    {
      "param": "plan_token",
      "message": "must be present"
    }
  ]
}
404 resource_not_found {...} 
{
  "error": "resource_not_found",
  "error_description": "No resource was found at this URL."
}

GET /subscriptions

Returns a paginated list of all subscriptions.

Example

curl https://test-api.pinpayments.com/1/subscriptions -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "state": "active",
      "next_billing_date": "2023-05-31T20:21:04Z",
      "active_interval_started_at": "2023-05-31T20:21:04Z",
      "active_interval_finishes_at": "2023-05-31T20:21:04Z",
      "cancelled_at": null,
      "created_at": "2023-05-31T20:21:04Z",
      "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
      "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
      "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
      "card_token": "card_nytGw7koRg23EEp9NTmz9w"
    }
  ],
  "count": 1,
  "pagination": {
    "count": 1,
    "per_page": 25,
    "current": 1
  }
}

GET /subscriptions/sub-token

Returns the details of the subscription identified by subscription token.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key:
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2023-05-31T20:21:04Z",
    "active_interval_started_at": "2023-05-31T20:21:04Z",
    "active_interval_finishes_at": "2023-05-31T20:21:04Z",
    "cancelled_at": null,
    "created_at": "2023-05-31T20:21:04Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

PUT /subscriptions/sub-token

Updates the card associated with a subscription identified by subscription token.

card_token A card token belonging to the customer that will be charged for this subscription. Setting to null will use the customer's default card.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X PUT \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w"
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2023-05-31T20:21:04Z",
    "active_interval_started_at": "2023-05-31T20:21:04Z",
    "active_interval_finishes_at": "2023-05-31T20:21:04Z",
    "cancelled_at": null,
    "created_at": "2023-05-31T20:21:04Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_request {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters are missing or invalid.",
  "messages": [
    {
      "param": "card_token",
      "message": "must be present"
    }
  ]
}
404 resource_not_found {...} 
{
  "error": "resource_not_found",
  "error_description": "No resource was found at this URL."
}

DELETE /subscriptions/sub-token

Cancels the subscription identified by subscription token. Subscriptions can only be cancelled if they are in trial or active state.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X DELETE
200 OK 
{
  "response": {
    "state": "cancelled",
    "next_billing_date": null,
    "active_interval_started_at": "2023-05-31T20:21:04Z",
    "active_interval_finishes_at": "2023-05-31T20:21:04Z",
    "cancelled_at": "2023-05-31T20:21:04Z",
    "created_at": "2023-05-31T20:21:04Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_state {...} 
{
  "error": "invalid_state",
  "error_description": "Cannot cancel subscription when state is cancelled"
}
404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

PUT /subscriptions/sub-token/reactivate

Reactivates the subscription identified by subscription token, returning the details of the subscription.

Optional include_setup_fee Whether the setup fee should be applied to this subscription. Default value is true.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ/reactivate -u your-secret-api-key: -X PUT
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2023-05-31T20:21:04Z",
    "active_interval_started_at": "2023-05-31T20:21:04Z",
    "active_interval_finishes_at": "2023-05-31T20:21:04Z",
    "cancelled_at": null,
    "created_at": "2023-05-31T20:21:04Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /subscriptions/sub-token/ledger

Fetch the ledger entries relating to a subscription identified by subscription token.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ/ledger -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "created_at": "2023-05-31T20:21:04Z",
      "type": "credit",
      "amount": 1000,
      "currency": "AUD",
      "annotation": "charge_credit"
    }
  ],
  "count": 1,
  "pagination": {
    "count": 1,
    "per_page": 25,
    "current": 1
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

Southern Payment Systems Pty Ltd
t/a Pin Payments
ABN: 46 154 451 582
Level 4, 356 Collins St,
Melbourne VIC 3000

A Checkout.com company

Privacy Policy Terms Security Status