Installation

Add this line to your application's Gemfile:

gem 'payoneer-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install payoneer-ruby

Configuration

# Configuration
Payoneer.configure do |c|
  c.environment = 'production'
  c.partner_id = '<payoneer_account_id>'
  c.client_id = '<client_id>'
  c.password, = '<password>'
  c.auth_storage = CustomStorage # See example implementation below
end

Tokens

There are two kinds of token in Payoneer API: application token and access token.

Application Token

This kind of token is used for some non-critical program scope operation that does not require user consent (registration link, payee status, mass payout...) Obtention and renewal are handled automatically by this gem. You should provide a custom centralized storage class to reuse a valid token. If you don't provide such a class, the application token will be cached by the gem as a class instance variable, but it's not efficient at all.

Example:

# Application token stuff done by the gem
Payoneer::Payee.new('payee_id').status

Access Token

Access token are required for some critical account scope operations and require user consent (Charge a payee, get a charge status...). It's your responsibility to store/renew those tokens at application level.

Example:

# Request a token
code = '<code obtained after user content redirect>'
redirect_url = '...' # should be the same you gave in consent url (and should be whitelisted by payoneer)
response = Payoneer::Client::Auth.new.access_token(code, redirect_url)
access_token = response[:access_token]

# Then store the token (DB, cache...) and monitor expiration unless you want to ask a new user's consent!
# ...

# Use the token
access_token = '...'
account_id = '...'
Payoneer::Account.new(account_id, access_token).balances

Custom storage implementation

It's very important to provide a custom, centralized application token storage implementation. Default Gem's storage is intended only for testing purposes.

class CustomStorage
  REDIS_KEY = 't4b-payoneer-auth-storage-key'

  def get
    MyApp.redis.get(REDIS_KEY)
  end

  def set(token)
    MyApp.redis.set(REDIS_KEY, token)
  end
end

APIs

All APIs responses are ruby Hash with key as symbols. If the response's status is not 200, a PayoneerError subclass is raised.

Payee

# Get Payee Registration link
payee = Payoneer::Payee.new('payee_1')

# Registration only
payee.registration_link(redirect_url: 'https://myapp.com/payoneer/register')

# Registration with user consent (for user Access Token request)
payee.registration_link(redirect_url: 'https://myapp.com/payoneer/register-consent',
                        with_consent: true,
                        state: '<your_radom_gen_state>')
# =>
# {
#   token: "7293f06a1d52..4e6f80af0f414b0f0962010B7745A",
#   registration_link: "https://payouts.sandbox.payoneer.com/partners/lp.aspx?token=7293f06a1d52..4e6f80af0f414b0f0962010B7745A"
# }

# Get Payee Status
payee = Payoneer::Payee.new('payee_1')
payee.status
# =>
# {
#   account_id: "3676945",
#   status: {
#     type: 1,
#     description: "Active"
#   },
#   registration_date: "2021-05-05",
#   payout_method: {
#     type: "BANK"
#   }
# }

Account

# Get payee USD balance
account_id = '5720096' # from payee.status
account = Payoneer::Account.new(account_id, access_token)
balances = account.balances.dig(:balances, :items)
balance = balances.find do |b|
  b[:currency] == 'USD'
end
balance[:id]
#=> '4366181904998956'

Payment

# Charge a payee
account_id = '5720096' # from payee.status
balance_id = '4366181904998956' # from account.balances
ref_id = SecureRandom.hex
payment = Payoneer::Payment.new(account_id, access_token)
payment.charge(balance_id: balance_id,
              currency: 'USD',
              ref_id: ref_id,
              amount: 42,
              description: "Test charge #{Time.current}")

# Commit a charge
commit_id = '23576bab-a37a-4f52-8f52-78a3f48ba6aa' # from payment.charge
payment.commit(commit_id)

# Get a charge Status
payment.status(ref_id)

Mass Payout

# Submit a mass payout
# https://developer.payoneer.com/docs/mass-payouts-and-services.html#/61c69e5c3e131-submit-mass-payout
params = {
  payments: [
    {
      client_reference_id: "payment_1",
      payee_id: "[email protected]",
      description: "Test_1256g1",
      currency: "USD",
      amount: "150"
    },
    {
      client_reference_id: "payment_2",
      payee_id: "[email protected]",
      description: "Test_1258g2",
      currency: "USD",
      amount: "100"
    }
  ]
}
payout = Payoneer::Payout.new
payout.create(params)

# Payout Status
payout.status('payment_2')

# Cancel a Payout
payout.cancel('payment_2')

Development

After checking out the repo, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Docker

Build Image:

docker build -t payoneer .

Run spec:

docker run -it payoneer rspec spec

Launch guard

docker run -v ${PWD}:/home/app -it payoneer guard

Contributing

1. Fork it ( https://github.com/[my-github-username]/payoneer-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