Introduction to payment webhooks
The different ways you can track customer payments on PartnerStack, so your partners can be rewarded for revenue attributed to them.
After customer records have been created in PartnerStack (either through PartnerStackJS or our APIs), you can use our platform to automatically track payments those customers make for your product or service. Since all customers are tied to the partner who referred them in PartnerStack, this means partners are automatically attributed for revenue they drove.
📎 Using our payment provider webhooks
Using our payment provider webhooks, you can have your payment platform send PartnerStack events whenever a customer pays for your product. We support webhooks from Stripe, Chargebee, Recurly and Chargify.
How our webhook integration works
When we receive an event from your payment platform that a payment was successful, we first try to find a customer in PartnerStack using information in the event. The way this works differs per platform:
| Platform | How a customer is identified |
|---|---|
| Stripe | When we receive a customer.created or customer.updated event, we check the event metadata for a customer_key field. If one matches a customer key in PartnerStack, we sync the Stripe Customer ID as the customer's provider key in PartnerStack. Future charge.succeeded events are now tracked automatically. |
| Chargebee | We check to see if the customer_key field is present in the customer.meta_data object of a payment_succeeded event. If one is, we look for a customer in PartnerStack with the same customer key. |
| Recurly | We check for a customer in PartnerStack whose customer key equals the value of the <account_code> attribute sent in a successful_payment_notification |
| Chargify | We check for a customer in PartnerStack whose customer key equals the payload[subscription][customer][reference] field of a payment_success event. |
After we've identified the customer, we record the transaction amount under the customer in PartnerStack.
Implementing webhooks
Heads up!
Implementing webhooks is a process that requires development effort. It should be done by someone with an understanding of your payment and signup flow on your website's back-end.
To implement webhooks, visit the guide for either Stripe, Chargebee, Recurly or Chargify depending on your provider. In general, you'll need to do 2 things:
-
Add the PartnerStack webhook URL (copied from your dashboard) to your payment platform and set it up to send the right events.
-
If you're using a Stripe or Chargebee webhook, you need to ensure that new customers are created with the
customer_keyin their metadata. This customer key is the same one you provided when you create a customer using PartnerStackJS or in the Customers API.
- If using Recurly, you must ensure that the customer key in PartnerStack matches the Recurly Account Code
- If using Chargify, you must ensure that the customer key in PartnerStack matches the Chargify Customer Reference
Refund processing
For some payment providers, we're also able to process refund events which archive the original transaction in PartnerStack. Please refer to the specific documentation for your webhooks for more information on which events are accepted.
💻 Using the Transactions API
For the most control over what transactions are sent to PartnerStack and how they appear on the platform, you can use our Transactions REST API from your website's back-end. The POST /api/v2/transactions endpoint accepts these body parameters:
| Parameter | Description |
|---|---|
amount (integer) | The amount the customer paid in cents (required) |
category_key (string) | An optional, arbitrary string to identify what type of transaction this was (for example, monthly). Reward generation can be customized based on category key. |
currency (string) | ISO 3-character currency code |
product_key (string) | An optional, arbitrary string to identify what type of transaction this was (for example, basic_plan). Reward generation can be customized based on product key. |
customer_key or customer_external_key or customer_email (string) | The reference to the customer. Exactly and only one of the three must be provided. - customer_key is the internal customer_key- customer_external_key is your unique identifier of the customer in PartnerStack. This is the same as the customer_key value used when creating the customer with PartnerStackJS.- customer_email is the customer's email address |
Once we receive an API request, the transaction will be recorded under the appropriate customer and automatically attributed to the partner who referred them. For more information, check out the PartnerStack API reference.
📄 Importing a CSV of transactions
If neither of the above options work well for you, you can upload a CSV containing transactions your customers made at any time on your dashboard. For more information on the fields required, see our documentation for the Universal Importer. The CSV can also be uploaded programmatically via our API.
Updated about 1 year ago