API requirements for buy bitcoin widget

Following requirements are needed to integrate BUY BITCOIN WIDGET into your blog, website or native mobile app.

To quickly start you don’t need to have any programming experience. Refer to affiliate page for customizations of your affiliate link.

Description for each customization parameter can be found under modification options section.

If you wish to integrate buy bitcoin widget into your app and have auto sendout purchased bitcoins to your provided external bitcoin address, you would need to create an API key and secret and secure the query parameters against malicious users.

Auto sendout feature is very useful for wallets integrating Paxful’s Buy Bitcoin Widget. It allows to send bitcoin automatically to provided external bitcoin address.

For integrating Paxful and paying with bitcoin in e-commerce we recommend to use our Pay with Paxful with auto sendout feature, since it is specifically tailored to e-commerce.

API-key and API-secret can be created under your Paxful account settings. Treat your API-secret as password, don’t store it in plain. For example, you can keep it encrypted in your database.

Example link with auto sendout to your provided bitcoin address is following

(NOTE: Parameter affiliate is now named kiosk_id, but you can still use affiliate. Should work with both parameter names. But this parameter is mandatory for link to be working):

https://paxful.com/roots/buy-bitcoin?affiliate=r5azdx9YA94&fiat_amount=50&fiat_currency=USD&payment_method=western-union&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo&apiseal=7f7350434390a30a7f3a9a028f7346d872f92ca58c7aec2f878f607fa2c82352

NB! If you want your link to contain the user email address, don’t forget to convert the ’@’sign into ‘%40’. For example, [email protected] should be written as name%40email.com. Otherwise the link wouldn’t work.

Reference

apikey (type: char, length: 32): client designated API-key (unique)
apiseal (type: char, length: 40): signature (digest) of the request params passed through a HMAC-SHA256 construct
Other parameters such as fiat amount, payment method etc which can be found in modification options.

API seal creation

The process of calculating the required apiseal parameter involves using a HMAC-SHA256 construct. The result is a digest, which in turn serves as a MAC for server-side validation in regards to data integrity and authenticity. You would need to concatenate all request parameters (i.e., apikey, fiat_amount) that are passed to the server when making a request, except for the apiseal parameter itself. The provided API-secret is used as the corresponding secret cryptographic key.

Example affiliate=r5azdx9YA94&fiat_amount=50&fiat_currency=USD&payment_method=western-union&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo

Passing this string with secret to your HMAC function will return API-seal that you pass to the Buy Bitcoin Widget URL (paxful.com/roots/buy-bitcoin).

Simulation

echo -n "affiliate=r5azdx9YA94&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.

For testing purposes various online HMAC Generators / Tester Tools ara available e.g. https://www.freeformatter.com

Pay attention! If your API seal is generated incorrectly, auto sendout to your provided bitcoin address will not be initiated but other settings with your affiliate ID and provided modification options will be working.

If your apiseal was correctly generated together with external crypto address it your kiosk user or while you test it would see on every step following text:

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