Custom integration

​

(Recommended) Provide automated access of subscription and charge events

The easiest and recommended way to notify Corrily of subscription and charge events is to grant Corrily automated access to your payment gateway’s webhook events. Email api@corrily.com to get started. If you’re using Stripe and would like to get your Corrily integration started now, click the Connect with Stripe button to grant Corrily read-only access to your Stripe subscription and charge events. Connect with Stripe If for whatever reason you cannot or do not want to grant Corrily automated access, you can manually notify Corrily instead.

​

Manually notify Corrily of subscription and charge events

​

The basic workflow

• You set up your own webhook server
• Your webhook server receives subscription and charge events from your payment gateway
• Your webhook server extracts only the data that Corrily needs and sends it to Corrily via the subscription and charge REST API endpoints

​

Build a webhook server

See the following docs for more guidance on building a webhook server for your particular payment gateway:

​

Stripe

• Receive event notifications with webhooks
• Using webhooks with subscriptions

​

Chargebee

• Events and Webhooks
• Webhook Settings

​

Recurly

• Webhooks

​

Braintree

• Webhooks

​

Handle subscription events

Payment gateways emit webhook events over the entire subscription lifecycle. Keeping Corrily up-to-date on important events helps Corrily determine optimal prices for your customers. Examples of important events include:

• Signing up for a trial
• Converting to a paying customer
• Switching to a higher or lower price
• Canceling a subscription

The following sections detail which events you need to handle, depending on your payment gateway.

​

Stripe

• customer.subscription.created
• customer.subscription.updated

​

Chargebee

• subscription_created
• subscription_activated
• subscription_cancelled
• subscription_changed

​

Recurly

• new_subscription_notification
• updated_subscription_notification
• canceled_subscription_notification

​

Braintree

• Braintree::WebhookNotification::Kind::SubscriptionCanceled
• Braintree::WebhookNotification::Kind::SubscriptionExpired
• Braintree::WebhookNotification::Kind::SubscriptionTrialEnded
• Braintree::WebhookNotification::Kind::SubscriptionWentActive
• Braintree::WebhookNotification::Kind::SubscriptionWentPastDue

​

Send subscription data to Corrily

Use Corrily’s Create subscription and Update subscription REST API endpoints to send the data from your webhook server to Corrily.

​

Handle subscription discounts

If you are providing a discount to a user, you should send Corrily the price that the user paid. You should not try to represent the discount with multiple calls to the Corrily API.

​

Map your payment gateway’s subscription statuses to Corrily’s values

The following tables explain how to map your payment gateways status values to Corrily’s values.

Stripe

Stripe’s value	Corrily’s value
incomplete	pending
incomplete_expired	pending
trialing	trialing
active	active
past_due	active
canceled	canceled
unpaid	canceled

Chargebee

Chargebee’s value	Corrily’s value
future	pending
in_trial	trialing
active	active
non_renewing	canceled
paused	canceled
canceled	canceled

Recurly

Chargebee’s value	Corrily’s value
future	pending
in_trial	trialing
active	active
expired	canceled
canceled	canceled

​

Braintree

Braintree’s value	Corrily’s value
Active	active
Canceled	canceled
Expired	canceled
PastDue	active
Pending	pending

​

Handle charge events

Keeping Corrily up-to-date on important charge events helps Corrily confirm that the price it generated for a visitor was optimal. For example, a new subscription is a slight signal that a price was optimal. When the customer allows their card to be charged for the subscription, that’s further confirmation that the price was optimal. The following sections detail which charge events you need to handle, depending on your payment gateway.

​

Stripe

• invoice.paid

Stripe refers to one-time charge events as invoice events.

​

Chargebee

• payment_succeeded
• payment_refunded

On payment events (which pay for subscriptions) Chargebee sends your webhook server transaction, customer, and subscription objects. The transaction object contains the amount that was paid (or refunded, depending on the transaction type). The transaction object contains the data that needs to be passed to Corrily.

​

Recurly

• successful_payment_notification
• successful_refund_notification

​

Braintree

• Braintree::WebhookNotification::Kind::SubscriptionChargedSuccessfully
• Braintree::WebhookNotification::Kind::SubscriptionChargedUnsuccessfully

​

Send charge data to Corrily

Use Corrily’s Create charge and Update charge REST API endpoints to send the invoice data from your webhook server to Corrily.

​

Handle charge discounts

If you are providing a discount to a user, you should send Corrily the price that the user paid. You should not try to represent the discount with multiple calls to the Corrily API.

​

Map your payment gateway’s charge statuses to Corrily’s values

The following tables explain how to map your payment gateways status values to Corrily’s values.

Stripe

Stipe’s value	Corrily’s value
draft	pending
open	pending
paid	succeeded
uncollectible	failed
void	failed

Chargebee

Chargebee’s value	Corrily’s value
in_progress	pending
success	succeeded
voided	failed
failure	failed
timeout	failed
needs_attention	failed

Recurly

Recurly’s value	Corrily’s value
pending	pending
processing	pending
success	succeeded
chargeback	succeeded
error	failed
declined	failed

Braintree

Braintree’s value	Corrily’s value
Braintree::WebhookNotification::Kind::SubscriptionChargedSuccessfully	succeeded
Braintree::WebhookNotification::Kind::SubscriptionChargedUnsuccessfully	failed