Advice and answers from the BitPay Team

By default, the PHP library creates a Point-of-Sale facade token but there are certain BitPay API endpoints only accessible with a merchant facade token. In this howto guide I'm going to show you how to easily create a merchant token to utilize those restricted resources. To get started, you'll need to download and install the latest release of our PHP Library from the GitHub repository here: https://github.com/bitpay/php-bitpay-client/releases/latest

If you've not used the API previously then you'll want to generate a new keypair for this exercise. Take a look at my other PHP library usage tutorial for more information on creating keys: https://labs.bitpay.com/t/bitpay-php-library-usage-tutorial-from-start-creating-keys-to-finish-creating-an-invoice/545/1. However, if you already have a keypair then you're good to go! You can use the same keys for this process of requesting a new merchant token.

So, whereas previously you created a pairing code inside your BitPay Merchant Dashboard and the call to createTokens looked like this:

/**
  * Using the pairing code you generated
  * from inside your merchant dashboard:
  */
$pairingCode = 'trweFdy';
$token = $client->createToken(
    array(
        'pairingCode' => $pairingCode,
        'label'       => 'Some description...',
        'id'          => (string) $sin,
    )
);

This method of pairing is called "server-side pairing" since you're creating the pairing code on BitPay's server. All tokens generated using the Merchant Dashboard in this manner are Point-of-Sale tokens and cannot be changed.

To navigate around this limitation and create a different facade token type, we are going to request our pairing code directly through the PHP library. This method of pairing is called "client-side pairing" since you are creating a pairing code from your server (the client).

Our call to createToken is going to differ slightly. Instead of using the pairingCode parameter, we're going to specify the facade parameter like this:

/**
  * Now we're creating a merchant token
  */
$token = $client->createToken(
    array(
        'facade'      => 'merchant',
        'label'       => 'Some description...',
        'id'          => (string) $sin,
    )
);

This BitPay API call will return a JSON payload containing the pairing code that you'll use to activate your new merchant token. For example, the returned JSON data might look like this:

{"data":[
 {"policies":[
   {
    "policy":"id",
    "method":"inactive",
    "params":["TfBAL1TtckhFET4LNzRuTfCc..."]        
   }
 ],    
 "token":"DsyNv4xXMuMyQAfPtkznyZ7T5Sxny...",    
 "facade":"merchant",    
 "label":"Some description...",    
 "dateCreated":1436986447652,    
 "pairingExpiration":1437072847652,    
 "pairingCode":"Wp4RRAz"    }]
}

The last step to actually pairing with this pairing code is to append this value onto a special URL. If you're doing this programatically, it should look like:

$url = 'https://' . $network_option . 'bitpay.com/api-access-request?pairingCode=' . $pairing_code

In this example, I'm also using an additional variable $network_option for the ability to use the test network. Navigating to this URL will request that you log into your Merchant Dashboard (if you're not already) and click "approve" to pair with this new merchant token.

Keep in mind that pairing codes expire so if you don't use them within 24 hours you'll have to regenerate a new one.

And here's our final result: a newly paired merchant token!

For more information on which BitPay API endpoints require the merchant facade, see: https://bitpay.com/api

Did this answer your question?