A common use of Reepay is to have customers in own system and customer subscriptions in Reepay, where at any time a customer will have at most one active subscription.

This simple use case demonstrates how Reepay can be used for signup, access control and subscription management without storing any data on own system except the customer with a unique id. At some point the solution could be extended to keep data on own system for quick access. This could be done by synchronizing data between Reepay and own system using webhooks.

Signup

A user wants to sign up to a subscription plan for the first time. The user does not exist in Reepay. A signup page in own system can take the following three steps:

1. Select plan - this might be an optional step, if only one plan is used. Otherwise let the user choose between a number of plans defined in Reepay. The plan handle must be used to reference the plan at Reepay.
2. Create subscription and customer
3. Get payment information from customer

For details on the signup process follow the guide here.

A subscription now exists for the customer. The handle for the subscription is the reference for the subscription that can be stored in your system. We recommend using a supplied handle, but it is also possible to use the argument generate_handle=true instead of handle to let Reepay generate a handle.

Access control

At various points the system might need to check if a customer has access to some service, special price, or the like. This can be done by getting the active subscriptions for a customer and using the plan handle to determine which services are accessible. Active subscriptions can be fetched with (only one should be returned):

curl -X GET \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Content-Type: application/json' \
https://api.reepay.com/v1/list/subscription?customer=cust-001&state=active

The subscription object returned will contain plan.

...
"state": "active",
"plan": "gold",
...

For full details on fetching subscriptions see: Get list of subscriptions and for full details on the subscription see Subscription object

Subscription management

A page in your own system can provide subscription management for the customer. The page can contain the following functionality:

1. Show active subscription
2. Signup to plan if no active subscription
3. Cancel/uncancel subscription
4. Change payment method on existing subscription

Other functionalities like plan upgrade and downgrade can easily be added. See the subscription resource

Show active subscription

Active subscriptions for customer can be fetched with the call described above.

Signup to plan if no active subscription

Resembles a signup except the fact that customer might already exists in Reepay. To determine if a user exists use: Get customer . If user exists use the following call:

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "plan": "gold",
  "signup_method": "source",
  "customer": "cust-001",
  "generate_handle": true,
  "source": "ct_e4926c46be444fcbbc809be06abfd706"
}' \
https://api.reepay.com/v1/subscription

When signing up to a new subscription for an existing customer in Reepay a new payment method can be saved for the customer using Reepay Checkout as described in the signup part and payment method provided as source. Another option is to let the customer use an already entered payment method if such exists. Existing payment methods can be fetched with:

curl -X GET \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Content-Type: application/json' \
https://api.reepay.com/v1/list/payment_method?customer=cust-001

A list of payment methods will be returned.

{
 [
    {
      "id": "ca_fcfac2016614418f969fa5697383e47c",
      "state": "active",
      "masked_card": "457111XXXXXX3777",
      ...
    }
   ...
  ]
}

Active cards can be presented to the customer with masked card number. Existing cards can be used as an option for payment method for the new subscription. The customer could choose between existing card or entering a new card. If an existing card is to be used as payment method the create subscription call should be used (only difference is the prefix on the source):

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "plan": "gold",
  "signup_method": "source",
  "customer": "cust-001",
  "generate_handle": true,
  "source": "ca_fcfac2016614418f969fa5697383e47c"
}' \
https://api.reepay.com/v1/subscription

Cancel/un-cancel subscription

A subscription can be cancelled, meaning that it will expire after the current billing period, or what is specified by potential notice and binding period on subscription plan. To determine if a subscription is cancelled the following attribute in the subscription object can be used:

"is_cancelled": "false"

If a subscription is not cancelled an option on the subscription management page can be provided. A subscription can be cancelled with:

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Content-Type: application/json' \
https://api.reepay.com/v1/subscription/{handle}/cancel

If a subscription is cancelled the subscription can be reinstated by cancelling the cancellation. This can be done with:

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Content-Type: application/json' \
https://api.reepay.com/v1/subscription/{handle}/uncancel

Change payment method on existing subscription

If the user wants to change payment method for the subscription this can be done in a number of ways:

Let the user choose between existing payment method or enter a new one on own page as described above for sign up for existing user, or just direct the user to a hosted page at Reepay.

The subscription object provides a link to a page:

"hosted_page_links": {
  "payment_info": "https://subdomain.reepay.com/paymentinfo/myaccount/4bc5f5f5536146a8b745aeab555162df"
},

The page provides a simple card entering page for changing card on subscription.