GET /api/v1/partners/:api_token/senders/:sender_id/remittances
Returns a hash with a single key remittance_ids
, containing an array of integers corresponding to the IDs of the remittance records belonging to the specified user.
Sample URL:
https://www.bloomremit.net/api/v1/partners/:api_token/senders/9831bc1f-e531-47d0-bc00-db32dbe875d7/remittances?api_secret=:api_secret
POST /api/v1/partners/:api_token/senders/:sender_id/remittances
json
404 - Couldn't find a recipient record with that ID
422 - Request was correctly parsed but there is missing information
# Example URL http://www.bloomremit.net/api/v1/partners/:api_token/senders/1/remittances?api_secret=:api_secret
# Example bank remittance { "api_secret": "cKaBK3rKuzfsyaQt9spJmEu4", "agent_id": 1, "recipient_id" : 1, "remittance" : { "account_name": "Luis Buenaventura", "account_number": "1234567890", "callback_url": "http://yourwebsite.com/remittances/1/callback_for_bloom", "dest_currency": "PHP", "flat_fee_in_orig_currency": 3000, "forex_margin": 0.5, "orig_currency": "KRW", "paid_in_orig_currency": 15000, "payout_method": "BPI", "receivable_in_dest_currency": 500 } } # Some destinations require more information, like Vietnamese banks: { "api_secret": "cKaBK3rKuzfsyaQt9spJmEu4", "agent_id": 1, "recipient_id" : 1, "remittance" : { # same as above, plus: "account_branch_address": "23 Nguyen, HCM", "account_branch_name": "Bank of HCM, Nguyen-HCM" } }
# Example cash pickup remittance { "api_secret": "cKaBK3rKuzfsyaQt9spJmEu4", "agent_id": 1, "recipient_id": 1, "remittance": { "amount": 10000.0, "callback_url": "http://yourwebsite.com/remittances/1/callback_for_bloom", "currency": "PHP", "payout_method": "CLH", "strategy": "pickup" } }
# Example payload for the `callback_url` { "remittance": { "id": 100, "partner_id": 1, "recipient_id": 1, "orig_currency": "KRW", "dest_currency": "PHP", "paid_in_orig_currency": 30000, "receivable_in_dest_currency": 500, "forex_margin": 1.0, "flat_fee_in_orig_currency": 2000, "payout_method": "BDO", "status": "error", "status_description": "Transaction error", "teller_id": 2 } }
# Example 200 (successful) response for bank deposit { "remittance": { "id": "fa672cc7-6006-46e6-9e64-14ac412cb2a4", "teller_id": "c2002ad1-7618-4592-b868-409ab209fdcf", "recipient_id": "4ae1f668-3b00-40ff-81b6-284660083b45", "orig_currency": "KRW", "dest_currency": "PHP", "paid_in_orig_currency": 15000.0, "receivable_in_dest_currency": 500.0, "status": "incomplete", "payout_method": "CBC", "partner_id": "049902b7-f09e-4675-a835-76df30017b94", "flat_fee_in_orig_currency": 3000.0, "forex_margin": 0.0, "account_name": "Luis Buenaventura", "account_number": "1234567890", "callback_url": "http://yourwebsite.com/remittances/1/callback_for_bloom", "sender_id": "d96f181e-d106-410d-86e0-2c91306dc97f" } }
# Example 200 (successful) response for cash pickup { "remittance": { "id": "fa672cc7-6006-46e6-9e64-14ac412cb2a4", "teller_id": "c2002ad1-7618-4592-b868-409ab209fdcf", "recipient_id": "4ae1f668-3b00-40ff-81b6-284660083b45", "orig_currency": "KRW", "dest_currency": "PHP", "paid_in_orig_currency": 15000.0, "receivable_in_dest_currency": 500.0, "status": "incomplete", "payout_method": "CBC", "partner_id": "049902b7-f09e-4675-a835-76df30017b94", "flat_fee_in_orig_currency": 3000.0, "forex_margin": 0.0, "tracking_sender": "Luis Buenaventura", "tracking_number": "BLMHUMAWAYA", "callback_url": "http://yourwebsite.com/remittances/1/callback_for_bloom", "sender_id": "d96f181e-d106-410d-86e0-2c91306dc97f" } }
# Example 422 (error) response when the bank account number is wrong { "errors": [ "Account number is invalid. The number must be 10-12 digits long with no spaces." ] }
Name | Type | Description |
---|---|---|
recipient_id required | Value:
Must be a String |
Recipient ID |
agent_id required | Value:
Must be a String |
Agent ID |
remittance required | Value:
Must be a Hash |
Remittance instructions |
remittance[orig_currency] required | Value:
Must be one of: |
Currency of Origin (Ex. ‘USD’, ‘KRW’) |
remittance[paid_in_orig_currency] optional | Value:
Must be a Float |
Amount paid by customer (Ex. 20000.0). Must be filled if ‘receivable_in_dest_currency’ is not set. If both are set, then this amount is disregarded. |
remittance[flat_fee_in_orig_currency] optional | Value:
Must be a Float |
Flat service fee that you wish to add to the total bill of your sender. Leave this blank to use your default fee (if any). |
remittance[forex_margin] optional | Value:
Must be a Float |
Additional foreign-exchange percentage to add to the total bill of your sender. Leave this blank to use your default margin (if any). |
remittance[dest_currency] required | Value:
Must be one of: |
Currency of Destination |
remittance[receivable_in_dest_currency] optional | Value:
Must be a Float |
Amount received by recipient (Ex. 1000.00). Must be filled if ‘paid_in_orig_currency’ is not set. If both are set, then this amount is used to calculate and override ‘paid_in_orig_currency’. |
remittance[payout_method] required | Value:
Must be one of: |
Remittance strategy slug |
remittance[account_name] optional | Value:
Must be a String |
Full Name of Bank Account Holder |
remittance[account_number] optional | Value:
Must be a String |
Bank Account Number |
remittance[callback_url] optional | Value:
Must be a String |
URL to post updates to when the status of a remittance changes. Please respond with a HTTP Code 200 and the word ‘ok’. If you have a Callback URL already defined in the Partner Settings, this is unnecessary. |
GET /api/v1/partners/:api_token/senders/:sender_id/remittances/:id
All information about the given remittance and recipient are returned with this call. Important fields to note include status
and receivable_in_dest_currency
.
Status changes from its initial value of incomplete
to paid
when we have confirmed that the partner has sufficient remaining credit to cover the cost of the remittance. It changes to completed
when we have handed off the local currency to the chosen payout partner, and sometimes changes to waiting
when the payout partner has not responded with a success notification yet. This typically happens when the remittance is made outside of banking hours or on holidays, during which the forwarding of a given transaction will take longer than normal.
Partners using the API can also trigger a change of status to cancelled
by using the /delete method. This safely removes the transaction from our processing queue.
Lastly, it could be rejected
if we detect abuse or are otherwise unable to complete the remittance.
With every status change, we will POST an updated JSON object of the remittance record to your provided callback_url
, if any.
Statuses can be one of the following: bank_error
, incomplete
, paid
, completed
, rejected
, refunded
, cancelled
, error
, delayed
, waiting
, unpaid
, and outstanding
.
Example JSON Response: { recipient: { id: 3, first_name: "Johnny", last_name: "Bravo", email: "johnny@bravo.ph", mobile: "0639175551111", address: null, city: "Makati City", province: "Metro Manila", postal_code: null, created_at: "2015-06-07T19:59:02.602+08:00", updated_at: "2015-06-07T19:59:02.602+08:00" }, remittance: { id: "728f77fd-30fb-49e0-98ec-1a9872e8db44", sender_id: "9831bc1f-e531-47d0-bc00-db32dbe875d7", recipient_id: "25a0cd10-b8af-4792-9b8f-5b40a7174cf1", destination_currency: "PHP", amount: 35000, service_fee: 450, status: 'paid', created_at: "2015-06-07T20:12:07.756+08:00", updated_at: "2015-06-07T20:12:07.756+08:00", tracking_number: "BLMKAMLUWAH", settled_at: null, payout_method: "CLH", } }
Name | Type | Description |
---|---|---|
id required | Value:
Must be a String |
Remittance ID (Integer > 0) |
DELETE /api/v1/partners/:api_token/senders/:sender_id/remittances/:id
Cancel a remittance. We never delete records so you will still be able to retrieve any cancelled remittances. Internally, we set the status to cancelled
. You can cancel remittances that are in the waiting
, paid
, delayed
, error
, outstanding
, and unpaid
.
Name | Type | Description |
---|---|---|
id required | Value:
Must be a String |
Remittance ID (UUID) |
POST /api/v1/partners/:api_token/remittances/calculate
In order to calculate the cost of a given remittance, you will need to provide an amount, a currency, and a payout_method. You may provide either the origin_amount (the money paid by the sender), or the destination_amount
(the money received by the beneficiary), and the calculator will compute the fees automatically.
If you provide the origin_amount
, the calculator will give you the amount receivable at the destination of the remittance. If you provide the destination_amount
, the calculator will give you the amount that must be paid by the sender at the point of origin.
{ origin_amount: 15000, origin_currency: 'KRW', payout_method: "CLH" }
{ destination_amount: 10000, destination_currency: 'PHP', payout_method: "CLH" }
{ origin_amount: 125000, payout_method: "CLH" }
Name | Type | Description |
---|---|---|
origin_amount optional | Value:
Must be a String |
Amount payable at origin |
origin_currency optional | Value:
Must be a String |
Currency of origin (If blank, will use partner’s default origin currency) |
destination_amount optional | Value:
Must be a String |
Amount receivable at destination |
destination_currency optional | Value:
Must be a String |
Currency of destination (If blank, will use partner’s default destination currency) |
payout_method required | Value:
Must be one of: |
Remittance provider slug |