To see a completed integration in a Ruby on Rails app, visit this repository.
#1. Installation
Add these lines to your application's Gemfile:
gem 'promisepay'And then execute:
$ bundle
Or install it yourself as:
$ gem install promisepay
#2. Configuration
Before interacting with Promispay API you need to generate an access token.
See PromisePay documentation for more information.
Create a PromisePay client
The client can be configured through environment variables.
# In your environment file
PROMISEPAY_USERNAME ||= youremailaddress
PROMISEPAY_TOKEN ||= y0urt0k3n12345678910123456789101The following parameters are configurable through the client:
:username/ENV['PROMISEPAY_USERNAME']: username for basic authentication:token/ENV['PROMISEPAY_TOKEN']: token for basic authentication:environment/ENV['PROMISEPAY_ENVIRONMENT']: API environment to use (default: 'test'):api_domain/ENV['PROMISEPAY_API_DOMAIN']: API domain name to use (default: 'api.promisepay.com')
Instantiate the PromisePay client.
client = Promisepay::Client.new(username: ENV['PROMISEPAY_USERNAME'], token: ENV['PROMISEPAY_TOKEN'])#3. Examples
##Tokens
The below example shows the controller request for a marketplace configured to have the Item and User IDs generated automatically for them. Note: by default, the ability to have PromisePay auto generate IDs is turned off. However, it can easily be requested by contacting PromisePay support.
token_request = client.tokens.create(:session, {
current_user: 'seller',
item_name: 'Test Item',
amount: '2500',
seller_lastname: 'Seller',
seller_firstname: 'Sally',
buyer_lastname: 'Buyer',
buyer_firstname: 'Bobby',
buyer_country: 'AUS',
seller_country: 'USA',
seller_email: 'sally.seller@promisepay.com',
buyer_email: 'bobby.buyer@promisepay.com',
fee_ids: [],
payment_type_id: 2
})
token = token_request['token']
item_id = token_request['item']
buyer_id = token_request['buyer']
seller_id = token_request['seller']#####Example 2 - Request session token The below example shows the request for a marketplace that passes the Item and User IDs.
token = client.tokens.create(:session, {
current_user_id: 'seller1234',
item_name: 'Test Item',
amount: '2500',
seller_lastname: 'Seller',
seller_firstname: 'Sally',
buyer_lastname: 'Buyer',
buyer_firstname: 'Bobby',
buyer_country: 'AUS',
seller_country: 'USA',
seller_email: 'sally.seller@promisepay.com',
buyer_email: 'bobby.buyer@promisepay.com',
external_item_id: 'TestItemId1234',
external_seller_id: 'seller1234',
external_buyer_id: 'buyer1234',
fee_ids: [],
payment_type_id: 2
})['token']##Items
#####Create an item
item = client.items.create(
id: '12345',
name: 'test item for 5AUD',
amount: '500',
payment_type: '1',
buyer_id: buyer.id,
seller_id: seller.id,
fee_ids: fee.id,
description: '5AUD transfer'
)#####Get an item
item = client.items.find('1')#####Get a list of items
items = client.items.find_all#####Update an item
item.update(name: 'new name')#####Cancel an item
item.cancel#####Get an item status
item.status#####Get an item's buyer
item.buyer#####Get an item's seller
item.seller#####Get an item's fees
item.fees#####Get an item's transactions
item.transaction#####Get an item's wire details
item.wire_details#####Get an item's BPAY details
item.bpay_details##Users
#####Create a user
user = client.users.create(
id: '123456',
first_name: 'test',
last_name: 'buyer',
email: 'buyer@test.com',
address_line1: '48 collingwood',
state: 'vic',
city: 'Mel',
zip: '3000',
country: 'AUS',
dob:'12/06/1980'
)#####Update a user
user = client.users.update(
id: '123456',
first_name: 'test',
last_name: 'buyer',
email: 'buyer@test.com',
address_line1: '48 collingwood',
state: 'vic',
city: 'Mel',
zip: '3000',
country: 'AUS',
dob:'12/06/1980'
)#####Get a user
user = client.users.find('1')#####Get a list of users
users = client.users.find_all#####Get a user's card account
user.card_account#####Get a user's PayPal account
user.paypal_account#####Get a user's bank account
user.bank_account#####Get a user's items
user.items#####Get a user's address
user.address#####Set a user's disbursement account
user.disbursement_account(bank_account.id)##Item Actions #####Make payment
item.make_payment(
account_id: buyer_card_account.id
)#####Request payment
item.request_payment#####Release payment
item.release_payment#####Request release
item.request_release#####Cancel
item.cancel#####Acknowledge wire
item.acknowledge_wire#####Acknowledge PayPal
item.acknowledge_paypal#####Revert wire
item.revert_wire#####Request refund
item.request_refund(
refund_amount: '1000',
refund_message: 'because'
)#####Refund
item.refund(
refund_amount: '1000',
refund_message: 'because'
)##Card Accounts #####Create a card account
card_account = client.card_accounts.create(
user_id: buyer.id,
full_name: 'test Buyer',
number: '4111 1111 1111 1111',
expiry_month: Time.now.month,
expiry_year: Time.now.year + 1,
cvv: '123'
)#####Get a card account
card_account = client.card_accounts.find('1')#####Deactivate a card account
card_account.deactivate#####Get a card account's users
card_account.user##Bank Accounts #####Create a bank account
bank_account = client.bank_accounts.create(
user_id: seller.id,
bank_name: 'Nab',
account_name: 'test seller',
routing_number: '22222222',
account_number: '1234567890',
account_type: 'savings',
holder_type: 'personal',
country: 'AUS'
)#####Get a bank account
bank_account = client.bank_accounts.find('1')#####Deactivate a bank account
bank_account.deactivate#####Get a bank account's users
bank_account.user#####Validate Routing Number
client.bank_accounts.validate('122235821')##PayPal Accounts #####Create a PayPal account
paypal_account = client.paypal_accounts.create(
user_id: seller.id,
paypal_email: 'seller@promisepay.com'
)#####Get a PayPal account
paypal_account = client.paypal_accounts.find('1')#####Deactivate a PayPal account
paypal_account.deactivate#####Get a PayPal account's users
paypal_account.user##Companies
#####Create a company
client.companies.create(
user_id: "1",
name: "Acme Co",
legal_name: "Acme Co Pty Ltd",
tax_number: "1231231",
charge_tax: true,
address_line1: "123 Test St",
address_line2: "",
city: "Melbourne",
state: "VIC",
zip: "3000",
country: "AUS"
)#####Get a company
client.companies.find('compamy_id')#####Get a list of companies
client.companies.find_all#####Get a company's address
company.address#####Update a company
client.companies.update(
id: "8d578b9c-5b79-11e5-885d-feff819cdc9f",
name: "Acme Co",
legal_name: "Acme Co Pty Ltd",
tax_number: "1231231",
charge_tax: true,
address_line1: "123 Test St",
address_line2: "",
city: "Melbourne",
state: "VIC",
zip: "3000",
country: "AUS"
)##Fees #####Get a list of fees
fees = client.fees.find_all#####Get a fee
fees = client.fees.find('1')#####Create a fee
fee = client.fees.create(
name: 'test fee for 5 AUD',
fee_type_id: '1',
amount: '75',
to: 'seller'
)##Transactions #####Get a list of transactions
transactions = client.transactions.find_all#####Get a transaction
transaction = client.transactions.find('1')#####Get a transaction's users
transaction.users#####Get a transaction's fees
transaction.feesCheck out the online documentation to get a full list of available resources and methods.
#4. Contributing
1. Fork it ( https://github.com/PromisePay/promisepay-ruby/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request