Pay With Paxful - Developer Documentation

This guide walks you through the steps to integrate PAY WITH PAXFUL into your website.

Prerequisites

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.

Parameter Required? Type Description
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
apiseal Yes String

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:

https://paxful.com/wallet/pay?
merchant=jozDqmvd7mW&apikey=6bSxoS3gd2vdO458EU0UZANWyiMmKnyo&
nonce=1386178459&
to=1CkSCqyWGtVjok5A5xeGKKyMvpeZMnfEbq&
amount=0.5&
saveaddress=1&
apiseal=f950b3241ce3fb1a4664c59d60c5ac470ca3793e


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.

Simulation

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";

 

Successful Request

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.

Unsuccessful Request

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).

Callbacks

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“.

Articles in this section