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 ERC20 stablecoin payments into your business or application.

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 developer portal.

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

ERC20 Payments

Generate Wallet Address

curl "https://api.pay.bleumi.com/v1/payment/erc20/wallet?chain=ropsten"
  --H "Content-Type: application/json" 
  --H "x-api-key: <key>"
  --X POST
  --data '
{
    "id": "1",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "buyerAddress": "0x71bc257fda57998e6715ee0b3370ab3b054f3111",
    "transferToPaymentProcessor": false
}
'

The above command returns JSON structured like this:

{
    "chain": "ropsten",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "balance": "0",
    "blockNum": "0"
}

This endpoint generate a unique wallet address to accept payments for a ERC20 token. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/erc20/wallet

Query Parameters

Parameter Default Description
chain string Ethereum network in which wallet is to be created. Please refer to the network list

Request

Field Type Description
id string Unique identifier for this wallet
token string ERC20 compliant contract address
buyerAddress string Ethereum address of buyer. Refund operations on this wallet will use this address.
transferToPaymentProcessor bool true - Payment received from the buyer will be transferred to the payment processor.
false - Payment received from the buyer will be transferred to the owner of the payment processor.

Response

Field Type Description
chain string Ethereum network in which wallet will be created
addr string Wallet address
token string ERC20 token address
balance string ERC20 token balance for wallet
blockNum string Block in which wallet was last updated, initially set to 0

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
VerificationIncomplete Production network access requires a verified account. To enable production access, contact support@bleumi.com
SetupIncomplete Sandbox/Production setup incomplete, contact support@bleumi.com
MalformedRequest
input_invalid
Input does not match schema
ValidationError
chain_invalid
Invalid value provided for chain
ValidationError
token_invalid
Contract address provided is not a valid ERC20 compliant token
PaymentAlreadyExists Wallet with 'id' already exists, please use a different id

Get a Specific Wallet

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

The above command returns JSON structured like this:

{
    "chain": "ropsten",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "balance": "0",
    "blockNum": "0"
}

This endpoint retrieves a specific wallet.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/erc20/wallet/{ID}

URL Parameters

Parameter Description
ID The ID of the wallet to retrieve

Response

Field Type Description
chain string Ethereum network in which wallet will be created
addr string Wallet address
token string ERC20 token address
balance string ERC20 token balance for wallet
blockNum string Block in which wallet was last updated, initially set to 0

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
id_not_found
URL parameter 'ID' not found

Get All Wallets

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

The above command returns JSON structured like this:

{
  "nextToken": "",
  "results": [
    {
        "chain": "ropsten",
        "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
        "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
        "balance": "2",
        "blockNum": "637263"
    },
    {
        "chain": "ropsten",
        "addr": "0xbec3e2f4d3b6ca13d09471f39d21ac1c1647525a",
        "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
        "balance": "11.2",
        "blockNum": "672932"
    }
  ]
}

This endpoint retrieves all wallets

HTTP Request

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

Pagination

The list of wallets is returned as an array in the 'results' field. The list is restricted to a maximum of 100 wallets.

If there are more wallets 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 wallets.

Query Parameters

Parameter Default Description
nextToken Cursor to start results from
sortBy createdAt 'createdAt' - results will be sorted by created time in ascending order.
'updatedAt' - results will be sorted by last updated time in ascending order.
startAt Get payments from this timestamp (unix). Will be compared to created or updated time based on the value of sortBy parameter.
endAt Get payments till this timestamp (unix). Will be compared to created or updated time based on the value of sortBy parameter.

Response

Field Type Description
chain string Ethereum network in which wallet will be created
addr string Wallet address
token string ERC20 token address
balance string ERC20 token balance for wallet
blockNum string Block in which wallet was last updated, initially set to 0

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
MalformedRequest
sortBy_unsupported
'sortBy' must be 'createdAt' or 'updatedAt'
MalformedRequest
startAt_not_integer
'startAt' value is not a integer
MalformedRequest
endAt_not_integer
'endAt' value is not a integer

Refund a Specific Wallet

curl "https://api.pay.bleumi.com/v1/payment/erc20/wallet/1/refund"
  -X POST
  -H "x-api-key: <key>"

This endpoint refunds a specific wallet. Any amount received will be refunded to the buyer address specified during its creation.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/erc20/wallet/{ID}/refund

URL Parameters

Parameter Description
ID The ID of the wallet to refund

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
id_not_found
URL parameter 'ID' not found

Settle a Specific Wallet

curl "https://api.pay.bleumi.com/v1/payment/erc20/wallet/2/settle"
  -X POST
  -H "x-api-key: <key>"
  --X POST
  --data '
{
    "amount": "1"
}
'

This endpoint settles a specific wallet. The amount specified will be transferred to the payment processor or creator (based on the transferToPaymentProcessor boolean set during creation) and the remaining balance if any will be sent to the address specified in buyerAddress during creation.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/erc20/wallet/{ID}/settle

URL Parameters

Parameter Description
ID The ID of the wallet to settle

Request

Field Type Description
amount string Amount to be settled to payment processor or creator

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
id_not_found
URL parameter 'ID' not found
MalformedRequest
amount_invalid
amount is not a valid number

Get All Operations for a Specific Wallet

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

The above command returns JSON structured like this:

{
  "nextToken": "",
  "results": [
    {
        "funcName": "createAndSettleWallet",
        "status": true,
        "hash": "0x2564059e216196d3fb09e30c21954dcdd17e667bddbaf1f566a6c8d47295a96a",
        "inputs": {
            "amount": "1"
        }
    },
    {
        "funcName": "createAndRefundWallet",
        "status": true,
        "hash": "0x165085abc6b263abd57b79e5c2dfa2b3924ee9e39f9d5b4f41fee65dc4e19af4",
        "inputs": {}
    }
  ]
}

This endpoint retrieves all operations for a specific wallet.

HTTP Request

GET https://api.pay.bleumi.com/v1/payment/erc20/wallet/{ID}/operations

Pagination

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

If there are more operations 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.

Query Parameters

Parameter Default Description
nextToken Cursor to start results from

createAndSettleWallet Response

Field Type Description
funcName string Function invoked on the payment processor
status boolean null - operation in progress
true - operation completed successfuly
false - operation failed to process
hash string Transaction hash of operation submitted to the network. This field is blank when operation is in progress.
inputs.
amount
string Amount to be settled

createAndRefundWallet Response

Field Type Description
funcName string Function invoked on the payment processor
status boolean null - operation in progress
true - operation completed successfuly
false - operation failed to process
hash string Transaction hash of operation submitted to the network. This field is blank when operation is in progress.

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

Payment Notifications

You can receive payment notifications using webhooks, to set your webhook URL you can use the Bleumi Pay developer portal. The URL must be publicly accessible and must be able to process HTTP POST requests with JSON payloads.

Real-time notifications are provided on a best effort basis but are not guaranteed. To ensure reliable processing, you can run an hourly batch process which uses the query endpoint to fetch payment requests sorted by the last updated time.

Webhook Data Model

Payment

{
  "event_type": "payment",
  "payment_data": {
    "chain": "3",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "hash": "0xd3c578c8613aecbfe0db4930a9196ea0ea2a4856161d454a3bfe6bf4ce2a7d3a",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "balance": "10.23",
    "blockNum": "646844"
  }
}
'

Notifications are sent for each ERC20 transfer received by a wallet. The notification contains the wallet balance and the associated block number.

Operation

{
  "event_type": "operation",
  "operation_data": {
    "chain": "3",
    "addr": "0xbefda6e35785ff904732fb71e10acaaab29c39e4",
    "hash": "0xd3c578c8613aecbfe0db4930a9196ea0ea2a4856161d454a3bfe6bf4ce2a7d3a",
    "token": "0x84df8548086EC9025E9C93297058Bed706E90DDD",
    "funcName": "createAndSettleWallet",
    "status": true
  }
}
'

These events are sent once the operation has 12 confirmations on the blockchain. The schema is the same as described in get endpoint

Ethereum

Bleumi Pay supports ERC20 stablecoin payments on the Ethereum network.

Supported Ethereum Networks

You may use one of the following Ethereum networks,

Name Code
Mainnet (production) mainnet
Ropsten ropsten
Görli goerli

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.