/promisepay-ruby

Ruby gem for invoking PromisePay RESTful API

Primary LanguageRubyMIT LicenseMIT

Ruby SDK - PromisePay API

Join the chat at https://gitter.im/PromisePay/promisepay-ruby

Gem Version Build Status Coverage Status Code Climate

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 ||= y0urt0k3n12345678910123456789101

The 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

Example 1 - Request session token

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.transactions

#####Get an item's batch transactions

item.batch_transactions

#####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 wallet account

user.wallet_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'
)

#####Decline refund

item.decline_refund

#####Refund

item.refund(
  refund_amount: '1000',
  refund_message: 'because'
)

#####Raise dispute

item.raise_dispute(user_id: '5830def0-ffe8-11e5-86aa-5e5517507c66')

#####Request resolve dispute

item.request_resolve_dispute

#####Resolve dispute

item.resolve_dispute

#####Escalate dispute

item.escalate_dispute

#####Send tax invoice

item.send_tax_invoice

#####Request tax invoice

item.request_tax_invoice

##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

##Wallet Accounts #####Get a Wallet account

wallet_account = client.wallet_accounts.find('1')

#####Deposit funds

wallet_account.deposit(
  account_id: '123',
  amount: 500
)

#####Withdraw funds

wallet_account.withdraw(
  account_id: '123',
  amount: 200
)

#####Get a Wallet account's users

wallet_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.fees

##Batch Transactions #####Get a list of batch transactions

batch_transactions = client.batch_transactions.find_all

#####Get a transaction

batch_transaction = client.batch_transactions.find('1')

##Charges #####Get a list of charges

charges = client.charges.find_all

#####Get a charge

charge = client.charges.find('1')

#####Create a charge

charge = client.charges.create(
  account_id: '123',
  user_id: '456',
  name: 'Charge for Delivery',
  email: 'anonymous+buyer+1@promisepay.com',
  amount: 4_500,
  zip: '3000',
  curency: 'AUD',
  country: 'AUS',
  retain_account: true,
  device_id: '0900JapG4txqVP4Nf...',
  ip_address: '172.16.81.100'
)

#####Get a charge's buyer

charge.buyer

#####Get a charge's status

charge.status

##Direct Debit Authority #####Get a list of direct debit authorities for a given account

bank_account = client.bank_accounts.find('9fda18e7-b1d3-4a83-830d-0cef0f62cd25')
ddas = client.charges.find_all(bank_account.id)

#####Get a direct debit authority

dda = client.direct_debit_authorities.find('8f233e04-ffaa-4c9d-adf9-244853848e21')

#####Create a direct debit authority

charge = client.direct_debit_authorities.create(
  account_id: '9fda18e7-b1d3-4a83-830d-0cef0f62cd25',
  amount: '10000'
)

#####Delete a direct debit authority

dda = client.direct_debit_authorities.find('8f233e04-ffaa-4c9d-adf9-244853848e21')
dda.delete

##Tools #####Health check

client.tools.health_check

##Marketplace

client.marketplace

##Token #####Generate

client.generate_token(token_type: 'card', user_id: '5830def0-ffe8-11e5-86aa-5e5517507c66')

Check 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