Introduction

The API is written according to the JSON API Specification. We highly recommend using a JSON API Client for consuming this API.

Environment	Endpoint
Sandbox	`https://agent-network-sandbox.bongloy.com`
Production	`https://agent-network.bongloy.com`

Authentication

This API uses JSON Web Token (JWT) Bearer authentication. You must generate a JSON Web Token and include it in the Authorization header for all requests.

Request Signing

All requests require you to sign your JWT according to the RS256 (RSA using SHA-256 hash) algorithm. In production you must generate your own RSA public/private key pair and provide us with your public key. While using the sandbox you can use the sample private key provided with the code samples.

The payload of your JWT must include:

Your API Key
The current unix timestamp (as a string)

{
  "api_token": "[your api token]",
  "timestamp": "1581510124"
}

Generating a RSA public/private key pair

$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
$ openssl rsa -pubout -in private_key.pem -out public_key.pub

Currencies

All API responses return amounts the currency's smallest unit. For example, a 10 USD transaction, would be returned as 1000 (i.e., 1000 cents).

Error Codes

Bongloy uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Bongloy returns an error using the appropriate status code.

In general, there are three status code ranges you can expect:

2xx success status codes confirm that your request worked as expected
4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
5xx error status codes are rare and indicate an error with Bongloy's servers

Some 4xx errors that could be handled programmatically include an error code (a short string with a brief explanation) as a value for code. Below is a list of possible error codes that can be returned.

Code
`validation_error`
`invalid_amount`
`insufficient_balance`
`invalid_transfer`
`expired_transfer`
`destination_account_daily_transfer_limit_exceeded`
`destination_account_not_found`
`destination_account_is_not_active`

Code samples

Code samples for consuming this API can be found here https://gist.github.com/samnang/ad45122a7cdf50d5eebaba355f1126d4.

Organizations

List all Organizations

Request

Endpoint

GET /v1/organizations

GET /v1/organizations

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://agent-network-sandbox.bongloy.com/v1/organizations" -X GET \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJOSUl6MjIzWFpQdng1ZE9CMUlXbWZ2UWQtYUhfaS1abG5QaUE4YjhtNzRnIiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.W0-3x3AxH_KvWK3n4_6vm-zae-G7VbK6j-oDnl8InxcpnNbZ9obQ6hxkHtAGiLN93sy7V8b8wLK55IrAfxANS4FzVgUynz0C6pRPEP6FKNfVHUIqk_9I5ZW3oJd-wFORE3wopl9mrS9CDMAL3xpAdNnGgrQLVBF-jHUxEm6RAOUWsfWxX8FrB_W168TOTluz3YbcYqKowjc4rYOq6K8KzsZNv4OcfQBS1ifMijUXMXJOt7EH1OgAHXH9Bv92prWpbd3Tx7Il-tKCsst9RvYiYl7DauaLJQiU1i15F0FhzMZAsrvSiDzs2ya3AgCmikc0QrlpnwL9FA6uLGQ-vTh4jlSESH5Y12RM6MKhFOO4_aBHswC5MKKPm6xwCSKGWhO-Ysejn7uXk15YvrVJaM4h8cMRWfOmYpfXzcsPuqUIYgFdko1mQiLQqqoYdWUpN3huRF6tV5qE5twD5ocf0V8pUnYEz_p_Mu83vHdRwGRs77KjpbY0cCsfvyuiX7mENdavuZd31QxCroMMKpf7FEgY2dzd0p-da4FqV37YnkXzjs3pwDB-7nyDmnoALH6ci_B6K9YOLkFpdItLbPkYH81-zPDh9A9Ic3JUeVE7qdte5XBXrdyhf6OCpveZipEm_HK_YJ7-_IqGZAHOg6mMPh-0R60iKFuGdOr9-E7Q94kC5Us"

Transfers

Create a Transfer

Request

Endpoint

POST /v1/transfers

POST /v1/transfers

Parameters

{
  "data": {
    "type": "transfer",
    "attributes": {
      "amount": 10000,
      "currency": "USD",
      "destination_account_number": "002002965",
      "metadata": {
        "foobar": "foobar"
      }
    }
  }
}

Name	Description
data[attributes][amount] required	A positive integer representing how much to transfer in the smallest currency unit (e.g., 10000 cents to transfer $100.00). The minimum amount is $1.00
data[attributes][currency] required	The currency of the account. Only `USD` is supported at this time
data[attributes][destination_account_number] required	The destination Bongloy account number
data[attributes][metadata]	Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Response


201 Created

[binary data]

curl "https://agent-network-sandbox.bongloy.com/v1/transfers" -d '{
  "data": {
    "type": "transfer",
    "attributes": {
      "amount": 10000,
      "currency": "USD",
      "destination_account_number": "002002965",
      "metadata": {
        "foobar": "foobar"
      }
    }
  }
}' -X POST \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiIzUjNkSjVRb0hvcEhicWRQYWhmWGRxT0pCZ3d2OG1TOXdnQzhzNHB2SkNFIiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.Rq3PBGBi6J-htsXGvVGpeHL-P5fJzG30cS2BtwKmbZ4WaZc2EjBEloiOJOr3LH2m1c00DHmvkT-xSPbB4N8dkfTCz6TJwtRPJiSGlCRm0V3qIgaqllug2DgwFuI7bG1kapLoEg2kPf_jXEUfoJjSryCyNbUdW9C5gyW84YX7bA6rBMD-7GuKoUIiUVfurMFSt-ZRLwo0tWBNHEWPRfipzP8EuHACMh0H7_wf1pqTg7myM0kZfnM_25tcsu-lhzfpoGHO7Lr8WGQsRDv9cXvPzxP_tvUGaDVnGFRJjVNjYPsL7kJJDdc1H3Dntik7zoaM5DOb7qhax2ESf-k9MZ08xa9LonpoPFAJv-IVr-uORd5Xg6T_exn6aXyMqgmEfsRtMwF_dFw2Zbp7diYLYeDdGiKnuW1QheQrrmNXy7IStD9ru5_y-LOrbX_fNhz7vBv9D0O6jlHOznLttmLLjz1O7rFSJBtevh9paGdSXxYRsWLzEzKuNDxeDL2udgnl4bod3E4Ay-QIQqBfZjaZzarU5utf_c-NssbNaBC3TN6XKf_WuGrPwjOPrSrDdJZI32gjN6dsDRKi3OUMFbSRtikgAgV1IWNnuWn0KqifzoqJTEwVElllJq_FeMZ0GbrWzM4kmZiE733bFvkKpLRS6Rzzy7qWI6XWmn0IRA46lx4x5k8"

Confirm a Transfer

Request

Endpoint

PATCH /v1/transfers/3b668cc8-9fea-4673-ac6a-d7f548ec064b/confirm

PATCH /v1/transfers/:id/confirm

Parameters

{
  "data": {
    "type": "transfer",
    "id": "3b668cc8-9fea-4673-ac6a-d7f548ec064b"
  }
}

None known.

Response


200 OK

[binary data]

curl "https://agent-network-sandbox.bongloy.com/v1/transfers/3b668cc8-9fea-4673-ac6a-d7f548ec064b/confirm" -d '{
  "data": {
    "type": "transfer",
    "id": "3b668cc8-9fea-4673-ac6a-d7f548ec064b"
  }
}' -X PATCH \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiI5alNPUHRlSXkwc0txNTI4NFFPekJXRmh3V0tKUENDRjU4S2FuTTRfRUl3IiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.LkDX9wSRJnF1R807hJWVphrjxLqjsPsU3ZlpB7EVfzB_Gg6rapjreuLt64gT5ZCGNYDSNvyy_SdbQ3iO0qxdKsygH-VbGtcXsRoeDFTrfVRtDi4TORB0F-mHEvtrGFXpsb45LfXVpYFlGm9Iqnm3xK1KyOJ1DfafNC1W6brmZT7osIlMpiUOT7YOhuxRwqdQ5LIb3jeeB4jqvlByZz3-nlQBtrtJtp9-i1V_lATUJ4KkmlOfqu8xTrwvrGh4vBoKpQfsZ2ExCvfeWHGT72Q0xY4k4T8GJVlxIH2HebNUDivOS3aRoqaZDJN4N5Pb3vt_aG8bbDXNN5Ko1orRfwf-u6uAQkhEJhiA2Kw9Rzp_H_JjC4QnknHA0qYexzKC4RyF5WOGKM13tQ1QtcSosyz0yuHnezkBxgxf6V_y4W2eQN_kjjdkT8oll6UjWUGfLqqG7QAc-jG3wz5gcfGFZ7Q-qBbdu9RO1Pu37nE6e1QPEgIvtWi6ZRNjGawBWlyGVCE0elkKdeFJ6ywHiO4MCqReSeiHpxKwdhMaIfzzeF_TkWEsa2_RMFWfPubXExNn-rDi_wLpWq7S1QPOnKGjZABSFUEoX7ZQLezi7z250WRm1deY6FwJx90bHTDaSBOC-zQv7cbsgsUxSfgOcNO5QPHFxPoHCcorWHtZwNuK6b2J55s"

Retrieve a Transfer

Request

Endpoint

GET /v1/transfers/0116c2d4-7f10-4d28-a034-4d87af85b41d

GET /v1/transfers/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://agent-network-sandbox.bongloy.com/v1/transfers/0116c2d4-7f10-4d28-a034-4d87af85b41d" -X GET \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJSUkFPRTRPUEFLT3dWVDVlX3dkQ1dxVWFwVUNqbmlEOXE2Sk9yakVpcW4wIiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.hErycaXwmgyBGZF-AuOVYyxsaTiyDDXyc9Ueb1OIxmwT4s_D_kHbB4gmc2PJwSY49eP7gq537XB3jodAXj6uBciTdwsuCka82pOpun_TYEz_8uu19-ok32NZldnuVLUp9W01HBSR12O1JEKbl2ECkayf1RtDLQv0v1XWruG3E6_HZbETdDhWpTvxqw8PRfYLYkZ2FbL9xj8whSx7GVnMYgcdN_AicGJOv0OhnB0cqo0AADQ89fxZeMShy_DR9tdaOoXMXDlo6l5T8dN0V0TPGkjVj36JUGMMVv9ukV-01lY56700xkHgwobNAmKO7aOsD87M9m4lJfSLep5bdOEcmUak95oxq4LTHSftE3shGNt3-LoRrjfbOckCIB9t3GNDeAiXuiiCD5LgPQs5ZByXMzPeKm5FZHCzvFwAQK-OjgeKnhPDGSwTOV7UrZI37FWJHF2AlbwjFaewdStIfloyy_tHE2oAb18GhtDxy8HO9PTTWPD1M3REbI0znS0sWaXmMoQpBJsZUr_ssyo-JmMeZpRvDO535kVzls0WDdxk4h8BeBNuXVwoOOQbf4WJRJeO01aLC6S34k5SgaqnWZVfFWcxXp53z9Psk7gFCKcfZ89NXrGHEYVMyj2ZrH3yR9hDL63eb17OziV7RJe1my-_PJEdpxW1ufIW2P5gGeA86ZE"

Update a Transfer

Request

Endpoint

PATCH /v1/transfers/79d15845-9925-4b68-8929-ac4f44ed971e

PATCH /v1/transfers/:id

Parameters

{
  "data": {
    "id": "79d15845-9925-4b68-8929-ac4f44ed971e",
    "type": "transfer",
    "attributes": {
      "metadata": {
        "reference_number": "cde456",
        "other_field": "foobar"
      }
    }
  }
}

Name	Description
data[attributes][metadata]	Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Response


200 OK

[binary data]

curl "https://agent-network-sandbox.bongloy.com/v1/transfers/79d15845-9925-4b68-8929-ac4f44ed971e" -d '{
  "data": {
    "id": "79d15845-9925-4b68-8929-ac4f44ed971e",
    "type": "transfer",
    "attributes": {
      "metadata": {
        "reference_number": "cde456",
        "other_field": "foobar"
      }
    }
  }
}' -X PATCH \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiIyQVF4OUt2cno5NUlSYy1jcjRIRklmOE9RLXZQNXdfUUZmWHpiUXVaQ2o0IiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.LZcqGuiXToYl2suGxwjNiCzmLukBSy8ZFBLlqGoEdPUprZlRQlbYHGQam1Ut0nY3154bjZjZyYgG8rHcfNZJqcL1b-NCffnzlHC-xbZLX01OaN8tS7rtUh4pWoT44mPtMsFQnqeqGiM5secNbgQBPlEdu_SLi5zFfmOqI1JmnApuE5LKbvdeIZbba5T9YjwnwqUytLrV7rPq6IdJdbR3YvYn6asefJS8VO8JE8TcqL2NhamL9ltsc36BXdk3TYlJ_GD_plXlsjZXZBPjqxSLC1p8XB4KkTzY7Yq3uOQYmuyVD1vbOkHW4QH6pbCS1MuDhCsJfbq6d_gpNoVBI3NtGpkNWA_-AC3wz2NPj3pCP6LmYSYNaXipYvYSSLh0BoY8D6Gk5J_rPaO0yb6jXWIVjNHiobu5BfEkuCa2i4O3a_cCPgrgV5jB9xcc6Eeo1H1ZEyy1Xql-pddJNyrDHMzpJFe0ZZ-ctqwE8UyMrw_JAm-ccZPyxfe9wq-1kj7fSMMWeraAKIoeC-0UUWadoB0eMdh6tKHFz4PKk33-_G7FaMeWZ9wOqUvqfrbWPO9I3PIkaEE0athTH6szjCjagSKNp_Ch8wSag8Fgqd4QNOCi_cWV_Sc1F8Mus6oW4P12rr9284pYhqcqZZ6lNiGbk4-0xGvQRdUXAQ4YWyYt9b3K814"

List all Transfers

Request

Endpoint

GET /v1/transfers?filter[status]=successful&amp;filter[from_date]=2020-01-01T00%3A00%3A00Z&amp;filter[to_date]=2020-01-01T11%3A00%3A00Z

GET /v1/transfers

Parameters

filter: {&quot;status&quot;=&gt;&quot;successful&quot;, &quot;from_date&quot;=&gt;&quot;2020-01-01T00:00:00Z&quot;, &quot;to_date&quot;=&gt;&quot;2020-01-01T11:00:00Z&quot;}

Name	Description
filter[status]	Return transfers that match the provided status.
filter[from_date]	Return transfers on or after the provided date/time in ISO 8601 format.
filter[to_date]	Return transfers on or before the provided date/time in ISO 8601 format.

Response


200 OK

[binary data]

curl -g "https://agent-network-sandbox.bongloy.com/v1/transfers?filter[status]=successful&filter[from_date]=2020-01-01T00%3A00%3A00Z&filter[to_date]=2020-01-01T11%3A00%3A00Z" -X GET \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJWT1FzU1pidVhueU1ZeVk1RWs1aEZLVnVEcXZ2VkFvcjRCZV9Ndk8wNnB3IiwidGltZXN0YW1wIjoiMTYzODM0MTI5NCJ9.LE1nXhdljlt6wMJr0-V97A7_EGDbnPAsze9nxTfzLqVwa2wtycAlBH8EZ3eSxob23g88cUps3K3d_AG4eHfvck-icnu58PsIxh2kMt0j9wQPZh3fk4TG7Sw3R-V9W4BQi41CYj-dwvONJrSdurY0fGN4mQyDHowYjbOtdzldKUis35l5tkftWG9KMDOQk8wMA9pTEiI8qFFYWpy2k0LAqZ2JWEtaBWeqoM-zmWdgkTTth8NAM2bT6gykfTo-dA-Yav7N-m6yW4Jny9kiQTpqHM7t5hxVJnWzjnogl_Y6ZjGanI5tq0QlyDgnRkWTpzdhgaPJ1IQtWNpXlynY7aUJhcC457rVMd3sRYqT8IJXuQQhNwiDLSMCvCWhVWuY1aM227I7PZXH_-BINFIi8ttg8wdTVkSH4FYVqc8Qm2rbW8NQEoHG0FoV3gB8P1KFhk21VS1HPXKmjInNgDCu3V3arjh4_hX2ZJBSPoiNNsoaQsC0gVIMWSdWXiSTYPwj7k2CC8XksrXM6kO_TK3QgdIc7amw-LBT49lojRe0XPYc__fCgaM8rod2jMgPU17cLTfF1l_iHmWJM_6WEDgLwsF_oCuLSel-CW8IlTwON5giG-d2d0tNqn3Eunm56DiuYQa-DeBoRNK3d2c1MQ_ZlvPT2lPI4emimxpSvArSOdyiRpM"