This guide walks you through the steps to integrate PAY WITH PAXFUL into your website.
Before you begin, you need to go to Paxful account settings and create your API-key and API-secret. You’ll need to use them later on in the process. Treat your API-secret as a password. Make sure it’s stored safely so that only you have access to it.
After you have generated your API-key and API-secret pair you have to sign up as a merchant. Once you’ve completed the registration, you’ll receive a “merchant ID” which is required to generate the payment links.
Generating a Payment Link
In order to initiate a payment you need to send the following parameters to “https://paxful.com/wallet/pay” endpoint.
The request made to Paxful can be either POST or GET. The order in which you use the parameters doesn’t have to match the one shown in this table. Once the payment processor receives a request to initiate a payment it will verify the validity of the payment request by recreating the signature and comparing it with the “api seal” parameter value that you have provided.
|merchant||Yes||String, max length: 11||Your designated merchant ID (unique) that you received when you registered yourself as a merchant|
|apikey||Yes||String, length: 32||Your designated API-key (unique)|
|nonce||No||String||A random integer that must be incremented in every request (common practice to use Unix timestamp)|
|to||Yes||String||The Bitcoin address where you want to receive the payments|
|track_id||No||String, max length: 100||Your unique transaction tracking code. This is passed back with a callback if transactions are successful and you can release purchased items.|
|amount||Only if “fiat_amount”, “fiat_currency” are not used||Number||The amount in Bitcoin the user has to pay|
|saveaddress||No||Number||You can optionally add saveaddress=1. This means if a user who is paying 1 Bitcoin, but has a balance of only 0.3 Bitcoins, it won’t redirect them to the Buy Bitcoin widget. Instead it will actually tell them to send their whole balance of 0.3 BTC. This is really useful for sports betting and account refilling websites, where the exact amount is not necessary and any amount would work.|
|fiat_amount||Only if “amount” is not used||Number||The amount in fiat that the user has to pay|
|fiat_currency||Only if “amount” is not used||Number||The fiat currency that the user will pay in|
Signature (digest) of the request parameters passed through an HMAC-SHA256 construct. See the next section of this guide on how to generate the signature.
Here’s a sample of a valid payment request:
Creating an API Seal
To calculate the required apiseal parameter involves using an HMAC-SHA256 construct. The result is a digest, which is used by Paxful payment gateway to verify that the data wasn’t tampered by a third-party in any way and to ensure that we process only whatever you, the merchant sent to the gateway. In order to get a digest, you need to concatenate all request parameters (i.e., apikey, nonce, to, 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.
Passing this string along with the secret to your HMAC function will return the API-seal that you pass to the PAY WITH PAXFUL URL as a value of apiseal parameter.
If you have access to shell, then you can run the following command to generate a valid “apiseal” parameter for a given request:
echo -n "merchant=jozDqmvd7mW&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo&nonce=1386178459
&to=1CkSCqyWGtVjok5A5xeGKKyMvpeZMnfEbq&amount=0.5" | openssl dgst -sha256 -hmac 98276117589486d823930f29dd0b8f3e
If your application is written in PHP then you can use the following snippet as a reference point to implement hashing and the payment link generation logic:
$apiKey = ''; // specify
$apiSecret = ''; // specify
$queryParams = [
'merchant' => '2Ld5VmJknQm', // replace
'apikey' => $apiKey,
'nonce' => time(),
'to' => 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', // replace!
'track_id' => sha1(time()),
'amount' => 0.1
$apiSeal = hash_hmac('sha256', http_build_query($queryParams), $apiSecret);
$queryParamsWithApiSeal = array_merge($queryParams, ['apiseal' => $apiSeal]);
$signedQueryString = http_build_query($queryParamsWithApiSeal);
If the query string is correct the Paxful wallet page send out dialog will open for the user with your specified Bitcoin address and amount pre-filled and the user has to make just 1 click –CONFIRM SEND to confirm the payment.
While you are developing the button, if the parameters or the HMAC calculation are incorrect, clicking the link will open the Paxful wallet page with detailed error message(s).
Pay with Paxful solution can be configured to provide callbacks to an outside address after a successful transaction.
You can set this up on your Merchant dashboard, under “Advanced: Open Customization Callbacks Panel“.