Payment gateway integration guide
Detailed guidance on how to integrate Corrily with a payment gateway.
Read this guide for detailed information on how to integrate Corrily with your payment gateway. In terms of the Price optimization overview diagram, this guide covers steps 7 and 8 (sets up billing to notifies of subscription & charge events). See Pricing page integration guide for help with steps 1 to 5 (views your pricing page to displays calculated price).
Payment gateway overview explains why it's necessary to integrate Corrily with your payment gateways if you're doing price experimentation.
The general integration workflow is the same for all payment gateways. When helpful, this guide also provides specific details for the following payment gateways:
- Stripe
- Chargebee
- Recurly
- Braintree
Payment-gateway-specific sections
Whenever you see a section titled
Stripe
,Chargebee
,Recurly
orBraintree
, it means that the section contains details for that specific payment gateway. You can skip the sections of the payment gateways that you're not using. For example, if you're not using Stripe, you can skip all sections titledStripe
.
Overview
There are 2 key steps in the integration process:
- Create custom prices in your payment gateway that are correctly associated to your products
- Notify Corrily of subscription or charge events so that Corrily can improve its pricing optimization (see Payment gateway overview)
Send custom prices to your payment gateway
Many payment gateways were not created with the use case of custom prices in mind. For this reason it may take a bit of customization to get the payment gateway to support a custom price that is correctly associated to a product.
Map smallest-unit currency format to decimal format
Many payment gateways format price in a currency's smallest unit. Corrily expects all prices to be passed in decimal format. For example, if your payment gateway formats a price as 1234
, the value that you need to provide to Corrily might be 12.34
. It depends on the currency.
You can avoid this complication by including the integrations
argument when you call Corrily's calculate price endpoint. Corrily's response will include the price format that your payment gateway expects. For example, if your integrations
object is set to ["stripe"]
, you can access the Stripe-formatted price value at <data>.prices.products.<id>.integrations.stripe.amount
, where <data>
is the payload from the calculate price response, and <id>
is your product ID.
Stripe
There are multiple ways to initiate payments in Stripe. Each of them involves overriding the base amount with a custom price amount and currency provided by Corrily.
What impact does overriding have on the relationship between your Stripe price objects and Stripe products? Overriding base amounts and currencies creates a one-off price object. The one-off price object is still correctly tied to your product. However, it cannot be used in future transactions and you won't see it in your product's list of prices on your Stripe dashboard. This means you can experiment with many different price points without ruining your internal Stripe product and price object hierarchy.
The next few sections provide examples of creating custom prices.
Stripe Payment Intent
stripe.PaymentIntent.create(
amount=response_dict['products']['monthly_plan']['integrations']['stripe']['amount']
currency=response_dict['products']['monthly_plan']['display']['stripe']['currency']
)
Stripe Subscription
stripe.Subscription.create(
customer=data['customerId'],
items=[
{
'price': {
'unit_amount': response_dict['products']['monthly_plan']['integrations']['stripe']['amount']
'currency': response_dict['products']['monthly_plan']['display']['stripe']['currency'],
'product': "monthly_plan", # or whatever the matching stripe product ID is
'recurring': {
'interval': "month"
}
}
}
],
expand=['latest_invoice.payment_intent'],
)
Stripe Checkout
stripe.checkout.Session.create(
payment_method_types=['card'],
line_items=[
{
'price_data': {
'unit_amount': response_dict['products']['monthly_plan']['integrations']['stripe']['amount'],
'currency': response_dict['products']['monthly_plan']['display']['stripe']['currency'],
'product_data': {
'name': 'Stubborn Attachments',
},
'recurring': {
'interval': "month"
}
},
'quantity': 1,
},
],
mode='payment',
success_url=YOUR_DOMAIN + '/success.html',
cancel_url=YOUR_DOMAIN + '/cancel.html',
)
(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 [email protected] 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.
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
Only required when automated access is not an option
If you have granted Corrily automated access to your payment gateway's webhook events, as explained in the previous section, you can stop here.
"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
Corrily needs to be notified of subscription AND charge events
Corrily needs to know about charge events because charge events are much closer to realized revenue than subscription events. In other words, charges are more like a realized commitment to pay, whereas subscription events are more like an intent to pay. Getting both signals helps Corrily's AI models provide more optimal prices for you.
Build a webhook server
See the following docs for more guidance on building a webhook server for your particular payment gateway:
Stripe
Chargebee
Recurly
Braintree
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::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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Chargebee
Chargebee's value | Corrily's value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Recurly
Recurly's value | Corrily's value |
---|---|
|
|
|
|
|
|
|
|
|
|
Braintree
Braintree's value | Corrily's vale |
---|---|
|
|
|
|
|
|
|
|
|
|
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
, andcharge.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::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
Stripe's value | Corrily's value |
---|---|
|
|
|
|
|
|
|
|
|
|
Chargebee
Charbee's value | Corrily's value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Recurly
Recurly's value | Corrily's value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Braintree
Braintree's value | Corrily's value |
---|---|
|
|
|
|
Updated 4 months ago