The payment button is the easiest way to start utilizing Dwolla's payment gateway. With no prior coding experience needed, the payment button gives any Dwolla user the ability to place payment buttons on their site and start getting paid.
When a customer clicks on a payment button, they are taken to Dwolla's website to process the instructed payment. Once checkout is completed, the customer is then redirected back to the merchant's site, along with some querystring parameters regarding the transaction.
Payment buttons are created by the button generator, and can then be replicated virtually unlimited times.
There are 3 variations of the button: simple, freetype, and an options drop-down. Here are examples of each:
User Experience
Here's a typical flow of the payment button:
-
Customer sees and click on a payment/purchase button.
-
Customer is taken to Dwolla to complete the checkout.
-
Customer gets redirected back to the merchant's website.
Installation
Installing a Dwolla payment button is as easy as copy / pasting a singple snippet of code. No prior coding experience is needed, and in fact, the button generator page was designed for those who want a dead-simple way of creating payment options.
After creating a button using the button generator, you'll need to add the button itself to your page. To do this, simply copy the code snippet generated in the genrator form, and paste that into your page. The button can go anywhere you'd like on your page.
While the payment button is easy to use, it can be quite powerful and customizable in conjunction with its different configuration options. Read more about those here »
Configuration Options
Button Script Parameters:
| Param | Description | |
|---|---|---|
| * | data-redirect | Redirect URL. This is where the customer will be taken to after the checkout process. |
| * | data-key | Consumer key for the button. This will be auto-generated and filled by the button generator. |
| * | data-amount | Price of the item. Must be $0 or more. |
| * | data-shipping | Shipping total for the order. Must be $0.00 or more. |
| * | data-tax | Tax applied the order. Must be $0.00 or more. |
| * | data-name | Name of the item. Must be 100 characters or less. |
| * | data-description | Description of the item. Must be 200 characters or less. |
| data-orderid | Merchant's order ID to identify the transaction. | |
| data-notes | Note to attach to the transaction. Limited to 250 characters. | |
| data-test | Flag if purchase order is for testing purposes only. Does not affect account balances and no emails are sent. The transaction ID will always be 'null' in the responses. | |
| data-guest-checkout | Flag to enable the Guest Checkout option. This will allow non-Dwolla users to checkout with their bank account information. | |
| data-type | Type of button to display. This can be "simple" for a simple pre-fixed amount, "freetype" for a free-type amount input, or "options" for a pre-fixed dropdown of product options (and prices). | |
| data-options | When choosing an options button type, this parameter is used to define the dropdown options. Please use the button generator form to create and populate this parameter |
Button example:
<script src="https://www.dwolla.com/scripts/button.min.js" class="dwolla_button" type="text/javascript" data-key="[YOUR KEY HERE]" data-redirect="http://www.example.com/" data-label="A Test Button!" data-name="Test Product" data-description="I love tests!" data-amount="0.99" data-shipping="0" data-tax="0" data-guest-checkout="true" data-type="freetype" > </script>
User Redirect
Upon successful payment, the user will then be redirected back to the merchant's website provided by the redirect URL provided during the request.
Redirect URL parameters:
| Param | Description |
|---|---|
| checkoutId | Unique purchase order ID generated by Off-Site Gateway. |
| orderId | Order ID provided during the request. |
| test | Flagged to 'true' if purchase order is for testing purposes only, absent otherwise. |
| transaction | Dwolla transaction ID to identify the successful transaction. If in test mode, the transaction ID has a value of 'null'. |
| postback | If the callback URL provided and the postback response completed succesfully, a value of "success" - else, "failure". |
| amount | Total amount of the purchase formatted to two decimal places. |
| signature | HMAC-SHA1 hexadecimal hash of the checkoutId and amount ampersand separated using the consumer secret of the application as the hash key. |
| clearingDate | Date and time in which the funds are to be cleared into the destination account. |
| status | Status of the checkout session. Possible values: Completed, and Failed. |
Redirect URL format
https://www.myurl.com/redirect?signature={}&orderId={}&amount={}&checkoutId={}&status={}&clearingDate={}&transaction={}&postback={}
Redirect URL example
https://www.myurl.com/redirect?signature=c50e4b2a4c50ad795c3ee31370aec1a563565aa4&orderId=&amount=0.01&checkoutId=f32b1e55-9612-4b6d-90f9-1c1519e588da&status=Completed&clearingDate=8/28/2012%203:17:18%20PM&transaction=1312616&postback=success
* Dwolla's Signature
In the user redirect querystring, Dwolla includes a signature that can be used to authenticate Dwolla's server identity. The signature is an HMAC-SHA1 hexadecimal hash of the checkoutId and amount ampersand separated using the consumer secret of the application as the hash key. Here's an example of a signature validation in some common languages:
Python
def verify_gateway_signature(proposed_signature, checkout_id, amount): import hmac import hashlib raw = '%s&%s' % (checkout_id, amount) signature = hmac.new(client_secret, raw, hashlib.sha1).hexdigest() return True if (signature == proposed_signature) else False
PHP
function verifyGatewaySignature($proposedSignature, $checkoutId, $amount) {
$amount = number_format($amount, 2);
$signature = hash_hmac("sha1", "{$checkoutId}&{$amount}", $apiSecret);
return $signature == $proposedSignature;
}