Kiosk

API requirements for Paxful Kiosk

In this guide, you’ll learn how to add the Paxful Kiosk integration to your blog, website, or native mobile application. The Paxful Kiosk allows you to fine-tune a link that you can integrate into your platform that can be used to jumpstart a trade.

After reading this guide, you’ll be able to generate a secure link that a user can follow to start trading. You can also set up additional parameters to automatically send the funds to your wallet address after a trade is completed.

For e-commerce, we recommend using our Paxful Pay integration that has an auto sendout feature. More information about the Paxful Pay integration can be found here.

The main difference between the Paxful Kiosk and Paxful Pay products is that Paxful Pay assumes that a Paxful user already has the funds to conduct a payment. The Paxful Kiosk allows a user to execute a trade before the transaction to get crypto and then have it transferred to you/let you earn commission off it (if the Affiliate Program is used, see below for more information).

First, you need to create your own Paxful Kiosk — https://paxful.com/buy-bitcoin-kiosk. Once your account is set up, you’ll need to create an API key and secret to secure the query parameters against malicious users. The API-key and API-secret can be created in your account under Account settings > Developer ( https://paxful.com/account/developer ). You should treat your API-secret like a password — don’t share it with anyone!

We also recommend checking out the Affiliate Program page to learn more about customizing your affiliate link. Sharing your affiliate link allows you to earn 50% of the escrow fee when the people you bring on board buy Bitcoin on Paxful. You’ll also earn another 10% of the escrow fee from the people they invite.

Modification options

Example link
https://paxful.com/roots/buy-bitcoin?kiosk=oNDwvjLowJQ&r=xLwgPDZqEYB&fiat_amount=50&fiat_currency=USD&payment_method=western-union&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo&apiseal=7f7350434390a30a7f3a9a028f7346d872f92ca58c7aec2f878f607fa2c82352

You can modify the Paxful Kiosk to your needs by showing only specific offers and payment methods, and you can even send your Bitcoin to your BTC address after a successful transaction.

While testing different parameters, you may see that you’re redirected to the same step in Paxful Kiosk. This is because Paxful Kiosk memorises a current step of the buying process and in cases where a bitcoin buyer accidentally closes a page which contains a kiosk, then when page is reopened the kiosk will display the same step where a user has left from. To fix this, head back to the first step and open your link with new parameters. Any old user states are deleted after 24 hours.
Parameter NameValue typeConstrainsExampleNotes
apikeyChar, length: 32requiredclient designated API-key (unique)
apisealChar, length: 40requiredSignature (digest) of the request params passed through a HMAC-SHA256 construct. See below for more info how to generate it.
kioskstringrequiredoNDwvjLowJQID of a kiosk. Once you have created a Kiosk you can find ID here.
rstringrecommendedxLwgPDZqEYBAffiliate code, can be found here
ext_crypto_addressstringrecommended1MnWENVYf1VqKetc4zcuUuMNMg2XPrCWPrIf filled, Bitcoins will automatically be sent to this BTC address after the trade is complete. Apikey and apiseal parameters are required. Paxful pays for a transaction fee if the transfer happens on the blockchain instead of between two Paxful wallets.
fiat_currencystringoptionalUSDCurrency ISO code
fiat_amountfloatoptional10.50
crypto_amount_btcfloatoptional1.05
is_exact_amountstringoptionalyesMissing or any value other than “yes” means false. This is needed when the exact Bitcoin amount is required. Check below for possible combinations of fiat_amount and crypto_amount_btc.
track_idstringoptional123456Required for callbacks.
payment_method_groupstringoptionalonline-transfersAvailable options: gift-cards, cash-deposits, online-transfers, debitcredit-cards, bank-transfers
payment_methodstringoptionalpaypalSlug of payment method. Overrides payment_method_group parameter.
offerstringoptionalkTBhHAAxx6MOverrides payment_method_group and payment_method parameters.
emailstringoptionaljohn.doe@example.comIf your Kiosk has a “trusted” status, you may leverage the auto-registration feature by specifying a user’s email in this parameter. If you want your link to contain the user’s email address, don’t forget to convert the ’@’ sign into ‘%40’. For example, name@email.com should be written as name%40email.com, otherwise the link won’t work.

When you’re passing fiat_amount or crypto_amount_btc combinations, these are the results:

  • fiat_amount=100&crypto_amount_btc=2 — fiat amount is taken
  • fiat_amount=100&crypto_amount_btc=2&is_exact_amount=yes — crypto amount is taken
  • fiat_amount=100&is_exact_amount=yes — error
  • crypto_amount_btc=2 — error
  • fiat_amount=100 — fiat amount is taken
This was developed for cases where the fiat amount is passed (offers with various Bitcoin amounts are shown since vendors set their own margins) but the user needs exactly 1 Bitcoin. ‘is_exact_amount’ needs to be added here so the offers with various fiat amounts can be shown. Buying 1 Bitcon costs less when buying with cash deposits (Western Union, Moneygram, etc.) compared to gift cards (Amazon, Target, etc.).

API seal creation

Calculating the required apiseal parameter uses an HMAC-SHA256 construct. The result is a digest, which is used by the Paxful payment gateway to verify that the data hasn’t been tampered by a third-party and to make sure we process only what you send to the gateway. To get a digest, you need to concatenate all request parameters (i.e., apikey, kiosk, fiat_currency) that are passed to the server when making a request, aside from the apiseal parameter itself. The API-secret will be used as the corresponding secret cryptographic key.

Example
            kiosk=oNDwvjLowJQ&fiat_amount=50&fiat_currency=USD&payment_method=western-union&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo
                        

Passing this string along with the secret to your HMAC function will return the API-seal that you pass to the Paxful Kiosk as a value of apiseal parameter.

Simulation
echo -n "kiosk=oNDwvjLowJQ&fiat_amount=50&fiat_currency=USD&payment_method=western-union&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo" | openssl dgst -sha256 -hmac 98276117589486d823930f29dd0b8f3e(stdin)=84493978f3af6e2527bc05e8ac94609345fd5f72c911f5f4968d38058b3f71ea

where 98276117589486d823930f29dd0b8f3e is your API-secret that you received under your account settings.

If your application is written in PHP, you can use the following snippet as a reference point to implement hashing and the payment link generation logic:

<?php
    $apiKey = ''; // specify
    $apiSecret = ''; // specify
    $queryParams = [
        'apikey' => $apiKey,
        'kiosk' => 'oNDwvjLowJQ' // replace
    ];
    $apiSeal = hash_hmac('sha256', http_build_query($queryParams), $apiSecret);
    $queryParamsWithApiSeal = array_merge($queryParams, ['apiseal' => $apiSeal]);
    $signedQueryString = http_build_query($queryParamsWithApiSeal);
    echo "https://paxful.com/roots/buy-bitcoin?$signedQueryString";
?>

For testing purposes, you can use online HMAC generators/ tester tools.Here’s an example: https://www.freeformatter.com

If your API seal is generated incorrectly, an auto send-out to your provided BTC address will not be initiated, but other settings with your affiliate ID and modification options will still work.

If your apiseal was correctly generated together with an external crypto address, you will see the following text on each step when you’re testing:

“You'll receive funds in your external wallet provided by <kiosk_name> once the order is complete.”

Callbacks

The Paxful Kiosk can be configured to provide callbacks to an outside address during user registration, on a successful, cancelled or expired trade. Configuration can be set up on your Kiosk dashboard, under Customize your Kiosk link > Customize your callbacks links. Callbacks are sent using the POST method.

Being on a Kiosk Dashboard page you can also test a webhook integration. For this, you need to specify a URL where the callback should be made and you can also specify parameters depending on the callback type. For example, when you’re testing the “Trade completed callback”, you can specify values for fields like “Fiat currency”, “Fiat amount”.

Below you’ll see available callbacks and parameters that their payload will contain.
User registered event callback
Request payload parameter nameDescription
track_idString, max length: 64. An optional value that you may specify during configuration and whenever an action happens, then callback payload will include it. May be useful if you happen to have several kiosks and would like to have an easy way to distinguish them.
statusString. Always set to “SUCCESSFUL”.
Trade completed callback
Request payload parameter nameDescription
track_idString, max length: 64. An optional value that you may specify during configuration and whenever an action happens, then callback payload will include it. May be useful if you happen to have several kiosks and would like to have an easy way to distinguish them.
fiat_currencyString. ISO identifier of fiat currency, like USD, EUR
crypto_currencyString. ISO identifier of crypto currency, like BTC or ETH
crypto_amountInteger. Amount of the trade in satoshis, (for instance, if a trade amount happens to be 1 BTC then the value is going to be 100000000)
statusString, possible values are:
  • SUCCESS
  • CANCELLED
  • EXPIRED

User auto-registration feature

When the auto-registration feature is requested for a Paxful Kiosk (email is provided in the link), the system will:

  • create a Paxful account for the Kiosk customer;
  • autologin the customer to the Kiosk;
  • auto verify the customer’s email.

The customer only needs to set a new password for the account and verify the phone number to finish registration.

The next conditions should be met for auto registration:

  • the kiosk should be trusted (please contact support)
  • the kiosk customer should not be a Paxful user (customer’s email is not present in Paxful DB)
  • the kiosk link should contain the next parameters with the valid values:
    • email
    • fiat_currency
    • fiat_amount
    • apikey
    • apiseal
Each kiosk link is unique and can only be used one time. If the customer opens the link but does not complete registration, the link won’t work if they decide to try it later.
This website uses cookies to ensure you get the best experience on our website.Learn more