NAV Navbar
Shell

Introduction

Base URL

https://api.pay.bleumi.com/v1

Welcome to the Bleumi Pay API, a simple and powerful REST API to integrate ERC-20, Ethereum & xDai Payments and/or Payouts into your business or application.

Client Libraries

By default, the Bleumi Pay API Documentation provides examples in curl to interact with the API. Examples for supported languages are provided as part of their respective SDK.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "x-api-key: <Your API Key>"

Make sure to replace <Your API Key> with your actual API key.

Bleumi Pay uses API keys to authenticate requests. You can view and manage your API keys in the Bleumi Pay Dashboard.

Authenticated API requests should be made with a x-api-key header. Your API key should be passed as the value.

Payments

Create a Payment

curl "https://api.pay.bleumi.com/v1/payment?chain=ropsten"
  --H "Content-Type: application/json"
  --H "x-api-key: <key>"
  --X POST
  --data '
{
    "id": "1",
    "buyerAddress": "0xD15BDD17175825742A5904b21008dd3A019a060E",
    "transferAddress": "0x7Dc30B85084aA1608e5C1Ce39c804Be177e40A07"
}
'

The above command returns JSON structured like this:

{
  "addr": "0xbea2f9d56c3cc7f2c7e17d294200dd75708eecd8"
}

This endpoint generates a unique wallet address in the specified network to accept payment. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment?chain={chain}

Query Parameters

Parameter Type Description
chain string Network in which the wallet is to be created. Please refer to the Supported Networks.

Request

Field Type Description
id string Unique identifier for this payment
buyerAddress string Address of buyer. Refund operations on this wallet will use this address.
You can set this to your address to manually handle refunds (outside of Bleumi Pay) to your buyer.
Warning! - This address must be able to receive payments from smart contracts.
transferAddress string Your deposit address. Settle operations on this wallet will use this address.
Warning! - This address must be able to receive payments from smart contracts.

Response

Field Type Description
addr string Wallet address

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema
ValidationError
wallet_already_exists|<addr>
A wallet with address <addr> has already been created with the specified payment 'id' for the given network

Retrieve a Payment

curl "https://api.pay.bleumi.com/v1/payment/1"
  -H "x-api-key: <key>"

The above command returns JSON structured like this:

{
  "id": "1",
  "addresses": {
    "ethereum": {
      "xdai_testnet": {
        "addr": "0xbe1fa332f24ba568108ba55a25eccf93d882f54e"
      },
      "rinkeby": {
        "addr": "0xbea2f9d56c3cc7f2c7e17d294200dd75708eecd8"
      }
    }
  },
  "balances": {
    "ethereum": {
      "xdai_testnet": {
        "XDAIT": {
          "balance": "1",
          "token_decimals": 15,
          "blockNum": "1698324",
          "token_balance": "1000000000000000"
        }
      }
    }
  },
  "createdAt": 1574493617,
  "updatedAt": 1574494588
}

This endpoint retrieves the wallet addresses & token balances for a given payment.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/{id}

URL Parameters

Parameter Description
id Unique identifier of the payment (specified during Create a Payment) to retrieve

Response

Field Type Description
addresses dictionary A dictionary which gives the address of the wallet generated for each network
balances dictionary A dictionary which gives the token balances in each network
createdAt integer The created UNIX timestamp of the payment
updatedAt integer The last updated UNIX timestamp of the payment

Response - Ethereum Address

Field Type Description
addr string Address of the wallet generated

Response - Ethereum Balance

Field Type Description
balances.balance string Token balance for the wallet
balances.token_balance string Token balance for the wallet in Ethereum format
balances.token_decimals integer Token decimal places
balances.blockNum string Block in which the balance was last updated

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema

List all Payments

curl "https://api.pay.bleumi.com/v1/payment"
  -H "x-api-key: <key>"
  -d "sortBy=createdAt&startAt=1546300800&endAt=1577836800&nextToken=ClMKEwoJY3JlYXRlZEF0EgYI2tKb7QUSOGoQc35wYXktZGV2LTIzNTkxMXIkCxIHQWNjb3VudCIKdGhpcnVwYXRoeQwLEgZXYWxsZXQiATcMGAAgAQ=="

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "2",
      "addresses": {
        "ethereum": {
          "ropsten": {
            "addr": "0xbe02daaf993b29302c2e983b63eca1465c227245"
          }
        }
      },
      "balances": {
        "ethereum": {
          "ropsten": {
            "0x84df8548086ec9025e9c93297058bed706e90ddd": {
              "blockNum": "6831652",
              "token_balance": "0",
              "balance": "0",
              "token_decimals": 18
            }
          }
        }
      },
      "createdAt": 1574493797,
      "updatedAt": 1574502335
    },
    {
      "id": "1",
      "addresses": {
        "ethereum": {
          "xdai_testnet": {
            "addr": "0xbe1fa332f24ba568108ba55a25eccf93d882f54e"
          },
          "rinkeby": {
            "addr": "0xbea2f9d56c3cc7f2c7e17d294200dd75708eecd8"
          }
        }
      },
      "balances": {
        "ethereum": {
          "xdai_testnet": {
            "XDAIT": {
              "blockNum": "1698324",
              "token_balance": "1000000000000000",
              "balance": "1",
              "token_decimals": 15
            }
          }
        }
      },
      "createdAt": 1574493617,
      "updatedAt": 1574494588
    }
  ]
}

This endpoint retrieves all payments created.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment

Pagination

The list of payments is returned as an array in the 'results' field. The list is restricted to a maximum of 10 per page.

If there are more than 10 payments, a cursor is returned in the 'nextToken' field. Passing this as the 'nextToken' query parameter will fetch the next page.

When the value of 'nextToken' field is an empty string, there are no more payments.

Query Parameters

Parameter Type Description
nextToken string Cursor to start results from
sortBy string 'createdAt' - results will be sorted by created time in ascending order.
'updatedAt' - results will be sorted by last updated time in ascending order.
startAt string Get payments from this timestamp (unix)
endAt string Get payments till this timestamp (unix)

Response

Parameter Type Description
nextToken Cursor to fetch next set of results (if next set is available)
results[] Array of payments, output format is similar to the response of the Retrieve a Payment endpoint

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
MalformedRequest
nextToken_invalid
'nextToken' value is invalid
ValidationError
<details>
Details on input which does not conform to the above schema

Settle a Payment

curl "https://api.pay.bleumi.com/v1/payment/wallet/2/settle?chain=ropsten"
  -X POST
  -H "x-api-key: <key>"
  --X POST
  --data '
{
    "amount": "5",
    "token": "0x84df8548086ec9025e9c93297058bed706e90ddd"
}
'

The above command returns JSON structured like this:

{
  "txid": "1574502130940"
}

This endpoint settles a specific amount of a token for a given payment to the transferAddress (specified during Create a Payment) and remaining balance (if any) will be refunded to the buyerAddress (specified during Create a Payment).

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/wallet/{id}/settle?chain={chain}

URL Parameters

Parameter Description
id Unique identifier of the payment (specified during Create a Payment) to settle

Query Parameters

Parameter Type Description
chain string Network in which the wallet is to be settled. Please refer to the Supported Networks.

Request

Field Type Description
amount string Token amount to be settled to the transferAddress (specified during Create a Payment)
token string ETH - for Ethereum settlements
XDAI - for xDai settlements
XDAIT - for xDai Testnet settlements
<contract address of ERC-20 token> - for ERC-20 settlements; Please refer to ERC-20 Tokens for contract address;

Response

Parameter Type Description
txid Unique identifier for the settle operation

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema
ValidationError
no_gas_accounts
No active gas accounts present in account, please activate atleast one account from the developer portal
ValidationError
prev_tx_inprogress
A previous operation is still being processed for this wallet
ValidationError
invalid_token
Provided token is not valid for the specified 'net' & 'chain'

Refund a Payment

curl "https://api.pay.bleumi.com/v1/payment/1/refund?chain=ropsten"
  -X POST
  -H "x-api-key: <key>"
  --data '
{
    "token": "XDAIT"
}
'

The above command returns JSON structured like this:

{
  "txid": "1574502150086"
}

This endpoint refunds the balance of a token for a given payment to the buyerAddress (specified during Create a Payment).

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/{id}/refund?chain={chain}

URL Parameters

Parameter Description
id Unique identifier of the payment (specified during Create a Payment) to refund

Query Parameters

Parameter Type Description
chain string Network in which the wallet is to be refunded. Please refer to the Supported Networks.

Request

Field Type Description
token string ETH - for Ethereum refunds
XDAI - for xDai refunds
XDAIT - for xDai Testnet refunds
<contract address of ERC-20 token> - for ERC-20 refunds; Please refer to ERC-20 Tokens for contract address;

Response

Parameter Type Description
txid Unique identifier for the refund operation

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema
ValidationError
no_gas_accounts
No active gas accounts present in account, please activate atleast one account from the developer portal
ValidationError
prev_tx_inprogress
A previous operation is still being processed for this wallet
ValidationError
invalid_token
Provided address is not a valid ERC-20 token

Retrieve a Payment Operation

curl "https://api.pay.bleumi.com/v1/payment/1/operation/1574502150086"
  -H "x-api-key: <key>"

The above command returns JSON structured like this:

{
  "chain": "xdai_testnet",
  "funcName": "createAndRefundWallet",
  "inputs": {
    "addr": "0xbe1fa332f24ba568108ba55a25eccf93d882f54e",
    "token": "XDAIT"
  },
  "status": true,
  "hash": "0x79dca6990b9ef4b07db158dbae9969033d058954edaa24e0d52aef80ef05eca8"
}

This endpoint retrieves a payment operation for a specific payment.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/{id}/operation/{txid}

URL Parameters

Parameter Description
id Unique identifier of the payment (specified during Create a Payment)
txid Transaction ID of the operation (returned during Refund Payment / Settle Payment) to retrieve

Response

Field Type Description
chain string Network in which the operation was carried out
funcName string Name of the function invoked on the Payment Processor.

Functions available:
- createAndSettleWallet
- createAndRefundWallet
status boolean null - Operation in progress
true - Operation confirmed by network
false - Operation rejected by network
hash string Transaction hash of the operation submitted to the network. This field is blank when the operation is in progress.
inputs.
addr
string Address of the wallet
inputs.
amount
string Amount (Only for settle operation)
inputs.
token
string ETH - for Ethereum
XDAI - for xDai
XDAIT - for xDai Testnet
<contract address of ERC-20 token> - for ERC-20; Please refer to ERC-20 Tokens for contract address;
inputs.
token_amount
string Token amount to be settled in network format (Only for settle operation)
inputs.
token_decimals
integer Token decimal places (Only for settle operation)

List all Payment Operations

curl "https://api.pay.bleumi.com/v1/payment/1/operation"
  -H "x-api-key: <key>"
  -d "nextToken=ClM1FqoJY3JlYXRlZEF0EgYI2tKb7QUSOGoQc35wYXktZGV2LTIzNTkxMXIkCxIHQWNjb3VudCIKdGhpcnVwYXRoeQwLEgZXYWxsZXQiATcMGAAgAZ=="

The above command returns JSON structured like this:

{
  "results": [
    {
      "txid": "1574502150086",
      "chain": "xdai_testnet",
      "funcName": "createAndRefundWallet",
      "inputs": {
        "addr": "0xbe1fa332f24ba568108ba55a25eccf93d882f54e",
        "token": "XDAIT"
      },
      "status": true,
      "hash": "0x79dca6990b9ef4b07db158dbae9969033d058954edaa24e0d52aef80ef05eca8"
    }
  ]
}

This endpoint retrieves all payment operations for a specific payment.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/{id}/operation

Pagination

The list of operations is returned as an array in the 'results' field. The list is restricted to a maximum of 10 operations per page.

If there are more than 10 operations for a wallet, a cursor is passed in the 'nextToken' field. Passing this as the 'nextToken' query parameter will fetch the next page.

When the value of 'nextToken' field is an empty string, there are no more operations.

URL Parameters

Parameter Description
id Unique identifier of the payment (specified during Create a Payment)

Query Parameters

Parameter Type Description
nextToken Cursor to start results from

Response

Parameter Type Description
nextToken Cursor to fetch next set of results (if next set is available)
results[] Array of payment operations, output format is similar to the response of the Retrieve a Payment Operation endpoint

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
MalformedRequest
nextToken_invalid
'nextToken' value is invalid
ValidationError
<details>
Details on input which does not conform to the above schema

Hosted Checkouts

Create a Checkout URL

curl "https://api.pay.bleumi.com/v1/payment/hc"
  --H "Content-Type: application/json"
  --H "x-api-key: <key>"
  --X POST
  --data '
{
    "id": "4",
    "currency": "USD",
    "amount": "10",
    "cancelUrl": "https://demo.store/api/cancelOrder?id=1",
    "successUrl": "https://demo.store/api/completeOrder?id=1"
}
'

The above command returns JSON structured like this:

{
  "id": "TBCItOjmR52dFo1a6JxCqQ",
  "url": "https://pay.bleumi.io/?id=TBCItOjmR52dFo1a6JxCqQ"
}

This endpoint generates a unique checkout URL to accept payment. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/hc

Request

Field Type Description
id string Unique identifier for this payment.
Warning! - Do not reuse this id with the Create a Payment endpoint.
currency string Currency Code

When you configure custom tokens for the Hosted Checkout in your account in the Bleumi Pay Dashboard, please use:
- ISO 4217 Alphabetic Code for fiat, gold, silver, etc.
- Token Symbol for crypto
chain string (Required if specifying 'token') Network in which the hosted checkout is to be created. Please refer to the Supported Networks.
token
(Optional)
string If this field is not, a list of tokens configured for the provided currency code for the Hosted Checkout in your account in the Bleumi Pay Dashboard is sent to the buyer. The buyer can complete the payment using any one of token from this list.

Set the token which must be used by the buyer for this payment. The token provided must be set in your portal for the provided currency code. The token is assumed to be 1:1 with the currency unit.

ETH - for Ethereum
XDAI - for xDai
XDAIT - for xDai Testnet
<contract address of ERC-20 token> - for ERC-20; Please refer to ERC-20 Tokens for contract address;
amount array Token amount for this payment
cancelUrl string Buyer will be redirected to this URL upon canceling the payment
successUrl string Buyer will be redirected to this URL upon successfully completing the payment and the following data is passed as GET parameters,
  • id - Unique identifier of the checkout URL
  • hmac.input - Payment parameters used to generate HMAC. The format is described below.
  • hmac.keyId - Key ID used to generate HMAC
  • hmac.alg - Algorithm used to generate HMAC
  • hmac.value - HMAC generated for hmac.input
buyerAddress
(Optional)
string Refund address for this payment.
You can set this to your address to manually handle refunds (outside of Bleumi Pay) to your buyer.

Format - hmac.input GET parameter passed in successUrl

The hmac.input GET parameter passed to successUrl contains payment parameters as a pipe ('|') separated string in the following order,

Response

Field Type Description
id string Unique identifier generated for this checkout URL
url string URL for buyer to complete payment

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema
ValidationError
no_tokens_defined
Please configure tokens for the Hosted Checkout in your account in the Bleumi Pay Dashboard
ValidationError
no_tokens_defined_for_currency
No tokens have been defined in your account for the specified currency
ValidationError
invalid_token
The token provided is not valid for the specified currency

List all Tokens

curl "https://api.pay.bleumi.com/v1/payment/hc/tokens"
  -H "x-api-key: <key>"
  -d "sortBy=createdAt&startAt=1546300800&endAt=1577836800&nextToken=ClMKEwoJY3JlYXRlZEF0EgYI2tKb7QUSOGoQc35wYXktZGV2LTIzNTkxMXIkCxIHQWNjb3VudCIKdGhpcnVwYXRoeQwLEgZXYWxsZXQiATcMGAAgAQ=="

The above command returns JSON structured like this:

[
    {
        "addr": "0x84df8548086ec9025e9c93297058bed706e90ddd",
        "chain": "ropsten",
        "symbol": "USD18",
        "name": "USD p18",
        "decimals": 18
    }
]

This endpoint retrieves all tokens configured for the Hosted Checkout in your account in the Bleumi Pay Dashboard.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/hc/tokens

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
no_tokens_defined
No tokens have been defined in your account

Validate a Checkout Payment

curl "https://api.pay.bleumi.com/v1/payment/hc/validate"
  --H "Content-Type: application/json"
  --H "x-api-key: <key>"
  --X POST
  --data '
{
    "hmac": {
    "input": "ropsten|0xbe98e68c0ffbead18f94882b0f5d15eb31930cee|0x84df8548086ec9025e9c93297058bed706e90ddd|10|12",
    "keyId": "v1",
    "alg": "HMAC-SHA256-HEX",
    "value": "e842bb5f3f62319864293ecb7ccc01674a0af08e4e74a01ab16b2157c3fce5d6" 
    }
}
'

The above command returns JSON structured like this:

{
  "valid": true
}

This endpoint is used to validate the GET parameters passed by Hosted Checkout in successUrl upon successfully completing payment. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/hc/validate

Request

Field Type Description
hmac.
input
string Payment Details. Passed as GET parameter in successUrl.
hmac.
keyId
string KeyId used to generate the HMAC. Passed as GET parameter in successUrl.
hmac.
alg
string Algorithm used to generate the HMAC. Passed as GET parameter in successUrl.
hmac.
value
string HMAC passed as GET parameter in successUrl.

Response

Field Type Description
valid boolean true - The data has been generated by Bleumi Pay
false - The data has not been generated by Bleumi Pay, the payment must be treated as unpaid

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema

Payouts

Create a Payout

curl "https://api.pay.bleumi.com/v1/payout?chain=ropsten"
  --H "Content-Type: application/json"
  --H "x-api-key: <key>"
  --X POST
  --data '
{
    "txid": "12345-6789",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "payouts": [
        {
            "transferAddress": "0xD15BDD17175825742A5904b21008dd3A019a060E",
            "amount": "1"
        },
        {
            "transferAddress": "0x7Dc30B85084aA1608e5C1Ce39c804Be177e40A07",
            "amount": "1"
        }
    ]
}
'

The above command returns JSON structured like this:

{
  "salt": "0x09d6f6e0c0c781a6c49153db62c72e4d8b159f742a42e8c4cfb18fc2b9c44224"
}

This endpoint makes a payout from your Private Payment Processor. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payout

Query Parameters

Parameter Type Description
chain string Network in which the payout is to be made. Please refer to the Supported Networks.

Request

Field Type Description
txid string Unique identifier for this payout
token string ETH - for Ethereum payouts
XDAI - for xDai payouts
XDAIT - for xDai Testnet payouts
<contract address of ERC-20 token> - for ERC-20 payouts; Please refer to ERC-20 Tokens for contract address;
payouts array Array of payments to be made in this payout.
This is an atomic transaction (i.e. either all payments are processed or all of them are rejected).
payouts.
transferAddress
string Address of receiver.
Warning! - This address must be able to receive payments from smart contracts.
payouts.
amount
string Amount of token to transfer

Response

Field Type Description
salt string Unique id generated for the given txid

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
ValidationError
<details>
Details on input which does not conform to the above schema
ValidationError
invalid_token
Provided token is not valid for the specified 'chain'
ValidationError
no_gas_accounts
No active gas accounts present in your account. Please activate at least one gas account from the Bleumi Pay Dashboard.
ValidationError
txid_already_exists
The 'txid' provided has been used previously
ValidationError
not_whitelisted|<addr>
The <addr> provided has not been whitelisted in your Private Payment Processor
ValidationError
payouts_requires_private_payment_processor
Private Payment Processor is not set up and linked to your account

List all Payouts

curl "https://api.pay.bleumi.com/v1/payout"
  -H "x-api-key: <key>"
  -d "sortBy=createdAt&startAt=1546300800&endAt=1577836800&nextToken=ClMKEwoJY3JlYXRlZEF0EgYI2tKb7QUSOGoQc35wYXktZGV2LTIzNTkxMXIkCxIHQWNjb3VudCIKdGhpcnVwYXRoeQwLEgZXYWxsZXQiATcMGAAgAQ=="

The above command returns JSON structured like this:

{
  "results": [
    {
      "txid": "12345-6789-10",
      "status": false,
      "hash": "<N/A>",
      "createdAt": 1574501464,
      "updatedAt": 1574501769,
      "inputs": {
        "salt": "0x6f3b4b923b133a82dddef57139b6bbd622e7343128983518557cd13201c5462b",
        "token": "0x84df8548086ec9025e9c93297058bed706e90ddd",
        "payouts": [
          {
            "transferAddress": "0xD15BDD17175825742A5904b21008dd3A019a060E",
            "amount": "15"
          },
          {
            "amount": "21",
            "transferAddress": "0x7Dc30B85084aA1608e5C1Ce39c804Be177e40A07"
          }
        ]
      }
    },
    {
      "txid": "12345-6789",
      "status": true,
      "hash": "0xbb7b393f61fdd8cf1337010003c46115fbf451b29e40098b9af1ff55ee9465b2",
      "createdAt": 1574501339,
      "updatedAt": 1574501659,
      "inputs": {
        "salt": "0x09d6f6e0c0c781a6c49153db62c72e4d8b159f742a42e8c4cfb18fc2b9c44224",
        "token": "0x84df8548086ec9025e9c93297058bed706e90ddd",
        "payouts": [
          {
            "transferAddress": "0xD15BDD17175825742A5904b21008dd3A019a060E",
            "amount": "1"
          },
          {
            "transferAddress": "0x7Dc30B85084aA1608e5C1Ce39c804Be177e40A07",
            "amount": "1"
          }
        ]
      }
    }
  ]
}

This endpoint retrieves all payouts created.

HTTP Request

GET https://api.pay.bleumi.com/v1/payout

Pagination

The list of payouts is returned as an array in the 'results' field. The list is restricted to a maximum of 10 payouts per page.

If there are more than 10 payouts, a cursor is returned in the 'nextToken' field. Passing this as the 'nextToken' query parameter will fetch the next page.

When the value of 'nextToken' field is an empty string, there are no more payouts.

Query Parameters

Parameter Type Description
nextToken string Cursor to start results from
sortBy string 'createdAt' - results will be sorted by created time in ascending order.
'updatedAt' - results will be sorted by last updated time in ascending order.
startAt string Get payouts from this timestamp (unix)
endAt string Get payouts till this timestamp (unix)

Response

Parameter Type Description
nextToken Cursor to fetch next set of results. (if next set is available)
results[] Array of Payouts

Response - Payout

Parameter Type Description
status boolean null - Operation in progress
true - Operation confirmed by network
false - Operation rejected by network
hash string Transaction hash of the operation submitted to the network. This field is blank when the operation is in progress.
inputs.
salt
string Unique identifier generated for the txid of the payout (specified during Create a Payout).
inputs.
token
string Token used for the payout
inputs.
payouts
dictionary Payout details (specified during Create a Payout)

400 Errors

The following table is a list of possible error codes that can be returned, along with additional information about how to resolve them for a response with 400 status code.

errorCode
errorMessage
Description
MalformedRequest
nextToken_invalid
'nextToken' value is invalid
ValidationError
<details>
Details on input which does not conform to the above schema

Notifications

To receive real-time notifications, set your webhook URL in the Bleumi Pay Dashboard. Your webhook URL must be publicly accessible and must be able to process HTTP(S) POST requests with JSON payloads.

Note: Real-time notifications are provided on a best-effort basis and are not guaranteed. To ensure reliable processing, you can run an hourly batch process for

Webhook Events

You will receive two types of webhook events, they can be distinguised using the 'event_type' field.

The following sections describe the data model for each event.

Balance Update

{
  "event_type": "eth_balance",
  "data": {
    "chain": "ropsten",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "balance": "10",
    "token_balance":"10000000",
    "token_decimals":6,
    "blockNum": "646844"
  }
}
'
Field Type Description
chain string Network for which the event was created. Please refer to the Supported Networks.
addr string Address of the wallet for which the balance has been updated
token string ETH - for Ethereum
XDAI - for xDai
XDAIT - for xDai Testnet
<contract address of ERC-20 token> - for ERC-20; Please refer to ERC-20 Tokens for contract address;
balance string Token balance for the wallet
token_balance string Token balance for the wallet in Ethereum format
token_decimals integer Token decimal places
blockNum string The blocknumber when the balance was updated

The blockNum field can be used to de-duplicate requests for a wallet. Incoming events with a blockNum lesser than the previously received "Balance Update" event for a wallet can be ignored.

Operation

{
  "event_type": "eth_operation",
  "data": {
    "chain": "ropsten",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "txid": "1572337931676",
    "hash": "0xd3c578c8613aecbfe0db4930a9196ea0ea2a4856161d454a3bfe6bf4ce2a7d3a",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "funcName": "createAndSettleWallet",
    "status": true
  }
}
'
Field Type Description
chain string Network for which the event was created. Please refer to the Supported Networks.
addr string Address of the wallet for which the balance has been updated
txid string Transaction ID for the operation
token string ETH - for Ethereum
XDAI - for xDai
XDAIT - for xDai Testnet
<contract address of ERC-20 token> - for ERC-20; Please refer to ERC-20 Tokens for contract address;
funcName string Name of the function invoked on the Payment Processor.

Functions available:
- createAndSettleWallet
- createAndRefundWallet
status boolean true - Operation confirmed by network
false - Operation rejected by network
hash string Transaction hash of the operation submitted to the network. This field is blank when the operation is in progress.

Payout

{
  "event_type": "eth_payout",
  "data": {
    "chain": "ropsten",
    "txid": "1572337931676",
    "hash": "0xd3c578c8613aecbfe0db4930a9196ea0ea2a4856161d454a3bfe6bf4ce2a7d3a",
    "status": true
  }
}
'
Field Type Description
chain string Network for which the event was created. Please refer to the Supported Networks.
txid string Transaction ID for the payout
status boolean true - Operation confirmed by network
false - Operation rejected by network
hash string Transaction hash of the operation submitted to the network. This field is blank when the operation is in progress.

Supported Networks

Ethereum

Production

Name Code
Mainnet mainnet
xDai xdai

Testnet

Name Code
Görli goerli
Kovan kovan
Rinkeby rinkeby
Ropsten ropsten
xDai Testnet xdai_testnet

As xDai does not have an official testnet, Bleumi Pay uses the Görli network for payments on the 'xdai_tesnet'. Payments on 'xdai_testnet' use the symbol 'XDAIT' and are made using ETH on the Görli network. To make testing easier the amount of ETH sent is multiplied by 1000.

E.g. Sending a payment of 0.001 ETH on the Görli network will be reported as a payment of 1 XDAIT in 'xdai_testnet'.

Tokens

ERC-20

Production

The following tokens are recommended ERC-20 stablecoins. Refer Etherscan for a comprehensive list of ERC-20 tokens.

Network Currency Code Token Contract Address Token Name Token Symbol Token Decimal Places
Mainnet USD 0xdac17f958d2ee523a2206206994597c13d831ec7 Tether USDT 6
Mainnet USD 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 USD Coin USDC 6
Mainnet USD 0x8e870d67f660d95d5be530380d0ec0bd388289e1 Paxos Standard PAX 18
Mainnet USD 0x0000000000085d4780B73119b644AE5ecd22b376 TrueUSD TUSD 18
Mainnet USD 0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359 Single Collateral DAI SAI 18
Mainnet USD 0x6b175474e89094c44da98b954eedeac495271d0f Multi Collateral DAI DAI 18
Mainnet USD 0x1c48f86ae57291f7686349f12601910bd8d470bb USDK USDK 18
Mainnet USD 0x4fabb145d64652a948d72533023f6e7a623c7c53 Binance USD BUSD 18
Mainnet USD 0x056fd409e1d7a124bd7017459dfea2f387b6d5cd Gemini Dollar BUSD 2
Mainnet USD 0x57ab1e02fee23774580c119740129eac7081e9d3 sUSD SUSD 18
Mainnet USD 0x4954db6391f4feb5468b6b943d4935353596aec9 USDQ USDQ 18
Mainnet USD 0xa4bdb11dc0a2bec88d24a3aa1e6bb17201112ebe StableUSD USDS 6
Mainnet AUD 0x00006100F7090010005F1bd7aE6122c3C2CF0090 TrueAUD TAUD 18
Mainnet CAD 0x00000100F2A2bd000715001920eB70D229700085 TrueCAD TCAD 18
Mainnet EUR 0xdb25f211ab05b1c97d595516f45794528a807ad8 STASIS EURO EURS 2
Mainnet EUR 0xabdf147870235fcfc34153828c769a70b3fae01f Tether EUR EURT 6
Mainnet GBP 0xc9a2c4868f0f96faaa739b59934dc9cb304112ec Binance GBP BGBP 8
Mainnet GBP 0x00000000441378008ea67f4284a57932b1c000a5 TrueGBP TGBP 18
Mainnet CHF 0xb4272071ecadd69d933adcd19ca99fe80664fc08 CryptoFranc XCHF 18
Mainnet HKD 0x0000852600ceb001e08e00bc008be620d60031f2 TrueHKD THKD 18
Mainnet SGD 0x0f72714b35a366285df85886a2ee174601292a17 1SG 1SG 18
Mainnet KRW 0x3c6cfbdaf0a04fc257b185bf98934a12124fe8d0 KRWQ KRWQ 18

Testnet

The following tokens are maintained by Bleumi for the sole purpose of making it easier for developers to test the Bleumi Pay API in the various testnets.

Use your preferred wallet to make a 0 ETH transaction to a token address with 100,000 gas. Once the transaction is confirmed, your wallet will be funded with 10,000 tokens.

Network Currency Code Token Contract Address Token Name Token Symbol Token Decimal Places
Görli USD 0x84df8548086EC9025E9C93297058Bed706E90DDD USD p18 USD18 18
Görli USD 0x115615DbD0f835344725146Fa6343219315F15E5 USD p6 USD6 6
Görli USD 0x87e0B406E5759EAc304f10fB725652C5f54408f8 USD p2 USD2 2
Görli EUR 0x781e3520413B34aD6a61245e9aA7262d43FE60E4 EUR p2 EUR2 2
Kovan USD 0x13f64504c901fD59313ac2B36D8232F176Ff7DC9 USD p18 USD18 18
Kovan USD 0xdD81FF436d377193FeD46563766E3C79c5529a58 USD p6 USD6 6
Kovan USD 0x8A2C4d3195D5761d87c6D31806339b6e6a03f4e2 USD p2 USD2 2
Kovan EUR 0x33E860d5784e3ACFa996a71893379944A305b53E EUR p2 EUR2 2
Rinkeby USD 0x56EEaBc0646794Aa6223de83B7850008239D8Adf USD p18 USD18 18
Rinkeby USD 0x13f64504c901fD59313ac2B36D8232F176Ff7DC9 USD p6 USD6 6
Rinkeby USD 0xdD81FF436d377193FeD46563766E3C79c5529a58 USD p2 USD2 2
Rinkeby EUR 0x8A2C4d3195D5761d87c6D31806339b6e6a03f4e2 EUR p2 EUR2 2
Ropsten USD 0x84df8548086EC9025E9C93297058Bed706E90DDD USD p18 USD18 18
Ropsten USD 0x115615DbD0f835344725146Fa6343219315F15E5 USD p6 USD6 6
Ropsten USD 0x87e0B406E5759EAc304f10fB725652C5f54408f8 USD p2 USD2 2
Ropsten EUR 0x781e3520413B34aD6a61245e9aA7262d43FE60E4 EUR p2 EUR2 2

Errors

Bleumi Pay API uses the following HTTP status codes for unsuccessful responses,

HTTP Status Code Meaning
400 Bad Request - Your request is invalid. Response is a JSON object with the following fields,

'errorCode' - Error type
'errorMessage' - Short code for identifying error

Please check the "400 Errors" section under each endpoint for possible error codes that can be returned, along with additional information about how to resolve them.
401 Unauthorized - Your API key is wrong.
403 Access Denied - Check your request URL.
429 Too Many Requests
500 Internal Server Error - We had a problem with our server. Try again later.
502 Bad Gateway Exception - We had a problem with our server. Try again later.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.
504 Gateway Timeout - We had a problem with our server. Try again later.

API Limits

API requests are subject to the following limits,

Name Description
Rate 50 requests per second
Burst 500 requests
Quota 10,000 requests per day

If you need to increase the limits on your account, please contact sales@bleumi.com.