Balanced Payments extension for Symphony CMS. This extension allows direct access to Balanced's API using Symphony CMS concepts.
Add as a submodulegit submodule add https://github.com/patrickyan/balanced.git extensions/balanced --recursive
Balanced Payments extension for Symphony CMS. This extension allows direct access to Balanced's API using Symphony CMS concepts; no PHP is necessary. It is based on @lewiswharf's Stripe extension.
- Version: 0.1
- Date: 2013-09-19
The Symphony CMS Balanced Extension uses filters at its heart to carry out Balanced API calls. Regular Symphony events with Balanced filters are used to call Balanced and save response data into your section. You can also setup Balanced Webhooks with the provided event.
This extension includes:
- Filters to make calls to Balanced API
- Event to create webhooks
- Fields to store data and link entries
- Fee charging
Add your API key to System > Preferences > Balanced.
Create a section that you want to receive Balanced data.
Create an new event for that section.
Add the filter of the call you want to make.
Add the event to a page.
If the event is for a webhook, add the Balanced: Webhooks Router event to the page as well.
On the page, add a form with input fields for the arguments you want to pass to Balanced.
Interacting with your Balanced account is done by applying filters to events. Only apply a single Balanced filter to each event. You could try more than one filter, but it hasn't been tested.
Arguments must be passed in the array
balanced. For example:
<input type="hidden" value="/v1/customers/CU7GuPv9Y2F8ySwJHuHL0YWq" name="balanced[customer_uri]" />
This filter will pass
/v1/customers/CU7GuPv9Y2F8ySwJHuHL0YWq as an
customer_uri argument. If the Balanced API call is successful, the filter will capture any response from Balanced and add it to the event's fields array prior to saving into the Symphony section. Passing
balanced[customer-uri] will also work, if you prefer to stick with the Symphony convention of hyphenated names.
Webhooks are callback endpoints that Balanced sends POST requests to upon certain events, such as successfully charging a credit card.
To setup a webhook, create a page with the Balanced: Webhooks Router event and an event with a Balanced: Webhook filter. Then go to your Balanced settings and add a webhook pointing to that page.
You could do more fancy stuff with a custom PHP event.
If you want the event to save data from Balanced's response, your section needs to have fields with handles that exactly match the response.
_ in Balanced fields are automatically converted into
- to match Symphony convention.
For example, if you call Balanced: Create Customer, you might send a form with:
"balanced" : "name" : "John Doe" "action" : "create-customer" : "submit"
and you will get back
"fields" : "name" : "John Doe" "created-at" : "2013-09-19T19:22:27.785483Z" "uri": /v1/customers/AC6oBn0TTBMavvoK7ROufYU7 "transactions-uri" : "/v1/customers/AC6oBn0TTBMavvoK7ROufYU7/transactions" "type" : "customer" "uris" : ...
DO NOT SAVE CREDIT CARD NUMBERS. IT IS ILLEGAL. Balanced never exposes sensitive information, so it's okay to save whatever is in the responses. Please use balanced.js to tokenize credit cards and bank accounts.
This extension comes with 4 fields.
- Balanced: Customer URI
- Balanced: Customer Link
- Balanced: Resource URI
- Balanced: Resource Link
You can only use Customer URI and Resource URI once. This means you cannot create multiple customer sections or transaction sections.
Recommended data structure
While you do not have to store the entire response, you should store some data, like the customer's URI, so you can charge them later! Here is an example setup:
Customers Name (input) URI (balanced_customer_uri) Card URI (input) Created at (date) Transactions Type (input) Status (input) URI (balanced_resource_uri) Created at (date) Amount (number) Customer URI (balanced_customer_link) On behalf of URI (balanced_customer_link)
balanced_customer_links used that will link the transaction entry to the appropriate customer.
If you have webhooks, you can create another section that link to your transactions:
Events Event URI (input) Entity URI (balanced_resource_link) Resource (input) Type (input)
You might want to charge users fees on each purchase. This extension makes it easy to charge variable and/or fixed fees on debits and/or credits.
- Specify the fees in System > Preferences > Balanced.
- When debiting or crediting, instead of sending
- Fees are automatically calculated and added.
- Response includes
Note: Fees are rounded up to the nearest cent. Debit amounts are calculated as
subamount + fees, while credit amounts are calculated as
subamount - fees.
You can also override the fixed fees by sending any amount via
If you don't want to charge fees, just use
Arguments & responses
Balanced: Create Customer
Balanced: Create Customer and Add Card
Balanced: Create Customer and Add Bank Account
Balanced: Update Customer
Balanced: Delete Customer
Balanced: Add Card
Balanced: Add Bank Account
Balanced: Create Bank Verification
Balanced: Update Bank Verification
Balanced: Create Debit
Balanced: Refund Debit
Balanced: Create Credit
Balanced: Webhook Debit, Credit, Hold, Refund
Some responses are altered to fit the Symphony data model better.
nullresponses removed (to prevent wiping out your section)
amountconverted from cents back to dollars
- Bank Account Verification responses prefixed with
bank_account_verification_(so you can store in your customers section without conflicts)
- Refund responses prefixed with
refund_(so you can store in your transactions section without conflicts)
idremoved (to avoid conflict with Symphony system id; Balanced recommends not storing this value)
Credit card/bank account form
If you are using
balanced.js and Balanced's example script to tokenize your cards, make sure you change
<input name="action[YOUR-EVENT]" type="submit" value="Submit"/>
<input name="action[YOUR-EVENT]" type="hidden"/> <input type="submit" value="Submit"/>
as using jQuery's
submit() method will not add the
action[YOUR-EVENT] field if it is on the submit button.
Why do I get the error "Argument 2 passed to SectionEvent::processPreSaveFilters() must be of the type array"?
Your page must include at least one input for a Symphony field, i.e. you cannot create a form with only
balanced fields. If you do not want to pass any non-Balanced fields for your section, simply add
<input name="fields" type="hidden"/> to your form.
Requires Symphony 2.3
- Compatible with Sections Event
Requires Symphony 2.3
- Initial release. BETA.