Ari10 Payment Gateway Api Documentation

## Sections
• [Welcome to Ari10 Payment Docs](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/welcome-to-ari10-payment-docs.md): Here is all you need to know before and during implementation of Ari10 Payment Gateway into your solution. About Ari10 Payment Gateway 💪 Ari10 Gateway is a white-label solution that enables B2B entities to sell cryptocurrencies and Web3 goods directly on their website. To empower non-crypto and crypto-projects that undergo tokenization with new business opportunities, while simplifying the access path for their customers. Get ready! There are billions of people online who are waiting for you. Earn more. Seamlessly! Seamless Integration ✅ Our "widget" is not only easy to integrate but also to customize. Tailored set of features to meet your needs: your brand + our technology stack. With modular integration and our dedicated tech support, you won’t have to wait long to make it work. Only a few weeks and your website is ready to earn. Built-in compliance 🔐 With our dedicated gateway, you do not have to worry about compliance with KYC/AML standards. We handle it for you. So you can focus on your core business. A user-friendly experience / solution that reduces risk rather than blocking your visitors. Why this documentation? 📄 The following documentation describe step by step on how to set an integration of your solution to use Ari10 Payment Gateway capabilities
• [Getting Started](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/getting-started.md): For a quick and easy installation please get yourself familiar with the following steps necessary to get you up and running. Implementation requirements: ✔ Solution will not work properly in an iframe window Setup of your account in the Ari10 Panel which result with information containing: API_KEY (WidgetID) SIGNATURE_SECRET (separate set for Test and Production environments) Setup of proper callback / webhook URLs in Ari10 Panel: START transaction webhook URL CANCEL transaction webhook URL PAID / FINISHED transaction webhook (all of the callback / webhook URL's needs to be rovided by partner / merchant; all of them can be pointing towards same URL) Setup of a BSC network wallet in Ari10 Panel: BSC network wallet (required only for the production environment) For other blockchains please contact us to agree on details Integration steps: 🪜 Generate an Ari10 transactionId Display Ari10 Gateway Widget on your page with the use of previously generated Ari10 transactionId Listening for a callback / webhook for a confirmation of a successful transaction Please continue following the documentation to correctly go through all of those steps.
• [Getting Ari10 transactionId](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/getting-ari10-transactionid.md): This API endpoint allows you to start a transaction for payments. This endpoint is used to start the transaction process and does not include method names such as GET or POST.
  • [Calculating signature required for obtaining Ari10 transactionId](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/getting-ari10-transactionid/calculating-signature-required-for-obtaining-ari10-transactionid.md): The following examples describes how to generate a signature necessary in starting transaction process. Why do we need signatures? 🔒 In the realm of RESTful API communication, the essence of a calculated signature goes beyond simple data transmission. Its importance can be delineated into three core tenets: Authentication and Authorization : A calculated signature offers a precise method for the server to confirm the identity of the requester. By examining the signature, a server can ascertain that the request has originated from a legitimate source and possesses the requisite permissions for a specific operation. Data Integrity : During the journey of data packets across the digital labyrinth of networks, they are susceptible to external alterations. A calculated signature acts as a seal, ensuring that the payload received matches the original sent payload. Any discrepancies in the data, whether inadvertent or malicious, can thus be rapidly detected and acted upon. Prevention against Eavesdropping and Tampering : In the open playground of the internet, APIs are vulnerable to multiple security threats like man-in-the-middle attacks. Malicious actors can intercept, alter, or reroute data. A calculated signature provides an added layer of defense, making it considerably challenging for these actors to tamper with the message without detection. In essence, the use of calculated signatures in RESTful API communication is akin to having a personalized, tamper-evident seal on a confidential envelope, ensuring the content remains unaltered and is only accessed by the intended recipient. Calculating signature for Ari10 transactionId request 🔐 To generate correct signature, one needs to create a string that contains of the following elements connected together: transaction amount multiplied by 100 (transaction_amount*100, no decimals) transaction currency return url For example with given data: transaction amount = 39.99 transaction currency = ‘PLN’ return url = ' https://127.0.0.1 ' The resulting string before signing: '3999PLNhttps://127.0.0.1' During implementation, the following online tool can be helpful to check if the signature is calculated correctly: https://www.devglan.com/online-tools/hmac-sha256-online Please find the following sample PHP code showing the process: Select... function calculateNoDecimalsAmount(float $transaction_amount) { return $transaction_amount * 100; } function constructSignatureStr(float $transaction_amount, string $transaction_currency, string $return_url) { $no_decimals_amount = calculateNoDecimalsAmount($transaction_amount); return $no_decimals_amount . $transaction_currency . $return_url; } function calculateTransactionSignature(string $signature_string, string $widget_secret) { return hash_hmac('sha256', $signature_string, $widget_secret); } $transaction_amount = 39.99; $transaction_currency = 'PLN'; $return_url = 'https://127.0.0.1'; $widget_secret = '1234567890abcdef1234567890abcdef'; $signature_string = constructSignatureStr($transaction_amount, $transaction_currency, $return_url); $signature = calculateTransactionSignature($signature_string, $widget_secret);
  • [Example of a proper Ari10 Transaction ID callout](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/getting-ari10-transactionid/example-of-a-proper-ari10-transaction-id-callout.md): Please use the following example values to check if your implementation of signature calculation and Ari10 Transaction ID callout are correct: Ari10WidgetId='12345678-abcd-1234-abcd-0123456789ab' widgetBaseUrl=' https://127.0.0.1 ' offeredCurrencyCode='PLN' offeredAmount=39.99 signature=f705102095d7f285929672085ab869ac74799510274a51a09fac8a0a8bc2688f Using the above data wont generate a proper transaction as it is only a sample code, but it shows a proper signature calculate for a given set of parameters
  • [Passing custom parameters](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/getting-ari10-transactionid/passing-custom-parameters.md): For partners that would like to pass custom parameters through Ari10 Gateway system and get them back via webhooks, we prepared set of functionalities that can be used. During generation of Ari10 transactionID an additional field named partnerMetadata can be used. The data provided via this field IS NOT included during signature calculation while generating transactionID. partnerMetadata field is an array and is designated to contain 3 fields (from which all are optional). First 2 fields: partnerTransactionId and partnerClientType have fixed names while within 3rd field named partnerParams a partner may decide to pass an array with any set of fields and values. Please find the following json as an example: Select... 'partnerMetadata': { //optional 'partnerTransactionId': 'sample string', //optional, field name is fixed 'partnerClientType': 'sample string', //optional, field name is fixed ‘partnerParams': { //optional ‘firstCustomParameterName': 'sample string', //optional, field name and value can be set by partner 'secondCustomParameterName': 'sample string', //optional, field name and value can be set by partner 'anyDefinedParameterName': 'sample string' //optional, field name and value can be set by partner } } Example request values and a proper transactionID callout: Ari10WidgetId='12345678-abcd-1234-abcd-0123456789ab' widgetBaseUrl=' https://127.0.0.1 ' offeredCurrencyCode='PLN' offeredAmount=39.99 signature='f705102095d7f285929672085ab869ac74799510274a51a09fac8a0a8bc2688f' partnerTransactionId='98765432-defa-1098-fedc-9876543210ba' partnerClientType='vip-client' additional custom field: clientID='1234567890abcdef' additional custom field: clientAdditionalInfo='some additional info'
• [Payment Methods](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/payment-methods.md): Depending on your agreement, multiple payment methods can be used. Out of all of them mostly used are: Blik fast payment method 💸 Credit Card Payments 💳 Apple Pay / Google Pay 📲 Blik payment method is specific for Poland and people having account in Polish banks using PLN as currency. To be able to enable it, one needs to select PLN as a currency while generating Ari10 transactionId. Using any other currency wont enable Blik as a payment. Transaction Limits For the payment methods supported by Ari10 Gateway, the following minimum limits should be set: PLN: 100 EUR: 25 USD: 25
• [Rendering the Ari10 Gateway](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/rendering-the-ari10-gateway.md): After you correctly obtained an Ari10 transactionId, the next step is to display a Ari10 Gateway. The widget will not work in an Iframe, please use a separate page where you render the widget. For a proper way to display a widget, please use the following code samples. Sandbox html code sample: Select... <!DOCTYPE html> <html lang="pl"> <head> <title>Ari10 Payment</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <script> widget_simple_view_9501036516336 = 'true'; //true, false, optional widget_no_logo_8075047110440 = 'true'; //true, false, optional widget_id_6851681344231 = "12345678-abcd-1234-abcd-0123456789ab" //Ari10 API_KEY/WidgetID widget_language_1776290735652 = "pl" //language, pl OR en window.addEventListener('ari10-transaction-window-loaded-event', (event) => { window.dispatchEvent( new CustomEvent('ari10-widget-start-commodities-payment-request', { detail: { transactionId: '98765432-dcba-7890-dcba-9876543210fe', //Ari 10 transactionI mailAddress: 'username@domain.com', //optional phoneNumber: '48123456789' //optional (E.164 phone format) } }) ); }); </script> <script src="https://gateway-dev.ari10.com/widget/main-tst.min.js"></script> </head> <body> </body> </html> Production html code sample: Select... <!DOCTYPE html> <html lang="pl"> <head> <title>Ari10 Payment</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <script> widget_simple_view_9501036516336 = 'false'; //true, false, optional widget_no_logo_8075047110440 = 'false'; //true, false, optional widget_id_6851681344231 = "12345678-abcd-1234-abcd-0123456789ab" //Ari10 API_KEY/WidgetID widget_language_1776290735652 = "pl" //language, pl OR en window.addEventListener('ari10-transaction-window-loaded-event', (event) => { window.dispatchEvent( new CustomEvent('ari10-widget-start-commodities-payment-request', { detail: { transactionId: '98765432-dcba-7890-dcba-9876543210fe', //Ari10 transactionId mailAddress: 'username@domain.com', //optional phoneNumber: '48123456789' //optional (E.164 phone format) } }) ); }); </script> <script src="https://gateway.ari10.com/widget/main.min.js"></script> </head> <body> </body> </html> Make sure you are loading a proper script from a proper URL depending on the enviroment: For Sandbox / Test: https://gateway-dev.ari10.com/widget/main-tst.min.js For Production: https://gateway.ari10.com/widget/main.min.js Tips & Tricks Providing an email and a phone number increases conversion rate Provided JavaScript code waits for the script to be correctly loaded and initialized and only after renders the Payment Widget Please display the Payment Widget on a separate page and make sure that correct viewport meta tag is set (as showed in the example) so it can scale correctly both on desktop and mobile web browser
  • [Chosing layout](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/rendering-the-ari10-gateway/chosing-layout.md): The Ari10 Payment Gateway presents two distinct transaction pathways. The standard, sequential transaction flow unfolds in stages: initially, users input their email and phone number (which might be automatically populated if predetermined data is supplied). They'll then confirm with an SMS. In the following stage, users agree to the terms and select a payment approach. Some payment options might introduce a third phase focused on KYC verification. For those favoring a more streamlined experience, we offer a simple transaction flow. Here, users fill in all necessary details on one screen, with an additional step introduced only if KYC is mandated by the selected payment method. Standard transaction flow The flow consist of the following steps: Gateway welcome screen Email / phone / SMS code input (visualised below as 2 separate screens, but being part of one step) Transaction confirmation To use that flow, please make sure that in the code used for rendering Ari10 Payment Gateway the following parameter is set to false or are omitted: Select... widget_simple_view_9501036516336 = 'false'; Simple transaction flow The flow consist of the following steps: Email / phone / SMS code input (visualised below as 2 separate screens, but being part of one step) To use that flow, please make sure that in the code used for rendering Ari10 Payment Gateway the following parameter is present and set to true: Select... widget_simple_view_9501036516336 = 'true';
  • [Disabling Ari10 Logo](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/rendering-the-ari10-gateway/disabling-ari10-logo.md): The Ari10 Payment Gateway allows to hide the Ari10 logo from the transaction process. The below screenshots shows one of the transaction steps with and without the logo: For a standard version (which consists the Ari10 logo), please make sure that in the code used for rendering Ari10 Payment Gateway the following parameter is set to false or are omitted: Select... widget_no_logo_8075047110440 = 'false'; If you wish ti disable the Ari10 logo, please set the following parameter during the Rendering the Ari10 Gateway step: Select... widget_no_logo_8075047110440 = 'true';
  • [Custom events to use](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/rendering-the-ari10-gateway/custom-events-to-use.md): When dealing with integrations that aren't feasible on standalone pages (described in previous section), the subsequent event descriptions and their associated code snippets offer a structured roadmap to assist you. Select... Event name: ari10-transaction-window-loaded-event Example listener: window.addEventListener('ari10-transaction-window-loaded-event', (event) => { window.dispatchEvent( new CustomEvent('ari10-widget-start-commodities-payment-request', { detail: { transactionId: 'transactionId as UUID', mailAddress: 'some@mail.address or undefined', phoneNumber: 'some phone number or undefined' }; }) ); }); The above JavaScript event is called and executed when Ari10 Gateway script is fully loaded and transaction popup can be displayed. In other words it will display the popup as soon as it is ready. For an implementation when the widget should be displayed as a consequence of some other JavaScript interactions, a simple function wrapper and function callout can be used: Select... function showWidget() { window.dispatchEvent( new CustomEvent('ari10-widget-start-commodities-payment-request', { detail: { transactionId: 'transactionId as UUID', //transaction ID mailAddress: 'some@mail.address or undefined', phoneNumber: 'some phone number or undefined' } }) ); } In the abowe case calling showWidget() function will display the widget. This method should be only used when user should not see the Ari10 Gateway widget as soon as the page opens.
  • [When user closes popup](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/rendering-the-ari10-gateway/when-user-closes-popup.md): When integrating the Ari10 Gateway alongside other content on a webpage (pop-up window), be aware that users might inadvertently click outside of the transaction area. If they do so, they'll receive a prompt asking if they wish to exit the transaction process. A "yes" response will close this prompt. To effectively utilize this user action, you may want to either redirect them to another page or implement specific browser reactions. To capture and act upon this specific event, refer to the JavaScript code provided below. Select... Event name: ari10-widget-transaction-canceled-event Event payload: { transactionId: "anId" } Example listener: window.addEventListener( 'ari10-widget-transaction-canceled-event', (event) => { console.log('Received transaction canceled event: ', JSON.stringify(event.detail)) } );
• [Webhooks / Callbacks](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/webhooks-callbacks.md): Ari10 employs webhooks, also known as callback URLs, to provide instantaneous updates on transaction statuses. Here's how it works: Webhook URLs Configuration. Partners typically offer three distinct URLs: Start Transaction Webhook URL Finish transaction webhook URL Cancel transaction webhook URL Alternatively, partners can choose to provide a single URL that will be triggered for all transaction stages. Transaction Statuses Sent Through Webhooks “ STARTED ” - Sent when the Ari10 Gateway gets rendered (is shown) in a web browser window. “ PAID ” - Status is activated once a user completes a payment and, akin to the FINISHED status, both are relayed to the "Finish transaction webhook URL." “ FINISHED ” - Indicates that all technical operations, encompassing blockchain tasks, are finalized. “ CANCELLED ” - Sent if a user decides to cancel a payment or if no activity is detected for 60 minutes since the transaction's initiation. Every webhook call will be retried until we get a 200 status code response from the provided webhook URL. There will be a total of 5 attempts to reach the destination webhook, with a 30-second pause between each retry. Upon reaching the threshold of 10 attempts or receiving a 200 status code response, there exists no technical capability to further retry the webhook call. Recommendation for Merchants For timely responses, such as account top-ups, merchants should primarily focus on the “ PAID ” status. The “ FINISHED ” status is vital for those relying on blockchain processes to conclude. However, due to potential blockchain delays, this status might be relayed up to 24 hours post the “ PAID ” status update. In summary, while all transaction statuses are important, the “ PAID ” status is crucial for immediate actions. Ensure that the operational dynamics of blockchain are considered when waiting for the “ FINISHED ” status. Examples of payloads: Calculating signature For accurate signature computation: Assemble a string incorporating all response elements in their original sequence except those included in “partnerMetadata.partnerParams.” field which is ignored for the calculation (for detailed signature calculation when partnerMetadata field is used, please refer to next section of this documentation). If a a JSON field of the response is numeric (e.g. 21.34570767): Round down value to second decimal place. (e.g. 21.34). Multiply the adjusted number by 100, ensuring the outcome value is integer. (e.g. 2134). If a JSON field is null, omit it and don't use in calculations (e.g. when mailAddress field is null) Encode the finalized string using the sha256 method, combined with the signature provided by the Ari10 team. Examples: Plain text $widget_secret = “1234567890abcdef1234567890abcdef” Example String and resulting signature for STARTED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feSTARTEDPLN9999https://127.0.0.1 Signature: 6999f05d9203f5ea36c3d22658b83ff2e99bd79572d9c8d796b0b0610aba756f Example String and resulting signature for PAID payload provided above: String: 98765432-dcba-7890-dcba-9876543210fePAIDPLN9999https://127.0.0.1john.doe@domain.com Signature: 4943f317b38ce3e96f8caa5088089995a0560d1ee007c216ddbd418612ca27e5 Example String and resulting signature for FINISHED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feFINISHEDPLN9999 Signature: f78e64cc1a1ff5296d036681dc94f62ebfc99441045999221886bb39ff6b3c26 Example String and resulting signature for CANCELLED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feCANCELLED Signature: e8515d997826e16bc22b8d1fac325c044c4ea3b41c3002bbc0554e61f01627fd
  • [Webhooks and custom params](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/webhooks-callbacks/webhooks-and-custom-params.md): Ari10 Gateway allow to pass custom parameters ( partnerMetadata ) via the whole process of the transaction. Detailed instruction on how to set them up was described in “Getting Ari10 transactionId / Passing custom parameters” section of this documentation. The following section of documentation describes how to properly calculate signature for Webhooks / Callbacks when those custom params are being used. Examples of payloads: Calculating signature For accurate signature computation: Assemble a string incorporating all response elements in their original sequence except those included in “ partnerMetadata.partnerParams .” field which is ignored for the calculation. If a a JSON field of the response is numeric (e.g. 21.34570767): Round down value to second decimal place. (e.g. 21.34). Multiply the adjusted number by 100, ensuring the outcome value is integer. (e.g. 2134). If a JSON field is null, omit it and don't use in calculations (e.g. when mailAddress field is null) Encode the finalized string using the sha256 method, combined with the signature provided by the Ari10 team. Examples: Select... $widget_secret = “1234567890abcdef1234567890abcdef” Example String and resulting signature for STARTED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feSTARTEDPLN9999https://127.0.0.112345678-abc-9012-abc-123456789abvip-client Signature: 3f0d62971f70f2afc816efe7fcabca785efa5d2b11b2e35fcf055716a4204994 Example String and resulting signature for PAID payload provided above: String: 98765432-dcba-7890-dcba-9876543210fePAIDPLN9999https://127.0.0.1john.doe@domain.com12345678-abc-9012-abc-123456789abvip-client Signature: be0eb270effe5caa83d5b802e63723511ae293d5aaa6eebc3fccad8d3b704f15 Example String and resulting signature for FINISHED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feFINISHEDPLN9999https://127.0.0.12134john.doe@domain.com12345678-abc-9012-abc-123456789abvip-client Signature: 658fe6b64bfd785ee1959ccb1e1320c94503eb58a168bf91fb5c263b285ddc70 Example String and resulting signature for CANCELLED payload provided above: String: 98765432-dcba-7890-dcba-9876543210feCANCELLED Signature: e8515d997826e16bc22b8d1fac325c044c4ea3b41c3002bbc0554e61f01627fd
• [Get Ari10 Transaction status](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/get-ari10-transaction-status.md): The API endpoint "get /transaction/{transactionId}/status" enables users to fetch the status of a specific transaction using its unique Ari 10 transactionId. This endpoint provides real-time insights into a transaction's progress and status within the Ari10 system. It's particularly vital for integrations centered on Blockchain operations beyond just payment methods. For integrations with processes like day +1 settlements, this endpoint serves as a supplementary information source. However, in such scenarios, Webhooks, especially the one indicating a PAID status, should be the primary method for acquiring transaction details. Types and description of Transaction Statuses Statuses for Successful Transactions: ✅ “ STARTED ”: This status is designated when the Ari10 Gateway becomes visible in a web browser window. “ IN_PROGRESS ”: This is assigned when the user embarks on the SMS verification journey. “ PAYMENT_IN_PROGRESS ”: This activates as the user steps into the phase of entering the BLIK code, furnishing credit card particulars, or other pertinent data contingent on the elected payment medium. " PAID : Denotes that the Ari10 system has accepted the deposit. “ FINISHED ”: This culminates when all actions tied to the Blockchain are accomplished. Statuses for Unsuccessful Transactions: ⛔️ “ REJECTED ”: Indicated when a transaction is either flagged for potential fraud or if a user's verification process, in some instances, exceeds a 30-minute wait. “ PAYMENT_CANCELLED ”: Occurs when a user decides to abandon the payment process. Other statuses: ✅ / ☑️ “ TRADE_REJECTED ”: Occurs when everything progresses as expected, but the Blockchain processes haven't concluded. Within 24 hours, the Blockchain transaction will undergo a recheck/replay to ensure its conclusion, leading to the “FINISHED” status. Recommendation for Merchants When integrating the /status endpoint, please consider the statuses “ PAID ” and “ TRADE_REJECTED ” as indicators that a deposit is underway and generally progressing towards completion. For users who require precise tracking of blockchain transactions to accurately reflect them on their platforms, the “ FINISHED ” status is the key confirmation that all processing on the blockchain has been fully completed. While the statuses “ PAID ”, and “ TRADE_REJECTED ” typically signify that a transaction is expected to conclude successfully, it’s important to note that completion times can vary based on network traffic and other factors. In rare instances, there is a slight possibility that a transaction may not finalize as anticipated. Therefore, if a partner chooses to act upon these statuses before reaching “ FINISHED ”, they should be mindful of the small risk involved in such cases. The same considerations apply to webhook statuses.
• [Testing the implementation](https://app.theneo.io/ari10/ari10-payment-gateway-api-documentation/testing-the-implementation.md): After fully implementing the flow, partners should conduct an end-to-end walkthrough of the entire process. Deposit Test Details: For testing deposits, use your personal email and enter the designated test phone number: +48 999 999 999. Click on the “Send Code / Wyślij kod” button. The fixed security code for this number will always be 899 999. Upon proceeding, select “Test Method / Metoda Testowa” and continue with the transaction. Subsequently, the partner site should receive the correct “ PAID ” and “ FINISHED ” webhooks, facilitating an immediate top-up to the user account.