Usage
The SDK Object
Use FellohSDK(containerID, publicKey, options?) to create an instance of the Felloh object. The Felloh object is your entrypoint to the rest of the Felloh SDK.
Your Felloh public API key is required when calling this function, as it identifies your website or application to Felloh.
We've prefilled the example with a sample test API key. Don’t submit any personally identifiable information in requests made with this key. To create a Felloh object using your account, replace the sample API key with your actual API key or sign in.
Setup the Payment iFrame
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-html" style="white-space:pre;color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span class="token" style="color:#808080"><</span><span class="token" style="color:#569cd6">div</span><span class="token" style="color:#569cd6"> </span><span class="token" style="color:#9cdcfe">id</span><span class="token" style="color:#d4d4d4">=</span><span class="token" style="color:#ce9178">"</span><span class="token" style="color:#ce9178">payment-iframe</span><span class="token" style="color:#ce9178">"</span><span class="token" style="color:#808080">></span><span class="token" style="color:#808080"></</span><span class="token" style="color:#569cd6">div</span><span class="token" style="color:#808080">></span><span> </span><span></span><span class="token" style="color:#808080"><</span><span class="token" style="color:#569cd6">script</span><span class="token" style="color:#569cd6"> </span><span class="token" style="color:#9cdcfe">type</span><span class="token" style="color:#d4d4d4">=</span><span class="token" style="color:#ce9178">"</span><span class="token" style="color:#ce9178">text/javascript</span><span class="token" style="color:#ce9178">"</span><span class="token" style="color:#808080">></span><span class="token script language-javascript"> </span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#569CD6">var</span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#9cdcfe">SDK</span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#d4d4d4">=</span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#569CD6">new</span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#4ec9b0">FellohPayments</span><span class="token script language-javascript" style="color:#d4d4d4">(</span><span class="token script language-javascript" style="color:#ce9178">'payment-iframe'</span><span class="token script language-javascript" style="color:#d4d4d4">,</span><span class="token script language-javascript"> </span><span class="token script language-javascript" style="color:#ce9178">'your-public-key'</span><span class="token script language-javascript" style="color:#d4d4d4">)</span><span class="token script language-javascript" style="color:#d4d4d4">;</span><span class="token script language-javascript"> </span><span class="token script language-javascript"></span><span class="token" style="color:#808080"></</span><span class="token" style="color:#569cd6">script</span><span class="token" style="color:#808080">></span><span> </span></code></pre></div>
When you’re ready to accept live payments, replace the test key with your live key in production. Learn more about how API keys work in test mode and live mode.
Method parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| containerID | true | string | The dom element ID where the payment element will be rendered. |
| publicKey | true | string | Your public key, this can be created using the felloh dashboard. |
| options.sandbox | false | boolean | Whether to use sandbox instead of production |
Rendering the Element
Once you have generated an ecommerce entity on your backend and passed this to your frontend, you can render the element using the ID.
The form will consume 100% of the width given to it, it is recommended that it has a minimum of 350px to grow into. The element wil also grow and shrink in height depending on what is being displayed, it is recommended that no restrictions are placed on the height it can grow to.
Required Parameters
- Name
ecommerceID- Type
- string
- Description
The ecommerce ID of the payment, generated via the felloh API
The Render Method
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span> </span><span class="token" style="color:#6a9955">// Ecommerce ID should be passed from your backend</span><span> </span><span> </span><span class="token" style="color:#569CD6">const</span><span> ecommerceID </span><span class="token" style="color:#d4d4d4">=</span><span> </span><span class="token" style="color:#ce9178">'Unique ecommerce ID'</span><span class="token" style="color:#d4d4d4">;</span><span> </span> <span> </span><span class="token" style="color:#6a9955">// Render the payment using the SDK</span><span> </span><span> fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">render</span><span class="token" style="color:#d4d4d4">(</span><span>ecommerceID</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>
Initalising an Ecommerce Payment
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span class="token" style="color:#c586c0">import</span><span> </span><span class="token" style="color:#9cdcfe">SDK</span><span> </span><span class="token" style="color:#c586c0">from</span><span> </span><span class="token" style="color:#ce9178">'@felloh-org/payment-sdk'</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span></span><span class="token" style="color:#c586c0">import</span><span> </span><span class="token" style="color:#9cdcfe">Axios</span><span> </span><span class="token" style="color:#c586c0">from</span><span> </span><span class="token" style="color:#ce9178">'axios'</span><span class="token" style="color:#d4d4d4">;</span><span> </span> <span></span><span class="token" style="color:#569CD6">const</span><span> </span><span class="token function-variable" style="color:#c0a9e5">renderPaymentForm</span><span> </span><span class="token" style="color:#d4d4d4">=</span><span> </span><span class="token" style="color:#569CD6">async</span><span> </span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span class="token" style="color:#569CD6">=></span><span> </span><span class="token" style="color:#d4d4d4">{</span><span> </span><span> </span><span class="token" style="color:#6a9955">// Instantiate the SDK</span><span> </span><span> </span><span class="token" style="color:#569CD6">const</span><span> fellohSDK </span><span class="token" style="color:#d4d4d4">=</span><span> </span><span class="token" style="color:#569CD6">new</span><span> </span><span class="token" style="color:#4ec9b0">SDK</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'payment-iframe'</span><span class="token" style="color:#d4d4d4">,</span><span> </span><span class="token" style="color:#ce9178">'your-public-key'</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span> <span> </span><span class="token" style="color:#6a9955">// Make a call to your backend and generate the ecommerce ID</span><span> </span><span> </span><span class="token" style="color:#569CD6">const</span><span> response </span><span class="token" style="color:#d4d4d4">=</span><span> </span><span class="token" style="color:#c586c0">await</span><span> axios</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">post</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'https://your.api'</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span> <span> </span><span class="token" style="color:#6a9955">// Render the payment form with the generated iD</span><span> </span><span> fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">render</span><span class="token" style="color:#d4d4d4">(</span><span>response</span><span class="token" style="color:#d4d4d4">.</span><span class="token property-access">data</span><span class="token" style="color:#d4d4d4">.</span><span class="token property-access">data</span><span class="token" style="color:#d4d4d4">.</span><span class="token property-access">id</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span></span><span class="token" style="color:#d4d4d4">}</span><span> </span> <span></span><span class="token" style="color:#c0a9e5">renderPaymentForm</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>
The onRender Event
This event triggers when the payment form has rendered
Method parameters
- Name
function- Type
- Description
A function to be undertaken when the event occurs
Using the onRender event
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span> fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">onRender</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span class="token" style="color:#569CD6">=></span><span> </span><span class="token" style="color:#d4d4d4">{</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'the form has rendered'</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span> </span><span class="token" style="color:#d4d4d4">}</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>
The Success Event
This event triggers when the transaction has successfully been undertaken
Method parameters
- Name
function- Type
- Description
A function to be undertaken when the event occurs
Function parameters
- Name
transaction.id- Type
- string
- Description
The ID of the transaction that has succedded
Using the onSuccess event
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span>fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">onSuccess</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#9cdcfe">data</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span class="token" style="color:#569CD6">=></span><span> </span><span class="token" style="color:#d4d4d4">{</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'the payment has succeded'</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'transaction id:'</span><span class="token" style="color:#d4d4d4">,</span><span> data</span><span class="token" style="color:#d4d4d4">?.</span><span>transaction</span><span class="token" style="color:#d4d4d4">?.</span><span>id</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span></span><span class="token" style="color:#d4d4d4">}</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>
The Decline Event
This event triggers when the transaction has successfully been undertaken
Method parameters
- Name
function- Type
- Description
A function to be undertaken when the event occurs
Function parameters
- Name
transaction.id- Type
- string
- Description
The ID of the transaction that has declined
Using the decline event
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span> fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">onDecline</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#9cdcfe">data</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span class="token" style="color:#569CD6">=></span><span> </span><span class="token" style="color:#d4d4d4">{</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'the payment has been declined'</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'transaction id:'</span><span class="token" style="color:#d4d4d4">,</span><span> data</span><span class="token" style="color:#d4d4d4">?.</span><span>transaction</span><span class="token" style="color:#d4d4d4">?.</span><span>id</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span> </span><span class="token" style="color:#d4d4d4">}</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>
The Processing Event
This event triggers when the transaction is processing
Method parameters
- Name
function- Type
- Description
A function to be undertaken when the event occurs
Function parameters
- Name
transaction.id- Type
- string
- Description
The ID of the transaction that is currently processing
Using the onProcessing event
<div class="syntax-highlighter"><pre style="color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none;padding:1em;margin:.5em 0;overflow:auto;background:#1b0f27"><code class="language-javascript" style="white-space:pre;color:#9cdcfe;font-size:13px;text-shadow:none;font-family:Menlo, Monaco, Consolas, "Andale Mono", "Ubuntu Mono", "Courier New", monospace;direction:ltr;text-align:left;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none"><span> fellohSDK</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">onProcessing</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#9cdcfe">data</span><span class="token" style="color:#d4d4d4">)</span><span> </span><span class="token" style="color:#569CD6">=></span><span> </span><span class="token" style="color:#d4d4d4">{</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'the payment is processing'</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span> </span><span class="token" style="color:#4ec9b0">console</span><span class="token" style="color:#d4d4d4">.</span><span class="token method property-access" style="color:#c0a9e5">log</span><span class="token" style="color:#d4d4d4">(</span><span class="token" style="color:#ce9178">'transaction id:'</span><span class="token" style="color:#d4d4d4">,</span><span> data</span><span class="token" style="color:#d4d4d4">?.</span><span>transaction</span><span class="token" style="color:#d4d4d4">?.</span><span>id</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span><span> </span><span class="token" style="color:#d4d4d4">}</span><span class="token" style="color:#d4d4d4">)</span><span class="token" style="color:#d4d4d4">;</span><span> </span></code></pre></div>