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.
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.
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.
Parameter Name | Value type | Constrains | Example | Notes |
---|---|---|---|---|
apikey | Char, length: 32 | required | client designated API-key (unique) | |
apiseal | Char, length: 40 | required | Signature (digest) of the request params passed through a HMAC-SHA256 construct. See below for more info how to generate it. | |
kiosk | string | required | oNDwvjLowJQ | ID of a kiosk. Once you have created a Kiosk you can find ID here. |
r | string | recommended | xLwgPDZqEYB | Affiliate code, can be found here |
ext_crypto_address | string | recommended | 1MnWENVYf1VqKetc4zcuUuMNMg2XPrCWPr | If 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_currency | string | optional | USD | Currency ISO code |
fiat_amount | float | optional | 10.50 | |
crypto_amount_btc | float | optional | 1.05 | |
is_exact_amount | string | optional | yes | Missing 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_id | string | optional | 123456 | Required for callbacks. |
payment_method_group | string | optional | online-transfers | Available options: gift-cards, cash-deposits, online-transfers, debitcredit-cards, bank-transfers |
payment_method | string | optional | paypal | Slug of payment method. Overrides payment_method_group parameter. |
offer | string | optional | kTBhHAAxx6M | Overrides payment_method_group and payment_method parameters. |
string | optional | john.doe@example.com | If 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:
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.
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.
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 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.”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.Request payload parameter name | Description |
---|---|
track_id | String, 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. |
status | String. Always set to “SUCCESSFUL”. |
Request payload parameter name | Description |
---|---|
track_id | String, 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_currency | String. ISO identifier of fiat currency, like USD, EUR |
crypto_currency | String. ISO identifier of crypto currency, like BTC or ETH |
crypto_amount | Integer. 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) |
status | String, possible values are:
|
When the auto-registration feature is requested for a Paxful Kiosk (email is provided in the link), the system will:
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: