Ruby SDK - PromisePay API

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: '[email protected]',
  buyer_email: '[email protected]',
  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: '[email protected]',
  buyer_email: '[email protected]',
  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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]'
)

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: '[email protected]',
  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

Fork it ( https://github.com/PromisePay/promisepay-ruby/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request