• Pay With Paxful - Developer Documentation

    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.

    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:


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


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

  • Pay with Paxful
    What is Pay with Paxful?
    Pay with Paxful is a button you can put on your e-commerce/business site solution that lets buyers pay with lots of payment methods, including gift cards.

    Pay With Paxful is great if you have a website and you are selling access, online or physical products. It can be a payment method beside your current ones that will bring in more customers and you don’t have to worry as the process is chargeback free.

    As a merchant, you do need to be willing to accept payment in BTC but there is a multitude of ways to convert it periodically to your local fiat currency.

    How does it work?
    Pay With Paxful brings together three sides: merchants (selling something), buyers (wanting to buy something) and Paxful vendors (exchanging buyer payment methods to BTC). The solution is unique as transactions are handled through the robust Paxful platform trades (which happen peer-to-peer).

    Merchants have control over the configuration of the solution and can track every transaction through a track ID. On every successful payment, a callback can be configured which can be set up to release the goods to the buyers on the merchant side.

    Merchants have a complete transaction list available on their Paxful Merchant Dashboard.

    How secure is Pay with Paxful?
    The Pay with Paxful button uses our secure escrow system and battle-tested platform. Your buyers are safe.
    You, as a merchant, are safe as Paxful uses a secure URL token system to prevent phishing and protect buyers as well as the merchant. To enable automatic send-outs to your bitcoin address, you must use our secure token system. Please refer to our developer page.
    Expected earnings with Pay with Paxful and how to track them.
    How much you can earn depends on the transactions completed by buyers.

    Every time a sale completes successfully you will see the transaction on the Merchant Dashboard and you can set up a callback solution to automate the resulting actions on your end.

    Payments are handled in bitcoin. This means you can keep them as BTC in your Merchant account for exchange for EUR/USD/etc. There are many services available for this, you can even use exchanges such as Kraken.

    Note: there is an extra (free) step to move the funds from your merchant account to your Paxful wallet.

    How much control do I have? Do my visitors ever leave my site?
    The Kiosk link can be configured to open in a new tab OR can be configured to open inside an iframe. You can set it up so the solution is embedded as an iframe right into pages so that visitors never leave your website. As a part of the process, your users will need to register as Paxful users, but you as a merchant can make the process smoother by providing the user email together with the generated URL so it would be pre-filled for users.
    What are the different configuration options?
    You choose how you want to configure the link. There are some options regarding:
    Currency: You can request the payment in either BTC or in FIAT currency (Paxful can convert the sum based on the market price).
    Sum: Normally you define this, but there is an option to request all user’s Paxful balance (or if the balance is 0, then let the user define it).
    Registration: You can define the user email, to make the purchase process easier.
    Receiver: By default, funds are deposited on your merchant account balance but it is possible to configure deposits to any Bitcoin address.
    Callback: You have to define the Callback address which can handle the callback parameters.

    The full list of technical parameters is available here: (https://developers.paxful.com/pay-with-paxful/authentication-requirements/).

    How easy is this to use really?
    For merchants, the process of setting it up is quite straightforward. You need to do some coding to configure the link generation. You can find examples from the developer documentation: developer page.

    For buyers, the purchase process will be a little unusual. They need to complete a trade with another person, but the solution holds a unique value proposal for them. We are already working to improve the buyer's experience.

    What are the fees involved?
    As a Merchant, there are no fees to use Pay with Paxful.

    Buyers have to pay the standard premiums set by Vendors. This means that buyers do have to pay more than the amount you are requesting from them to cover the Vendor premiums.

    If you want to use External BTC addresses for transactions, then each time an external transaction is used, please refer to this article for the full list of fees. 

    What are the minimum and maximum payments possible?
    A merchant can request any sum, but the minimum trade amount is 10 dollars (also in other currencies). Any amount larger than the amount requested by the merchant will stay in the buyer's Paxful balance and they can use it or withdraw it at any time.

    There is no direct limitation to the purchase sizes but for large sums, a buyer might have to do multiple trades and also vendor can request additional KYC procedures.

    Where to find more information regarding Pay with Paxful?
    More information can be found on the landing page: https://paxful.com/pay-with-paxful and the developer guide here: https://developers.paxful.com/pay-with-paxful/introduction/

    It is also possible to write to support or get a personal account manager for larger merchants.