API Documentation

Remittances

Show all remittances belonging to the given user

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

Headers

Header name Description
X-API-SECRET
required 		API secret of your organization

Initiate a new money transfer by providing a recipient_id and a remittance hash. (VENDOR partner version)

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

Supported Formats

json

Errors

404 - Couldn't find a recipient record with that ID
422 - Request was correctly parsed but there is missing information

Examples

# Example URL

http://www.bloomremit.net/api/v1/partners/:api_token/senders/1/remittances

# Example bank remittance

{
  "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:
{
  "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

{
  "recipient_id": 1,
  "remittance": {
    "receivable_in_dest_currency": 10000.0,
    "dest_currency": "PHP",
    "payout_method": "CLH"
  }
}

# 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": "waiting",
    "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",
    "purpose": "Salary",
    "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": "waiting",
    "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."
  ]
}

Request Parameters

NameTypeDescription
recipient_id
required		Value:

Must be a String

Recipient ID

remittance
required		Value:

Must be a Hash

Remittance instructions

remittance[orig_currency]
optional		Value:

Must be one of: ADA, AED, AUD, AXS, BCH, BNB, BUSD, CAD, CNY, DASH, EUR, GBP, HKD, IDR, INR, JPY, KRW, LINK, MYR, NEAR, NPR, PAX, PHP, SGD, SLP, THB, USD, USDC, USDT, VND, ZAR.

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: ADA, AED, AUD, AXS, BCH, BNB, BUSD, CAD, CNY, DASH, EUR, GBP, HKD, IDR, INR, JPY, KRW, LINK, MYR, NEAR, NPR, PAX, PHP, SGD, SLP, THB, USD, USDC, USDT, VND, ZAR.

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

Where this remittance will be deposited. 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[recipient_first_name]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precedence over the given recipient_id

remittance[recipient_last_name]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_email]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_mobile]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_address]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_city]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_state]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_zip_code]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_country]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_occupation]
optional		Value:

Must be a String

Recommended way to set recipient information. This will take precendence over what is found in recipient_id

remittance[recipient_relationship_to_sender]
optional		Value:

Must be a String

remittance[sender_first_name]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_last_name]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_email]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_mobile]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_address]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_city]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_state]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_zip_code]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_country]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[sender_occupation]
optional		Value:

Must be a String

Recommended way to set sender information. This will take precendence over what is found in sender_id

remittance[purpose]
optional		Value:

Must be a String

Reason for remittance

remittance[callback_url]
optional		Value:

Must be a String

[DEPRECATED] Subscribe to /tx_events instead

Headers

Header name Description
X-API-SECRET
required 		API secret of your organization

Show information about a given recipient along with their associated remittance. (VENDOR partner version)

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.

Statuses can be one of the following:

  • waiting: We’re waiting for confirmation from the payout partner
  • error: General failure, please contact support
  • cancelling: This transaction is being cancelled
  • outstanding: Transaction is waiting to be claimed by the recipient (only used in cash-pickup transactions)
  • cancelled: This transaction has been cancelled
  • completed: This transaction is complete

Examples

{
  "recipient": {
    "id": "client-ref-id",
    "first_name": "Johnny",
    "last_name": "Bravo",
    "email": "johnny@bravo.ph",
    "mobile": "0639175551112",
    "city": "Makati City",
    "state": "Metro Manila",
    "created_at": "2024-04-20 23:33:18 +0800",
    "updated_at": "2024-04-21 01:31:18 +0800"
  },
  "remittance": {
    "id": "07f7d6e8-138e-4ccf-bb5c-0c7b57c8b77a",
    "partner_id": "bac48570-5c4c-4a93-903a-e1c20428d040",
    "recipient_id": "client-ref-id",
    "receivable_in_dest_currency": 35000,
    "payout_method": "CLH",
    "status": "waiting",
    "tracking_number": "BLMKAMLUWAH",
    "sender_id": "9f8260b0-0714-44ae-bcae-86b6f3cc70fd",
    "client_external_id": "client-external-id"
  }
}

Request Parameters

NameTypeDescription
id
required		Value:

Must be a String

Remittance ID

Headers

Header name Description
X-API-SECRET
required 		API secret of your organization

Cancel a remittance. Note that this changes 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

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.

Request Parameters

NameTypeDescription
id
required		Value:

Must be a String

Remittance ID (UUID)

Headers

Header name Description
X-API-SECRET
required 		API secret of your organization

Returns the total fees for a given remittance amount and payout method.

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.

Examples

{
  origin_amount: 15000,
  origin_currency: 'KRW',
  payout_method: "CLH"
}

{
  destination_amount: 10000,
  destination_currency: 'PHP',
  payout_method: "CLH"
}

{
  origin_amount: 125000,
  payout_method: "CLH"
}

Request Parameters

NameTypeDescription
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 a String

Where this remittance will be deposited. Must be listed in https://www.bloomremit.net/developers/1/static

Headers

Header name Description
X-API-SECRET
required 		API secret of your organization