Changelog
Changelog

Dark mode

Welcome to Ari10 Payment Docs

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

Was this section helpful?

What made this section unhelpful for you?

Getting Started

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

  1. 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)
  2. 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)
  3. 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: 🪜

  1. Generate an Ari10 transactionId
  2. Display Ari10 Gateway Widget on your page with the use of previously generated Ari10 transactionId
  3. 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.

Was this section helpful?

What made this section unhelpful for you?

Getting Ari10 transactionId

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.

Header Parameters

Ari10-Widget-Idstring Required
Content-Typestring Required

Body Parameters

widgetBaseUrlstring Required

The url to which user will be redirected after transaction concludes.

offeredCurrencyCodestring Required

The code representing the currency in which the goods are being offered for purchase. This parameter is included in the request body.

offeredAmountstring (double)Required

The amount of the offered currency that is being requested for the goods. This parameter is included in the request body.

signaturestring Required

The signature generated for the transaction to ensure its authenticity and integrity. This parameter is included in the request body.

Responses

200
Object
OK

Response Attributes

transactionIdstring Required

The unique identifier assigned to the transaction. This parameter is included in the response.

403
Object
Forbidden

Base URL

Production:

https://gateway.ari10.com

Sandbox / Test:

https://gateway-dev.ari10.com

POST

/goods/transaction

Select
1 2 3 4 5 6 7 8 9 curl --location 'https://gateway.ari10.com/goods/transaction' \ --header 'Ari10-Widget-Id: YOUR-WIDGET-ID' \ --header 'Content-Type: application/json' \ --data '{ "widgetBaseUrl": "", "offeredCurrencyCode": "", "offeredAmount": "", "signature": "" }'

Response

{
  "transactionId": ""
}

Payment Methods

Depending on your agreement, multiple payment methods can be used. Out of all of them mostly used are:

  1. Blik fast payment method 💸
  2. Credit Card Payments 💳
  3. 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

Was this section helpful?

What made this section unhelpful for you?

Rendering the Ari10 Gateway

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.

HTML

html
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>

HTML

html
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

Webhooks / Callbacks

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:

  1. 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).
  2. If a a JSON field of the response is numeric (e.g. 21.34570767):
    1. Round down value to second decimal place. (e.g. 21.34).
    2. Multiply the adjusted number by 100, ensuring the outcome value is integer. (e.g. 2134).
  3. If a JSON field is null, omit it and don't use in calculations (e.g. when mailAddress field is null)
  4. Encode the finalized string using the sha256 method, combined with the signature provided by the Ari10 team.

Examples:

PLAINTEXT
$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

Responses

STARTED
Object

Response Attributes

transactionIdstring
statusstring
offeredCurrencyCodestring
offeredAmountnumber (float)
widgetBaseUrlstring

widgetBaseUrl provided during Transaction ID generation.

signaturestring

Response Attributes

transactionIdstring
statusstring
offeredCurrencyCodestring
offeredAmountnumber (float)
widgetBaseUrlstring

widgetBaseUrl provided during Transaction ID generation.

finalBuyAmountnumber (float)
Empty value:
True
mailAddressstring
Empty value:
True
signaturestring
FINISHED
Object

Response Attributes

transactionIdstring
statusstring
offeredCurrencyCodestring
offeredAmountnumber (float)
widgetBaseUrlstring

widgetBaseUrl provided during Transaction ID generation.

finalBuyAmountnumber (float)
Empty value:
True
mailAddressstring
Empty value:
True
signaturestring
CANCELLED
Object

Response Attributes

transactionIdstring
statusstring
signaturestring

Response

{
  "transactionId": "98765432-dcba-7890-dcba-9876543210fe",
  "status": "STARTED",
  "offeredCurrencyCode": "PLN",
  "offeredAmount": 99.99,
  "widgetBaseUrl": "https://127.0.0.1",
  "signature": "6999f05d9203f5ea36c3d22658b83ff2e99bd79572d9c8d796b0b0610aba756f"
}

Get Ari10 Transaction status

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: ✅

  1. “STARTED”: This status is designated when the Ari10 Gateway becomes visible in a web browser window.
  2. “IN_PROGRESS”: This is assigned when the user embarks on the SMS verification journey.
  3. “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.
  4. "PAID: Denotes that the Ari10 system has accepted the deposit.
  5. “FINISHED”: This culminates when all actions tied to the Blockchain are accomplished.

Statuses for Unsuccessful Transactions: ⛔️

  1. “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.
  2. “PAYMENT_CANCELLED”: Occurs when a user decides to abandon the payment process.

Other statuses: ✅ / ☑️

  1. “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.

Header Parameters

Ari10-Widget-Idstring

Also known as API_KEY

Path Parameters

transactionIdstring Required

The ID of the transaction for which you want to retrieve the status. This parameter is a path parameter, meaning it should be included in the URL after the word "transaction", followed by the actual ID.

Responses

200
Object

Response Attributes

idstring
statusstring
startTimearray (date-time)

Show child attributes

403
Object
Forbidden
Was this section helpful?

What made this section unhelpful for you?

GET

/transaction/{transactionId}/status

Select
1 2 curl --location --globoff 'https://gateway.ari10.com/transaction/{transactionId}/status' \ --header 'Ari10-Widget-Id: 12345678-abcd-1234-abcd-0123456789ab' \

Response

{
  "id": "98765432-dcba-7890-dcba-9876543210fe",
  "status": "FINISHED",
  "startTime": [
    2023,
    8,
    23,
    23,
    54,
    38,
    859000000
  ]
}

Testing the implementation

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.

Was this section helpful?

What made this section unhelpful for you?