Custom Integration
Manually notify Corrily of subscription and charge events
“Charge” events is a generic term in this guide
In this guide we use the word “charge” to refer to a non-recurring payment. Different payment gateways use different words for this concept. When reading your payment gateway’s documentation, “charge” may not be the word you’re looking for.
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:
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
Chargebee
Recurly
Braintree
Braintree::WebhookNotification::Kind::SubscriptionCanceledBraintree::WebhookNotification::Kind::SubscriptionExpiredBraintree::WebhookNotification::Kind::SubscriptionTrialEndedBraintree::WebhookNotification::Kind::SubscriptionWentActiveBraintree::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
Stripe refers to one-time charge events as invoice events.
Why not use Stripe charges instead?
Stripe invoice events are closer to payments for individual subscriptions than Stripe charges are. In Stripe, charges pay for invoices which may contain payments for more than just a single subscription. If however it’s easier for you to handle charges, you can also look to handle Stripe’s charge.captured, charge.refunded, charge.updated, and charge.succeeded events.
Chargebee
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
Braintree
Braintree::WebhookNotification::Kind::SubscriptionChargedSuccessfullyBraintree::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 |