Implement Merchant IC+ Pricing Model
Interchange Plus (IC+) is a pricing model for credit card processing, where merchants are billed for processing fees, (interchange fees), rather than interchange fees being applied in real time. In addition to interchange fees, processors charge a markup, referred to by the “Plus.” Interchange and markup fees are calculated and billed to merchants at the end of each billing cycle.
IC+ provides the most transparent pricing for your merchants by calculating breaking down the card network processing costs vs. the processor costs of each transaction. A number of data points factor into a given transaction’s processing cost, which is what gets tracked and calculated. Rather than approximating processing costs and charging a standard fee across all transactions (as with our out-of-the-box blended rate pricing), Merchant IC+ pricing allows WePay to track interchange costs per transaction, in addition to WePay processing fees and your platform fees, and then to compile a billing statement for merchants at the end of each billing cycle.
Use this guide if your signed contract with WePay indicates that your platform has access to the Merchant IC+ feature.
An IC+ pricing model breaks down fees into the following three categories:
- Interchange fees from issuing banks
- Fees & assessments charged from the card network*
- Processor Markup where Markup = X% + Y¢ (a percentage fee and a per transaction fee)
* Some monthly fees may be estimated by WePay, as those are reported at platform level.
Conversely, a Merchant IC+ pricing model breaks down fees into the following three categories:
- Interchange fees from issuing banks
- Fees & assessments charged from the network*
- Platform Markup where Markup = X% + Y¢(a percentage fee and a per transaction fee)
To implement Merchant IC+, you’ll use the pricing API to set the fixed and variable amounts that your platform will charge per transaction. At the end of the billing cycle, your pricing will be added to the merchant’s bill in addition to the interchange fees. For instance, your platform may want to charge a higher percentage rate for credit card transactions than for ACH/Echeck transactions, and may want to apply a $0.50 flat rate across both credit card and ACH/Echeck transactions. Setting a fee pricing like this will be outlined in this guide.
Set Up
Before getting started, be sure to subscribe to the following Notifications:
billing_statements.createdadjustments.createdrecoveries.completedaccounts.created*recoveries.created*recoveries. failed*
* Subscribing to these Notification event topics is recommended, but not mandatory for a functional Merchant IC+ integration.
The billing statement Notification will give you the Account and the amount details of fees owed, but it does not reflect the actual money movement related to Merchant IC+ to and from an Account. Adjustment and Recovery Notifications will reflect money movement to and from an Account in association with Merchant IC+. To help differentiate an Merchant IC+ related Recovery or Adjustment Notification from other types of Recoveries and Adjustments, you can look at the reason JSON block in Notifications.
Process Diagram
To find out more about what getting notified looks like, see the section below on Consume Billing Statements.
Define Merchant IC+ Pricing
This section outlines how to set the markup fees on each transaction.
Use the pricing parameter on the POST /accounts request with the merchant’s currency. For merchants using an alternate method of payments such as eCheck, you can define the pricing using the argument payment_bank.
Using Merchant IC+, you can define pricing for the following:
- Authorizations
- Refunds
- Recurring fees
- Credit card markup fees
- ACH/eCheck standard fees
In addition, you can define a recurring fee from a merchant to your platform.
Authorization Fees:
Set a fixed amount to charge merchants per credit card authorization attempt, regardless of down-stream approval or decline. On either a POST /accounts or a POST /accounts/{id} request, use the pricing.currencies.USD.credit_card.interchange_plus.auth.fixed_fee_markup_amount parameter. Note that this integer value describes the fee in cents, so a value of 2 describes $0.02, 20 describes $0.20, and so on.
Refund Fees:
Keep fees when a credit card or ACH/eCheck transaction gets refunded. The full amount gets refunded to the payer, and the merchant covers fees to your platform. On either a POST /accounts or a POST /accounts/{id} request, set refund fees for credit card transactions by setting the pricing.currencies.USD.credit_card.interchange_plus.refund_fee_for_transaction_markup parameter to true. Similarly, set refund fees for ACH/eCheck payments on the same request by setting the pricing.currencies.USD.payment_bank.standard.refund_fee_for_transaction_markup parameter to true.
Recurring Fees:
Charge merchants a recurring fee for services rendered by your platform. Currently, WePay supports monthly recurrence. The merchant’s WePay balance will be debited, and the credit will be made to your platform account. On either a POST /accounts or a POST /accounts/{id} request, set a recurring fee amount with the pricing.currencies.USD.recurring_fee.amount parameter, and the schedule with the pricing.currencies.USD.recurring_fee.period set to monthly.
Credit Card Markup Fees:
Define a fixed dollar amount, and a percentage to charge per transaction. On either a POST /accounts or a POST /accounts/{id} request, use the pricing.currencies.USD.credit_card.interchange_plus.transaction structure. BPS represents percentage points, so a value of 295 represents 2.95%. Again, the fixed fee is represented in cents.
ACH/eCheck Standard Fees:
Since ACH/eCheck transactions are not subject to interchange fees, you may only define standard pricing here. On either a POST /accounts or a POST /accounts/{id} request, use the pricing.currencies.USD.payment_bank.standard structure. Just as with credit card fees, BPS represents percentage points, and the fixed amount is represented in cents.
A request to set Merchant IC+ pricing may look like this:
curl -X POST \
--url 'https://stage-api.wepay.com/accounts' \
-H 'Accept: application/json'\
-H 'App-Id: {your-app-id}'\
-H 'App-Token: {your-app-token}'\
-H 'Api-Version: 3.0'\
-H 'Content-Type: application/json' \
--data-raw '{
"legal_entity_id": "{insert-merchant's-LE-ID}",
"name": "Foo Bar campaign",
"statement_description": "Thanks for your Foo Bar campaign donation",
"pricing": {
"currencies": {
"USD": {
"credit_card": {
"type": "interchange_plus",
"interchange_plus": {
"transaction": {
"fixed_fee_markup_amount": 20,
"variable_fee_markup_bps": 295
},
"auth": {
"fixed_fee_markup_amount": 20
},
"refund_fee_for_transaction_markup": true
}
},
"payment_bank": {
"type": "standard",
"standard": {
"fixed_fee_amount": 10,
"variable_fee_bps": 195,
"max_fee_amount": 1000,
"min_fee_amount": 200,
"refund_fee_for_standard": true
}
},
"recurring_fee": {
"period": "monthly",
"amount": 1500
}
}
}
}
}'
Note
Across the WePay Clear APIs, values related to amounts are represented in the lowest denomination (cents). So to represent $2.00, use a value of 200.
Important:
If any errors are made in setting an Account’s pricing, they must be corrected using a POST /accounts/{id} request with the correct pricing parameters. Pricing only applies to future Payments; it does not apply retroactively.
Process Diagram
Consume Billing Statements
First, WePay will create a Billing Statement on the 5th of the month following each billing cycle (defined as a calendar month), and will send a Notification when it is ready. A Billing Statement will describe the amount in fees owed by the merchant by providing aggregate information about the merchant’s fees over the billing cycle. The aggregate information will be present in the payload block of the billing_statements.created Notification.
Note
Be sure to account for any Delayed Capture payments, especially if the authorization occurs at the end of one month and the capture occurs at the beginning of the next month. When this happens, fees for authorization and capture will be applied separately.
A Billing Statement Notification will look like this:
{
"id": "ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"resource": "notifications",
"path": "/notifications/ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"owner": {
"id": "121212",
"resource": "applications",
"path": null
},
"topic": "billing_statements.created",
"event_time": 1568922341,
"payload": {
"resource": "billing_statements",
"id": "c4a1abf1-34ac-40e8-bdba-5649f0665421",
"path": "/billing_statements/c4a1abf1-34ac-40e8-bdba-5649f0665421",
"owner": {
"resource": "accounts",
"id": "c4a1abf1-34ac-40e8-bdba-5649f0643043",
"path": "/accounts/c4a1abf1-34ac-40e8-bdba-5649f0643043"
},
"create_time": 1510080177,
"amount": 2300000,
"currency": "USD",
"month": 1,
"year": 2019,
"api_version": "3.0"
}
}
Amount describes the amount owed by the merchant to WePay for processing fees, and will match the amount in the Adjustment.
Next, fetch the billing statement fee summary and transaction summary by sending GET /billing_statements/{id}/fees_summary & GET /billing_statements/{id}/transactions_summary requests respectively. Use the response data in combination with the billing statement data to compile the billing statement for the merchant.
A GET /billing_statements/{id}/fees_summary response might look something like this:
{
"previous": "/billing_statements/{id}/fees_summary?page=aaabc123def456",
"next": "/billing_statements/{id}/fees_summary?page=cccde123fgh456",
"results": [
{
"fee_type": "VISA",
"fee_category": "VISA CORPORATE CARD - CARD NOT PRESENT",
"currency": "USD",
"total_amount": 202903,
"item_count": 4,
"variable_fee_bps": 265,
"total_fixed_fee_amount": 10,
"fixed_fee_markup_amount": 0,
"variable_fee_markup_bps": 15,
"total_interchange_fee": 5417,
"total_markup": 30435,
"total_fees": 35852,
"api_version": "3.0"
},
{
"fee_type": "ECHECK",
"fee_category": "eCheck fees",
"currency": "USD",
"total_amount": 20290,
"item_count": 6,
"variable_fee_bps": null,
"total_fixed_fee_amount": null,
"fixed_fee_markup_amount": 0,
"variable_fee_markup_bps": 15,
"total_markup": 5417,
"total_fees": 5417,
"total_interchange_fee": null,
"api_version": "3.0"
},
{
"fee_type": "CHARGEBACK",
"fee_category": "Chargeback fees",
"currency": "USD",
"total_amount": 20290,
"item_count": 4,
"variable_fee_bps": 0,
"total_fixed_fee_amount": 1500,
"fixed_fee_markup_amount": null,
"variable_fee_markup_bps": null,
"total_markup": null,
"total_fees": 6000,
"total_interchange_fee": null,
"api_version": "3.0"
},
{
"fee_type": "RECURRING FEES",
"fee_category": "Monthly",
"currency": "USD",
"total_amount": null,
"item_count": null,
"variable_fee_bps": null,
"total_fixed_fee_amount": null,
"fixed_fee_markup_amount": 2500,
"variable_fee_markup_bps": null,
"total_markup": 2500,
"total_fees": 2500,
"total_interchange_fee": null,
"api_version": "3.0"
},
{
"fee_type": "MASTERCARD",
"fee_category": "Auth Fees",
"currency": "USD",
"total_amount": null,
"item_count": 50,
"variable_fee_bps": null,
"total_fixed_fee_amount": null,
"fixed_fee_markup_amount": 30,
"variable_fee_markup_bps": null,
"total_markup": 1500,
"total_fees": 1500,
"total_interchange_fee": null,
"api_version": "3.0"
},
{
"fee_type": "ADJUSTMENT",
"fee_category": "Financial Adjustment",
"currency": "USD",
"month": 1,
"total_amount": 100,
"item_count": null,
"variable_fee_bps": null,
"total_fixed_fee_amount": null,
"fixed_fee_markup_amount": null,
"variable_fee_markup_bps": null,
"total_markup": null,
"total_fees": null,
"total_interchange_fee": null,
"api_version": "3.0"
}
],
"api_version": "3.0"
}
A Note On Adjustments
When an adjustment occurs, there will be two possibilities for the fee_category value:
- Financial Adjustment - This describes money movement (either credited to or debited from).
- Reporting Adjustment - This describes an error in money movement reporting (where the money movement itself was correct), and a subsequent Adjustment to correct reporting.
Reporting Adjustments are expected to be rare.
A GET /billing_statements/{id}/transactions_summary response might look something like this:
{
"previous": "/billing_statements/{id}/transactions_summary?page=aaabc123def456",
"next": "/billing_statements/{id}/transactions_summary?page=cccde123fgh456",
"results": [
{
"day": 1,
"month": 1,
"year": 2019,
"currency": "USD",
"total_amount": 672424,
"item_count": 100,
"summaries": [
{
"fee_type": "VISA",
"currency": "USD",
"total_amount": 652134,
"item_count": 69
},
{
"fee_type": "VISA",
"currency": "USD",
"total_amount": -3000,
"item_count": 10
},
{
"fee_type": "ECHECK",
"currency": "USD",
"total_amount": 18290,
"item_count": 22
},
{
"fee_type": "MASTERCARD",
"currency": "USD",
"total_amount": 2000,
"item_count": 9
},
{
"fee_type": "MASTERCARD",
"currency": "USD",
"total_amount": 3400,
"item_count": 3
}
],
"api_version": "3.0"
},
{
"day": 2,
"month": 1,
"year": 2019,
"currency": "USD",
"total_amount": 673928,
"item_count": 100,
"summaries": [
{
"fee_type": "CHARGEBACK",
"currency": "USD",
"total_amount": 652000,
"item_count": 69
},
{
"fee_type": "ECHECK",
"currency": "USD",
"total_amount": 18290,
"item_count": 22
},
{
"fee_type": "DISCOVER",
"currency": "USD",
"total_amount": 3638,
"item_count": 9
}
],
"api_version": "3.0"
}
],
"api_version": "3.0"
}
Once a Billing Statement is made available, your platform must compile a statement for merchants.
Compile the merchant’s statement using data from the Billing Statement, fees summary, and transactions summary. The statement must be compiled and sent to merchants within 24 hours of WePay sending the billing_statements.created Notification. When your platform sends the statement, include a notice that their Payout Method will be debited for the billing statement amount. When planning this process, provide merchants with sufficient time to review the statement you send them and reach out with any questions or concerns before WePay debits their Payout Method.
WePay will debit the merchant’s Payout Method 24 hours after the Billing Statement is available.
In WePay systems, the debit will be an API Recovery. The merchant will be able to view the debit as a single line item on their bank statement.
If the Recovery for fees fails, WePay will debit for fees from the merchant’s gross settlement the following day.
Process Diagram
Bill Merchants
To bill merchants, WePay will initiate a Recovery from the merchant’s active Payout Method for fees owed (the amount value in the Billing Statement). This will occur 24 hours after the Billing Statement was created (so the 6th of the month). If the recovery for fees fails, WePay will make an Adjustment to the merchant’s Account balance to collect the fees owed.
It is recommended to disclose this process to merchants before they begin processing, and again once each Billing Statement is made available.
Take note that these Recoveries and Adjustments fall outside of the merchant’s normal transactions which are included in Billing Statements and reconciliation.
First, listen for the recoveries.created Notification to identify Merchant IC+ Recoveries. These Notifications will look like this:
{
"id": "ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"resource": "notifications",
"path": "/notifications/ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"owner": {
"id": "121212",
"resource": "applications",
"path": null
},
"topic": "recoveries.created",
"event_time": 1568922341,
"payload": {
"id": "bb109170-f401-44b0-8a8b-7abfd27e9f30",
"resource": "recoveries",
"path": "/recoveries/bb109170-f401-44b0-8a8b-7abfd27e9f30",
"create_time": 1278889543,
"complete_time": 1278889965,
"status": "pending",
"amount": 100,
"currency": "USD",
"owner": {
"id": "c4a1abf1-34ac-40e8-bdba-5649f0643043",
"resource": "accounts",
"path": "/accounts/c4a1abf1-34ac-40e8-bdba-5649f0643043"
},
"reason": {
"reason_code": "FEES",
"reason_message": "Recovery for fees.",
"details": [{
"detail_code": "billing_statement_fees",
"detail_message": "Fees associated with a billing statement."
}]
},
"payout_method": {
"id": "0102b1c6-2bc7-448a-aa1d-076b1637547c",
"resource": "payout_methods",
"path": "/payout_methods/0102b1c6-2bc7-448a-aa1d-076b1637547c"
},
"pending_reasons": [{
"reason_code": "PROCESSING",
"reason_message": "Recovery is being processed",
"details": {
"detail_code": "processing",
"detail_message": "The recovery is currently under processing."
}
}]
}
}
Please note that there is no specific reason code to distinguish between a recovery debit vs. processing fees (i.e. Merchant IC+ monthly fees) debit.
To identify Merchant IC+ debits from the merchant’s Payout Method, match the amount value from the recoveries.created Notification to the amount value from the billing_statements.created Notification.
When a recoveries.created Notification is received, notify the merchant that a debit from their active Payout Method is currently being processed. Next, listen for either the recoveries.completed or the recoveries.failed Notifications, and advise the merchant of the outcome. Recoveries take 2-3 days to complete, which will typically be on the 8th of the month following the Billing Statement in question.
If a Recovery becomes completed, a receipt or confirmation of successfully paid processing fees should be provided to the merchant.
If a Recovery becomes failed, there will be a reason code explaining why. Notify the merchant that the recovery attempt failed, and that an Adjustment will be made to their Account balance to cover the fees.
After a recovery failure, listen for the adjustments.created Notification. These Notifications will look like this:
{
"id": "ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"resource": "notifications",
"path": "/notifications/ccdbd4f6-a409-42b8-abdb-3451ff40501e",
"owner": {
"id": "121212",
"resource": "applications",
"path": null
},
"topic": "adjustments.created",
"event_time": 1568922341,
"payload": {
"amount": 100,
"create_time": 1520471380,
"currency": "USD",
"custom_data": null,
"id": "9fed5d2f-3957-412c-9f30-efabcc2b5405",
"message": "Custom message from WePay",
"owner": {
"id": "c4a1abf1-34ac-40e8-bdba-5649f0643043",
"resource": "accounts",
"path": "/accounts/c4a1abf1-34ac-40e8-bdba-5649f0643043"
},
"path": "/adjustments/9fed5d2f-3957-412c-9f30-efabcc2b5405",
"reason": {
"reason_code": "FEES",
"reason_message": "Adjustment for fees.",
"details": [{
"detail_code": "billing_statement_fees",
"detail_message": "Fees associated with a billing statement."
}]
},
"resource": "adjustments",
"txnr_adjustment": {
"id": "80027dfa-39a2-4d6e-ac7a-024c61340bc2",
"resource": "transaction_records",
"path": "/transaction_records/80027dfa-39a2-4d6e-ac7a-024c61340bc2"
},
"type": "debit"
}
}
Specifically note the reason JSON block containing the details identifying the Adjustment as a payment for Merchant IC+ fees.
Once an Adjustment is completed, a receipt or confirmation of successfully paid processing fees should be provided to the merchant.
Process Diagram
Reconcile Data
Many merchants will want a line-by-line breakdown of their fees which can be fetched by sending GET /billing_statements/{id}/transactions_summary and GET /billing_statements/{id}/fees_summaryrequests.
The API response to GET /billing_statements/{id}/transactions_summary contains an array of Transaction Summaries and will look something like this:
{
"previous": "/billing_statements/{id}/transactions_summary?page=aaabc123def456",
"next": "/billing_statements/{id}/transactions_summary?page=cccde123fgh456",
"results": [{
"day": 1,
"month": 1,
"year": 2019,
"total_amount": 672424,
"currency": "USD",
"item_count": 100,
"summaries": [{
"fee_type": "VISA",
"currency": "USD",
"total_amount": 652134,
"item_count": 9
},
{
"fee_type": "ECHECK",
"currency": "USD",
"total_amount": 20290,
"item_count": 6
},
{...},
{...}
],
"api_version": "3.0"
},
{"day": 2, ...},
{"day": 3, ...}
}
Each summary provides details organized by day of the month, fee type, and fee category. Fee types include the different card networks (i.e. Visa, Mastercard, etc.), and the different API Resources (i.e. Disputes (notated as chargebacks), Adjustments, etc). Fee categories drill down further to differentiate fees, and this is where you’ll be able to identify recurring fees (set by your platform in the pricing API), and authorization fees (also set by your platform in the pricing API).
The GET /billing_statements/{id}/fees_summary response contains an array of Fees Summaries and will look something like this:
{
"previous": "/billing_statements/{id}/fees_summary?page=aaabc123def456",
"next": "/billing_statements/{id}/fees_summary?page=cccde123fgh456",
"results": [{
"fee_type": "VISA",
"fee_category": " VISA BUSINESS TIER 3 - STANDARD",
"currency": "USD",
"total_amount": 56594,
"item_count": 1,
"variable_fee_bps": 295,
"fixed_fee_amount": 20,
"variable_fee_markup_bps": 15,
"fixed_fee_markup_amount": 0,
"total_interchange_fee": 1690,
"total_markup": 8489,
"total_fees": 10179,
"api_version": "3.0"
}, {
"fee_type": "VISA",
"fee_category": "VISA BUSINESS TIER 4 - STANDARD",
"currency": "USD",
"total_amount": 652134,
"item_count": 9,
"variable_fee_bps": 295,
"fixed_fee_amount": 25,
"variable_fee_markup_bps": 15,
"fixed_fee_markup_amount": 0,
"total_interchange_fee": 19463,
"total_markup": 97820,
"total_fees": 117823,
"api_version": "3.0"
}, {
"fee_type": "VISA",
"fee_category": "Auth Fees",
"currency": "USD",
"total_amount": 202903,
"item_count": 4,
"variable_fee_bps": 265,
"fixed_fee_amount": 10,
"variable_fee_markup_bps": 15,
"fixed_fee_markup_amount": 0,
"total_interchange_fee": 5417,
"total_markup": 30435,
"total_fees": 35852,
"api_version": "3.0"
}, {
"fee_type": "ECHECK",
"fee_category": "ECHECK FEES",
"currency": "USD",
"total_amount": 20290,
"item_count": 6,
"variable_fee_bps": null,
"fixed_fee_amount": null,
"variable_fee_markup_bps": 15,
"fixed_fee_markup_amount": 0,
"total_interchange_fee": null,
"total_markup": 5417,
"total_fees": 5417,
"api_version": "3.0"
}, {
"fee_type": "CHARGEBACK",
"fee_category": "CHARGEBACK FEES",
"currency": "USD",
"total_amount": null,
"item_count": 4,
"variable_fee_bps": 0,
"fixed_fee_amount": 1500,
"variable_fee_markup_bps": null,
"fixed_fee_markup_amount": null,
"total_interchange_fee": null,
"total_markup": null,
"total_fees": 6000,
"api_version": "3.0"
}, {
"fee_type": "OTHER",
"fee_category": "MC ACQUIRING FEE",
"currency": "USD",
"total_amount": 8807781,
"item_count": 49,
"variable_fee_bps": 0.4,
"fixed_fee_amount": 0,
"variable_fee_markup_bps": null,
"fixed_fee_markup_amount": null,
"total_interchange_fee": 352,
"total_markup": null,
"total_fees": 352,
"api_version": "3.0"
}, {
"fee_type": "RECURRING FEES",
"fee_category": "Monthly",
"currency":"USD",
"total_amount": null,
"item_count": null,
"variable_fee_bps": null,
"fixed_fee_amount": null,
"fixed_fee_markup_amount":2500,
"variable_fee_markup_bps":null,
"total_markup": 2500,
"total_fees": 2500,
"total_interchange_fee": null,
"api_version": "3.0"
},
{...}
],
"api_version": "3.0"
}
The Transaction Summaries and Fees Summaries can be used in conjunction with reporting to provide holistic reconciliation for merchants.
Additionally, you can get a list of specific transactions (Payments, Adjustments, Recoveries, Disputes, etc.) included in the merchant’s processing for a given billing cycle. To do so, send a GET request for each resource with the start_time parameter matching the beginning of the billing cycle:
curl -X GET -G \
--url 'https://stage-api.wepay.com/adjustments?create_time_start=1546329600'
-H 'Accept: application/json'\
-H 'App-Id: {your_app_id}'\
-H 'App-Token: {your_app_token}'\
-H 'Api-Version: 3.0' \
The create_time_start will be the unix timestamp for the 1st of a given month at 0:00:00 UTC.
Process Diagram
Test Merchant IC+
For testing Merchant IC+, we’ve created the following magic header values for the WePay-Magic-Behavior header key:
| Endpoint | Header Value |
|---|---|
| GET /billing_statements/{id} | get_billing_statements_id |
| GET /billing_statements?account_id={account_id} | get_billing_statements |
| GET /billing_statements/{id}/transactions_summary | get_billing_statements_id_transactions_summary |
| GET /billing_statements/{id}/fees_summary | get_billing_statements_id_fees_summary |
Find more information in the testing article.
Migrate Merchants To Blended Pricing
If a merchant is currently on Merchant IC+ pricing but is moving back to standard blended rate pricing, the following parameters must be set to null:
pricing.currencies.USD.credit_cardpricing.currencies.USD.payment_bankpricing.currencies.USD.recurring_fee
Questions? Need help? Visit our support page!