BloomRemit Ruby Library

CircleCI

Ruby wrapper for BloomRemit's API

Installation

Add this line to your application's Gemfile:

gem 'bloom_remit2'

And then execute:

bundle install

Or install it yourself as:

gem install bloom_remit2

Usage

In an initializer:

BloomRemit2.configure do |c|
  c.api_token = 'BLOOM-REMIT-API-TOKEN'
  c.api_secret_key = 'BLOOM-REMIT-API-SECRET-KEY'
end

Partners

Shows partner details

# GET /api/v1/partners/:api_token

BloomRemit2::Partner.retrieve

Agents

Show a list of agents belonging to this partner

# GET /api/v1/partners/:api_token/agents
# Return a list of agents created by this partner, sorted by newest first.

BloomRemit2::Agent.list

Show an agent belonging to this partner

# GET /api/v1/partners/:api_token/:agents/:id

BloomRemit2::Agent.retrieve('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')

Create a new agent under this partner

# POST /api/v1/partners/:api_token/agents

BloomRemit2::Agent.create('Seoul Branch')

Update the attributes of an agent belonging to this partner

TODO: Needs to be implemented; update doesn't work at the moment

# PUT /api/v1/partners/:api_token/agents/:id

agent_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
BloomRemit2::Agent.update(
  agent_id,
  name: 'Incheon Branch'
)

Delete an agent belonging to this partner

# DELETE /api/v1/partners/:api_token/agents/:id

agent_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Agent.delete(agent_id)

Credits

Retrieve a credit address

TODO: Needs to be implemented; this returns a 500 Internal Server Error

# GET /api/v1/partners/:api_token/credits

BloomRemit2::Credit.list

Show a list of credit transactions

# GET /api/v1/partners/:api_token/credits/history

BloomRemit2::Credit.history

Rates

Returns a real-time hash of currency exchange rates. Updates every minute

# GET /api/v1/rates

BloomRemit2::Rate.list
=> fetches all the rates

BloomRemit2::Rate.retrieve('USDPHP')
=> fetches one rate

The rate returned is defined as:

  • The rate that Bloom purchases the base currency (USD) for the counter currency (PHP)
  • The rate that a BloomRemit partner can sell the base currency (USD) for the counter currency (PHP)
  • The amount of PHP (counter currency) that a BloomRemit partner receives from Bloom by exchanging 1 USD (base currency)

Recipients

Create a new recipient for a sender belonging to this partner

# POST /api/v1/partners/:api_token/recipients

BloomRemit2::Recipient.create(
  sender_id,
  {
    first_name: 'Luis',
    last_name: 'Buenaventura',
    email: '[email protected]',
    mobile: '639171234567',
    address: '251 Salcedo St., Legaspi Village',
    city: 'Makati City',
    province: 'Metro Manila',
    country: 'PH'
  }
)

List all recipients for a user belonging to this partner

# GET /api/v1/partners/:api_token/senders/:sender_id/recipients

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Recipient.list(sender_id)

Show details about a recipient of a given user, and their associated remittance IDs

# GET /api/v1/partners/:api_token/senders/:sender_id/recipients/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
recipient_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Recipient.retrieve(sender_id, recipient_id)

Update the attributes of a recipient of a user belonging to this partner

# PUT /api/v1/partners/:api_token/senders/:sender_id/recipients/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
recipient_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Recipient.update(
  sender_id,
  recipient_id,
  {
    first_name: 'Luis',
    last_name: 'Buenaventura',
    email: '[email protected]',
    mobile: '639171234567',
    address: '251 Salcedo St., Legaspi Village',
    city: 'Makati City',
    province: 'Metro Manila',
    country: 'PH'
  }
)

Delete recipient record of a user belonging to this partner safely

# DELETE /api/v1/partners/:api_token/senders/:sender_id/recipients/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
recipient_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Recipient.delete(sender_id, recipient_id)

Remittances

Show all remittances belonging to the given user

# GET /api/v1/partners/:api_token/senders/:sender_id/remittances

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Remittance.list(sender_id)

Initiate a new money transfer by providing a recipient_id and a remittance hash

Use either paid_in_orig_currency or receivable_in_dest_currency and not both as this will result in a 500 Internal Server error.

# POST /api/v1/partners/:api_token/senders/:sender_id/remittances

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
recipient_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Remittance.execute(
  sender_id,
  {
    recipient_id: 1,
    remittance: {
      account_name: 'Luis Buenaventura',
      account_number: '1234567890',
      dest_currency: 'PHP',
      flat_fee_in_orig_currency: 0,
      forex_margin: 0,
      orig_currency: 'PHP',
      # paid_in_orig_currency: 0,
      payout_method: 'BPI',
      receivable_in_dest_currency: 25000
    }
  }
)
=> remittance hash, not a BloomRemit2::Remittance

Show information about a given recipient along with their associated remittance

# GET /api/v1/partners/:api_token/senders/:sender_id/remittances/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
remittance_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Remittance.retrieve(sender_id, remittance_id)

Cancel a remittance

TODO: Need to add tests

Note that this change the status of the remittance to 'cancelled' and refunds the partner credits used, but does not delete it from the database

# DELETE /api/v1/partners/:api_token/senders/:sender_id/remittances/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
remittance_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Remittance.cancel(sender_id, remittance_id)
=> remittance_hash, not a BloomRemit2::Remittance

Sender uploads

TODO: Needs to be implemented

Senders

Show a list of senders belonging to this partner

Returns a list of senders created by this partner, sorted by newest first

# GET /api/v1/partners/:api_token/senders

BloomRemit2::Sender.list

Show a sender belonging to this partner

# GET /api/v1/partners/:api_token/senders/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Sender.retrieve(sender_id)

Show a sender belonging to this partner by supplying their email address

# GET /api/v1/partners/:api_token/senders/find_by_email

BloomRemit2::Sender.find_by_email('[email protected]')

Show a sender belonging to this partner by supplying their mobile

TODO: Needs to be implemented

# GET /api/v1/partners/:api_token/senders/find_by_mobile

BloomRemit2::Sender.find_by_mobile('639171234567')

Create a new sender under this partner

# POST /api/v1/partners/:api_token/senders

BloomRemit2::Sender.create({
  agent_id: '12345-54321',
  sender: {
    first_name: "Luis",
    last_name: "Buenaventura",
    email: "[email protected]",
    mobile: "+639175551111",
    address: "251 Salcedo St., Legaspi Village",
    city: "Makati City",
    country: "PH"
  }
})

Update the attributes of a sender belonging to this partner

# PUT /api/v1/partners/:api_token/senders/:id

BloomRemit2::Sender.update(
  sender_id,
  {
    first_name: 'Luis',
    last_name: 'Buenaventura',
    mobile: "+639175551111",
    address: "251 Salcedo St., Legaspi Village",
    city: "Makati City",
    country: "PH",
    postal_code: "1600",
    identification: {
      url: "http://aws.amazon.com/bucket/image.jpg"
    }
  }
)

Delete a sender belonging to this partner

# DELETE /api/v1/partners/:api_token/senders/:id

sender_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
BloomRemit2::Sender.delete(sender_id)

Static

Lists remittance strategies

TODO: Needs to be implemented

# GET /api/v1/strategies

BloomRemit2::RemittanceStrategy.list

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also 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, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/makisu/bloom_remit2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the BloomRemit2 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.