Reepay Technical Documentation

Hello Developer!

Welcome to the Reepay API developer hub. You'll find comprehensive guides and documentation to help you get started working with the Reepay API as quickly as possible, as well as support you if your stuck.

Let's jump right in!

Get Started

Simple subscription handling

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
  2. Create customer & payment information
  3. Create a subscription

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 customer & payment information

Use Reepay Checkout to create a customer and store the customers card. In this example we use the Modal.

2.1 Create a recurring session

Use the Reepay Checkout API to make a recurring session for the customer "Spongebob". The handle customer-2 is the customer id from own system. If the customer already exists the the existing customer will be used with the customer information already at Reepay.

curl --request POST \
  --url https://checkout-api.reepay.com/v1/session/recurring \
  -u '<your private key>:' \
  --header 'content-type: application/json' \
  --data '{
  	"button_text":"Save",
  	"create_customer":{
  	    "email":"bob@hotmail.com",
  	    "address":"124 Conch Street",
  	    "address2":"Bikini Bottom",
  	    "city":"Pacific Ocean",
  	    "handle":"customer-2",
  	    "first_name":"Spongebob",
  	    "last_name":"Squarepants"
  	}
  }'

Response

{
  "id":"cs_dc70e0827dbbdb5dbf5fdc3faa5788da"
  "url":"https://checkout.reepay.com/#/cs_dc70e0827dbbdb5dbf5fdc3faa5788da"
}
Key
Type
Description

id

string

Session id for opening the Checkout window with the Web SDK

url

string

A url for the checkout window that can be used directly.

2.2 Include the Checkout Web SDK

Read more about different ways to use Checkout

<script src="https://checkout.reepay.com/checkout.js"></script>

2.3 Open the window as overlay (modal)

var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE ');

rp.addEventHandler(Reepay.Event.Accept, function(data) {
  console.log('Success', data);
  
  // The customer handle will be in this
  console.log(data.customer)
  
  // The customers payment information will be in this
  console.log(data.payment_method)
  
});

3. Create a subscription

A subscription is created with a single atomic call. The customer is returned from previous step together with payment_method which is a reference to the payment method stored for the customer in Reepay. It will begin with ca_.... The payment method must be given in the argument source when creating subscription.

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "plan": "gold",
  "signup_method": "source",
  "customer": '<customer_handle>',
  "handle": "s-100",
  "source": '<payment_method>'
}' \
https://api.reepay.com/v1/subscription

For full details on the create subscription operation, see: Create subscription.

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/subscription?search=customer.handle: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/customer/cust-001/payment_method

A list of cards will be returned.

{
  "cards": [
    {
      "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.

Simple subscription handling


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.