Advice and answers from the BitPay Team

This is a complete example tutorial on how to use the BitPay PHP library to successfully create keys, pair with a merchant account, generate tokens, and generate invoices. 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

You might notice the example code used in this guide is pretty much lifted from the sample scripts in the library's /tutorial folder. I've made only slight edits to format for this guide.

STEP 1: Create and persist (save) a public & private keypair:

/**
 * Start by creating a PrivateKey object:
 */
$privateKey = new \Bitpay\PrivateKey('/tmp/bitpay.pri');
$privateKey->generate();
/**
 * Once we have a private key, a public
 * key is created from it.
 */
$publicKey = new \Bitpay\PublicKey('/tmp/bitpay.pub');
$publicKey->setPrivateKey($privateKey);
$publicKey->generate();
/**
 * For security reasons it is recommended
 * that you use the EncryptedFilesystemStorage
 * engine to persist (save) your keys. You can,
 * of course, create your own storage engine to
 * suite your specific app's needs as long as it
 * implements the StorageInterface. In this
 * example, I'm using the regular unencrypted
 * FilesystemStorage engine so that you can
 * see what's inside the key files & for your
 * learning purposes.
 */
$storageEngine = new \Bitpay\Storage\FilesystemStorage();
$storageEngine->persist($privateKey);
$storageEngine->persist($publicKey);

STEP 2: Log into your Merchant Dashboard and create a pairing code so we can generate our API token (https://test.bitpay.com/dashboard/merchant/api-tokens). Copy the resulting pairing code. For example, it might look something like "trweFdy".

STEP 3: Pair with your Merchant account using the pairing code generated in Step 2. This will generate a token we will use to access certain BitPay API resources:

/**
 * To load keys that you have previously saved,
 * you must use the same storage engine. You
 * also must specify the same location for each
 * key you want to load.
 */
$storageEngine = new \Bitpay\Storage\FilesystemStorage();
$privateKey = $storageEngine->load('/tmp/bitpay.pri');
$publicKey = $storageEngine->load('/tmp/bitpay.pub');
/**
 * Generate our SIN:
 */
$sin = \Bitpay\SinKey::create()->setPublicKey($publicKey)->generate();
/**
 * Create the client:
 */
$client = new \Bitpay\Client\Client();
/**
 * The network is either livenet or testnet. You
 * can also create your own as long as it
 * implements the NetworkInterface. In this
 * example we will use testnet.
 */
$network = new \Bitpay\Network\Testnet();
/**
 * The adapter is what will make the calls to
 * BitPay and return the response from BitPay.
 * This can be updated or changed as long
 * as it implements the AdapterInterface.
 */
$adapter = new \Bitpay\Client\Adapter\CurlAdapter();
/**
 * Now all the objects are created and we can
 * inject them into the client.
 */
$client->setPrivateKey($privateKey);
$client->setPublicKey($publicKey);
$client->setNetwork($network);
$client->setAdapter($adapter);
/**
 * Paste the pairing code you generated
 * in your merchant dashboard in STEP 2:
 */
$pairingCode = 'trweFdy';
$token = $client->createToken(
 array(
 'pairingCode' => $pairingCode,
 'label' => 'Some description...',
 'id' => (string) $sin,
 )
);
/**
 * Now persist (save) the token obtained OR,
 * after it's created initially, you can call the
 * getTokens() method to retrieve all tokens
 * associated with your key.
 */
$persistThisValue = $token->getToken();
echo 'Token obtained: ' . $persistThisValue . PHP_EOL;

STEP 4: Now that you've successfully paired and created a new API token, you can create invoices:

/**
 * Same setup as before...
 */
$storageEngine = new \Bitpay\Storage\FilesystemStorage();
$privateKey = $storageEngine->load('/tmp/bitpay.pri');
$publicKey = $storageEngine->load('/tmp/bitpay.pub');
$client = new \Bitpay\Client\Client();
$network = new \Bitpay\Network\Testnet();
$adapter = new \Bitpay\Client\Adapter\CurlAdapter();
$client->setPrivateKey($privateKey);
$client->setPublicKey($publicKey);
$client->setNetwork($network);
$client->setAdapter($adapter);
/**
 * The last object that must be injected into
 * the client object is the token object. If
 * you didn't persist (save) it previously,
 * you can make a call to getTokens() and
 * retrieve the specific token value used in
 * the setToken() method parameter.
 */
$token = new \Bitpay\Token();
$token->setToken('qweRQWER1234123qeqwerqwerQWERQWERQWER13412341234');
$client->setToken($token);
/**
 * Create an Invoice object now. You can check
 * the InvoiceInterface for possible methods you
 * can use on this object - FYI.
 */
$invoice = new \Bitpay\Invoice();
/**
 * Create an Item object to store the details
 * of the item on your invoice. Then inject
 * the Item object into the Invoice object.
 */
$item = new \Bitpay\Item();
$item->setCode('skuNumber');
$item->setDescription('General Description of Item');
$item->setPrice('1.99');
$invoice->setItem($item);
/**
 * BitPay supports many different currencies.
 * and most shopping cart applications have a 
 * defined set of currencies that can be used.
 * Call the setCurrency() method on the Invoice
 * object to specify the currency you wish to
 * use for this invoice. For the current list
 * of currencies supported by BitPay, see:
 * https://test.bitpay.com/bitcoin-exchange-rates
 * Also, if you wish to use rate data in your app,
 * see https://bitpay.com/api/rates for the rates
 * in an easily consumable JSON format.
 */
$invoice->setCurrency(new \Bitpay\Currency('USD'));
/**
 * Now create our invoice...
 */
$client->createInvoice($invoice);
/**
 * Simply displaying the invoice info here. In
 * your application, you'd redirect the user
 * to this URL so they can pay this invoice.
 * If you want to embed this invoice in an 
 * iFrame, append &view=iframe to the URL
 * and specify this as the src parameter in
 * the iFrame tag itself. For more information
 * on displaying invoices, see:
 * https://bitpay.com/docs/display-invoice
 */
echo 'Success! Created invoice "' . $invoice->getId() . '". See ' . $invoice->getUrl() . PHP_EOL;

For example, in my own test I received the response:
Success! Created invoice "LNsKRTJxeWUUfHmKitdPVG". See https://test.bitpay.com/invoice?id=LNsKRTJxeWUUfHmKitdPVG

That's all there is to it! Using the steps above, you will be able to easily and successfully pair with a merchant account, create/get tokens, and create/get invoices. Also, after you've completed STEPS 1 - 3, you only need to do STEP 4 afterward when creating new invoices.

If you run into issues developing your PHP application and have specific questions related to our PHP Library or API calls, feel free to send an email to integrations@bitpay.com. We regret that we cannot help develop or debug entire applications but we're happy to help with specific issues you're running into.

Did this answer your question?