7
Getting Started
ForumPay offers several integration options to meet the needs of any merchant. This document provides a high-level overview of the different options available. This guide is meant to serve as a starting point for understanding the integration options available and any key concepts to be considered during the integration. More in-depth information can be found in our API documentation.
Integration Options
Shopping Cart
For merchants utilizing one of the shopping carts below, ForumPay has plugins available:
- WooCommerce
- Magento
- Drupal
While you can find more information and downloads for the plugins on our GitHub, we do recommend installing the plugins directly from your shopping cart.
Once installed you will need to add your API Key and Secret in order to use the plugin. You can generate these API credentials via your Merchant Dashboard and can find more detailed instructions for this at https://support.forumpay.com/kb/article/10-creating-api-keys/.
Payment Widget
For payments with a set, static amount, our Payment Widget is a great option. This allows you to set all the parameters for a payment, including amount, and get a link to the ForumPay Payment Widget which can be embedded in any page via an iFrame.
ForumPay’s Payment Widget is all that is needed to complete a payment. Everything is completed from within the widget and nothing else is needed. The widget is optimized to maximize conversions and localized into several languages.
Payment Links
Payment links are a great way to generate a link which you can then send via chat or email. The link will take the recipient directly to a ForumPay hosted payment page where they can complete their payment.
This is an ideal solution for invoicing or sending payment requests to customers, vendors, contractors or anyone with a payment due.
API Integration
Integrating with ForumPay via API is the most robust integration option. When using our API you have the ability to fully customize the payment UI/UX and embed it into you current payment flow however you wish.
While using the API is the most complex integration, it does give you the most optionality and control over the acceptance of crypto payments. If you are interested in the features available via but do not wish to create your own payment UI/UX, API integration still offers the option to iFrame our Payment Widget.
API Keys/Credentials
You can create your API Keys/Credentials via the Developers Tools section of your merchant dashboard.
Your API Keys/Credentials consists of an API User and an API Secret. The API User and first half of the API Secret will be displayed in your Merchant Dashboard. The second half of the API Secret will be emailed to you and never show up in the Merchant Dashboard. Please be sure to secure this.
Your full API secret is the combination of both halves with no spaces or characters in between. You can read our Knowledge Base Article for more detailed instructions on creating API Keys.
Building Your Own UI/UX
If you are planning on building your own UI/UX for accepting crypto payments, you will want to call the GetRate endpoint first to show your customer the exchange rate and amount of crypto for their payment.
After GetRate you will call StartPayment with the PaymentID that was returned to you in the GetRate call. The StartPayment response will give you all the information and data points you need to then build out your own UI/UX.
Embedding ForumPay’s Payment Widget
Ideal for merchants needed dynamic payment amounts but not wanting to build out their own UI/UX. Calling the CreatePaymentLink endpoint will return a link to our Payment Widget. Simply iFrame the link in your existing payment flow and you are all set.
Webhooks
Webhooks are how ForumPay communicates any changes of payment states to your integration. Every time there is a change in the state of a payment, a webhook will be sent to the URL configured in your Merchant Dashboard.
Webhooks do not contain any information regarding the payment itself. Rather they are notifications that something has changed. Upon receiving a webhook, your integration should call CheckPayment to get all the relevant information regarding the payment.
Payment States
|
State |
Description |
|
Waiting |
Payment initiated, still open, but no payment sent by consumer |
|
Processing |
Payment on the blockchain and awaiting blockchain confirmation |
|
Underpayment |
Underpayment sent, payment still open and can be completed |
|
Cancelled* |
No payment sent or payment sent but not yet accepted by merchant (late or under) |
|
Zero_Confirmed |
Payment zero confirmed by ForumPay, settlement guaranteed |
|
Confirmed* |
Payment confirmed on the blockchain, settlement guaranteed |
|
Blocked* |
Payment blocked as a result of Chainalysis result |
* Possible final states, all others are temporary.
Payment Errors
Payment errors happen when customers:
- Send less crypto than was required to complete the payment (Underpayment)
- Send more crypto than was required to complete the payment (Overpayment)
- Send their crypto after the payment has timed out, 15 minutes (Late Payment)
Default Behavior for Payment Errors
- Underpayments will be cancelled. As a result, these payments will need to be either refunded or accepted for the lower amount.
- Late payments will also be cancelled. As a result, these payments will need to be refunded or accepted for the amount the payment is worth at the time of acceptance (this could be more or less, depending on the exchange rate at the time).
- Overpayments will be confirmed for the amount expected and the overage will then need to be refunded or accepted.
Automated Handling of Payment Errors
To ease the burden of handling payment errors, ForumPay has automation options that eliminate the need for any manual intervention.
Within the Account Settings of your Merchant Dashboard you can set thresholds/parameters for the auto acceptance of any payment errors.
These settings will automatically be applied to any payment error and the payment will be handled accordingly.
Additionally, if you pass in your customer’s email address when initiating payment (using any method available), we will email the customer with a link to self-service their refund in the even one is needed.
You can also set thresholds/parameters for auto acceptance when you initiate a payment via the API. If you do so, these settings will override the default settings at the account level.
Refunds
Within the ForumPay ecosystem, a “refund” specifically refers to returning cryptocurrency to a customer when the original payment has not yet been converted to fiat, typically when a payment error has occurred. As this payment has been confirmed, a refund is not available for it.
Traditional refunds, as commonly understood in card payments, are not directly available once a transaction has been converted to fiat and settled because the original crypto funds are no longer held.
For merchants integrating via the API, you can determine whether a crypto refund is still possible by using the CheckPayment call. If the refund_amount_opened parameter returns a value greater than zero, a refund can still be processed for that transaction.
However, merchants can achieve a similar outcome by using Buy Orders to convert available fiat balances back into cryptocurrency and sending those funds to the customer. This provides a practical way to issue a cryptocurrency refund when your business determines one is appropriate.
Account Users
You can add additional users to your ForumPay account and give them only the permissions (see Appendix A for a complete list) they need to perform their job function. In your Account Settings you can add as many users as needed.
Once added, the new user will receive an email to accept the invitation. Once accepted, they can create their account and will only have access to the items you granted them permission to.
Test/Sandbox Environment
ForumPay has a Test/Sandbox environment that functions identically to our live environment. You can easily access the Test/Sandbox environment via the toggle in the top right corner of your Merchant Dashboard.
This is where you will work on, test and complete your integration. Once ready to go live, all that is required is to change the endpoints and API Keys/Credentials to our live environment.
Please note that API Keys/Credentials created in Test will not work in live and vice versa.
The Test Environment features a fully functional simulated crypto wallet for sending and receiving payments. You can open your wallet at any time by clicking the wallet icon in the lower left corner of your Merchant Dashboard
