API requirements for buy bitcoin widget

Following requirements are needed to integrate BUY BITCOIN WIDGET into your blog, any 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 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 so that after bitcoin purchase user’s bitcoins are sent automatically to user’s wallet provided 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 passwords, don’t store it in plain. For example keep it encrypted in your database.

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

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:
Funds will be sent to your affiliate-name account once the order is complete