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.
In order to initiate a payment you need to send the following parameters to https://paxful.com/wallet/pay endpoint.
https://paxful.com/wallet/pay?merchant=jozDqmvd7mW&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo&apiseal=f950b3241ce3fb1a4664c59d60c5ac470ca3793e&nonce=1386178459&to=1CkSCqyWGtVjok5A5xeGKKyMvpeZMnfEbq&amount=0.5&saveaddress=1
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.
Parameter Name | Value type | Constrains | Notes |
---|---|---|---|
merchant | Сhar, length: 11 | required | Your designated merchant ID (unique) that you received when you registered yourself as a merchant |
apikey | Char, length: 32 | required | Your designated API-key (unique) |
apiseal | Char, length: 40 | required | 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. |
to | String | required | The Bitcoin address where you want to receive the payments |
amount | Number | optional | The amount in Bitcoin the user has to pay. Only if fiat_amount, fiat_currency are not used |
fiat_amount | Number | optional | The amount in fiat that the user has to pay. Only if amount is not used |
fiat_currency | Number | optional | The fiat currency that the user will pay in. Only if amount is not used |
track_id | Char, length: 100 | optional | Your unique transaction tracking code. This is passed back with a callback if transactions are successful and you can release purchased items. |
saveaddress | Number | optional | 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. |
nonce | Number | optional | A random integer that must be incremented in every request (common practice to use Unix timestamp) |
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 PAXFUL PAY 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:
<?php $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); echo "https://paxful.com/wallet/pay?$signedQueryString"; ?>
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).
Paxful Pay 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“.