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_secretPOST /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",
"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,
"currency": "PHP",
"payout_method": "CLH",
"strategy": "pickup"
}
}
# Instead of using callback_url, you are encouraged to use get updates on
# the transactions by make the following POST call:
curl -X GET 'https://www.bloomremit.net/message-bus/x/poll?dlp=t' -H 'Authorization: Basic MTox' -d %2Ftx_events=-50
# `MTox` is your partner_id:partner_api_secret in base64 without newlines
# or spaces
#
# `%2Ftx_events` or `/tx_events` is set to -50 in the example, and this will
# return the last 49 events.
# You may use https://github.com/SamSaffron/message_bus if you're in Ruby,
# JS, or if you want to learn more.
# Here's an example reply:
[
{
"global_id": 68510299,
"message_id": 10385646,
"channel": "/exchange_rates",
"data": {
"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",
# if tracking_number is known, we show it. If not known yet this will be blank. You may poll the update channel (message bus) for the tracking_number.
"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 a String |
Remittance strategy, must be listed in https://www.bloomremit.net/developers/1/static |
| 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[client_external_id] optional | Value:
Must be a String |
Unique code you want to refer to this transaction; this can only be submitted once. If not given, one will be generated for you, but it is strongly recommended that you generate it yourself to avoid accidentally processing multiple transactions. |
| remittance[callback_url] optional | Value:
Must be a String |
[DEPRECATED] Subscribe to |
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. When this endpoint is triggered, the transaction will first go into the cancelling state. It will only become cancelled when we have confirmed that it has been safely removed 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: Bank failure, please contact supportincomplete: No payment was receivedpaid: We’re processing this transactioncompleted: This transaction is completerejected: This transaction could not be processedrefunded: This transaction has been refundedcancelled: This transaction has been cancelledcancelling: This transaction is being cancelledcancelling_unpaid: This transaction is being cancellederror: General failure, please contact supportdelayed: This transaction is delayed and will be processed manuallywaiting: We’re waiting for confirmation from the payout partnerunpaid: This transaction has not yet been processed due to insufficient balanceoutstanding: Transaction is waiting to be claimed by the recipient (only used in cash-pickup transactions)disbursing: We’re waiting for confirmation from the payout partnerNote: we are working to simplify the statuses shown to partners. In a future version of this API endpoint, the statuses will be reduced to about four (4).
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 cancelling and then cancelled once we have confirmed that it is safe to cancel. You can cancel remittances that are in the statuses waiting, paid, delayed, error, and outstanding.
| 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 |