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 stablecoin payments (on Ethereum & Stellar Networks) 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 the 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 developer portal.

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

Pay-As-You-Go Payments (PAYG)

Make A Request

curl "https://api.pay.bleumi.com/v1/payment/payg/1"
  --H "Content-Type: application/json" 
  --H "x-api-key: <key>"
  --X POST
  --data '
{
  "fromAddress": "0x13e4ACeFE6a6700604929946E70E6443E4E73447",
  "paymentAmount": "10",
  "toAddress": "0xc65e620A3A55451316168d57E268f5702EF56a11",
  "token": {
    "addr": "0xe1922b025ac05e7ee7640de4f3c5e19104cdce02",
    "network": "ropsten"
  }
}
'

The above command returns JSON structured like this:

{
  "paymentAddress": {
    "addr": "0x1532095DDE3255330f1CE8B0d6700122b1157b92"
  }
}
curl "https://api.pay.bleumi.com/v1/payment/payg/2"
  --H "Content-Type: application/json" 
  --H "x-api-key: <key>"
  --X POST
  --data '
{
  "fromAddress": "GDWDREWGE2P367TMHYOL5EGUM2YOTKFPBH4UU4WPXCCZMJL6Z4J4YELK",
  "fromMemo": "483948",
  "paymentAmount": "2",
  "toAddress": "GDYNASCTWRHWF5BRZBHVQIQO2D3TYTFC3N5V5ERQ2HZWUMLYQFUTJLEM",
  "toMemo": "309582",
  "token": {
    "code": "USD",
    "issuer": "GDWEVA6U7ZUKAWERV336BIQ7T3UNLLKSF4ENFK3GZ3Q35ZSU7SWH6AYV",
    "network": "test"
  }
}
'

The above command returns JSON structured like this:

{
  "paymentAddress": {
    "addr": "GC6HB77CRUVFHOYZG4JSCMRDA2XDK3FDHTYUI3OMBTQC7IVKZVV43AQ4",
    "memo": "v5wAsLzUQk2ZYTCSUKfFEA"
  }
}

This endpoint creates a payment request. The request must be passed as JSON.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/payg/{ID}

URL Parameters

Parameter Description
ID The ID of the payment request

Ethereum Payment Request

Field Type Description
fromAddress string (Optional) Ethereum address. Refunds (for cancelled request or excess payment) will be sent to this address.
Incoming payments are not processed until this field is set using the create or update endpoints.
paymentAmount string Payment amount requested.
Minimum payment amount is 10 USD/EUR.
Maximum payment amount is 10,000 USD/EUR.
Decimal places are restricted by the token being used. Please refer to the token list and ensure paymentAmount specified does not exceed the token capability.
currency string (optional)
USD - United States Dollar
EUR - Euro

Defaults to 'USD' if not specified
toAddress string Ethereum address. Payment amount (minus charges) will be sent to this address.
token.
addr
string ERC20 token address. Must be one of the supported tokens
token.
network
string Ethereum network used. Must be one of the supported networks

Ethereum Payment Response

Field Type Description
paymentAddress.
addr
string Ethereum address to which payments must be sent.

Stellar Payment Request

Field Type Description
fromAddress string (Optional) Stellar address. Refunds (for cancelled request or excess payment) will be sent to this address.
Incoming payments are not processed until this field is set using the create or update endpoints.
fromMemo string (Optional) Memo to be used while making a transfer to fromAddress
paymentAmount string Payment amount requested.
Minimum payment amount is 2 USD/EUR.
Maximum payment amount is 10,000 USD/EUR.
Decimal places must be less than or equal to 7
currency string (optional)
USD - United States Dollar
EUR - Euro

Defaults to 'USD' if not specified
toAddress string Stellar address. Payment amount (minus charges) will be sent to this address.
toMemo string (Optional) Memo to be used while making a transfer to toAddress
token.
code
string Asset code. Must be one of the supported assets
token.
issuer
string Asset issuer. Must be one of the supported assets
token.
network
string Stellar network used. Must be one of the supported networks

Stellar Payment Response

Field Type Description
paymentAddress.
addr
string Stellar address to which payments must be sent.
paymentAddress.
memo
string Memo to be set while making payment.
Incoming payments without a memo will not be processed automatically. Please contact support@bleumi.com if you have received payments without a corresponding memo.

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
MalformedRequest
verification_invalid
Payment requests on production networks are only allowed if your account has been verified. You can verify your account on the developer portal
MalformedRequest
payment_id_not_found
URL parameter 'ID' not found
MalformedRequest
input_invalid
Input does not match schema
MalformedRequest
token_invalid
Token does not match schema
MalformedRequest
payment_amount_less
'paymentAmount' is less than the minimum for the network selected
MalformedRequest
toAddress_invalid
The value of 'toAddress' is not an Ethereum/Stellar address
MalformedRequest
fromAddress_invalid
The value of 'fromAddress' is not an Ethereum/Stellar address
MalformedRequest
paymentAmount_not_number
'paymentAmount' provided is not a string representation of a number
MalformedRequest
paymentAmount_exceeds_max
'paymentAmount' exceeds the maximum limit
MalformedRequest
paymentAmount_exceeds_max_precision
'paymentAmount' exceeds precision supported by token requested
MalformedRequest
paymentAmount_exceeds_7_precision
'paymentAmount' exceeds precision (7 digits) supported by Stellar
ValidationError
toAddress_not_found
'toAddress' does not exist on the Stellar network
ValidationError
toAddress_trustline_missing
'toAddress' does not have a Trustline for the asset requested
ValidationError
fromAddress_not_found
'fromAddress' does not exist on the Stellar network
ValidationError
fromAddress_trustline_missing
'fromAddress' does not have a Trustline for the asset requested
PaymentAlreadyExists URL parameter 'ID' already exists, please use a different ID

Update A Request

curl "https://api.pay.bleumi.com/v1/payment/payg/1"
  --H "Content-Type: application/json" 
  --H "x-api-key: <key>"
  --X POST
  --data '
{
  "fromAddress": "0x13e4ACeFE6a6700604929946E70E6443E4E73447",
  "paymentAmount": "10",
  "toAddress": "0xc65e620A3A55451316168d57E268f5702EF56a11"
}
'
curl "https://api.pay.bleumi.com/v1/payment/payg/2"
  --H "Content-Type: application/json" 
  --H "x-api-key: <key>"
  --X PUT
  --data '
{
  "fromAddress": "GDWDREWGE2P367TMHYOL5EGUM2YOTKFPBH4UU4WPXCCZMJL6Z4J4YELK",
  "fromMemo": "483948",
  "paymentAmount": "2",
  "toAddress": "GDYNASCTWRHWF5BRZBHVQIQO2D3TYTFC3N5V5ERQ2HZWUMLYQFUTJLEM",
  "toMemo": "309582"
}
'

This endpoint updates a specific payment request. The request must be passed as JSON.

HTTP Request

PUT https://api.pay.bleumi.com/v1/payment/payg/{ID}

URL Parameters

Parameter Description
ID The ID of the payment request

Ethereum Payment Reuest

Field Type Description
fromAddress string (Optional) Ethereum address. Refunds (for cancelled request or excess payment) will be sent to this address.
Incoming payments are not processed until this field is set using the create or update endpoints.
paymentAmount string Payment amount requested.
Minimum payment amount is 10 USD/EUR.
Maximum payment amount is 10,000 USD/EUR.
Decimal places are restricted by the token being used. Please refer to the token list and ensure paymentAmount specified does not exceed the token capability
toAddress string Ethereum address. Payment amount (minus charges) will be sent to this address.

Stellar Payment Request

Field Type Description
fromAddress string (Optional) Stellar address. Refunds (for cancelled request or excess payment) will be sent to this address.
Incoming payments are not processed until this field is set using the create or update endpoints.
fromMemo string (Optional) Memo to be used while making transfer to fromAddress
paymentAmount string Payment amount requested.
Minimum payment amount is 2 USD/EUR.
Maximum payment amount is 10,000 USD/EUR.
Decimal places must be less than or equal to 7
toAddress string Stellar address. Payment amount (minus charges) will be sent to this address.
toMemo string (Optional) Memo to be used while making transfer to toAddress

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
payment_id_not_found
URL parameter 'ID' not found
MalformedRequest
input_invalid
Input does not match schema
MalformedRequest
payment_amount_less
'paymentAmount' is less than the minimum for the network selected
MalformedRequest
toAddress_invalid
The value of 'toAddress' is not an Ethereum/Stellar address
MalformedRequest
fromAddress_invalid
The value of 'fromAddress' is not an Ethereum/Stellar address
MalformedRequest
paymentAmount_not_number
'paymentAmount' provided is not a string representation of a number
MalformedRequest
paymentAmount_exceeds_max
'paymentAmount' exceeds the maximum limit
MalformedRequest
paymentAmount_exceeds_max_precision
'paymentAmount' exceeds precision supported by token requested
MalformedRequest
paymentAmount_exceeds_7_precision
'paymentAmount' exceeds precision (7 digits) supported by Stellar
MalformedRequest
payment_status_invalid
Payment is not in 'outstanding' or 'partiallyPaid' status, no further updates are possible
ValidationError
toAddress_not_found
'toAddress' does not exist on the Stellar network
ValidationError
toAddress_trustline_missing
'toAddress' does not have a Trustline for the asset requested
ValidationError
fromAddress_not_found
'fromAddress' does not exist on the Stellar network
ValidationError
fromAddress_trustline_missing
'fromAddress' does not have a Trustline for the asset requested
PaymentUnderProcess The payment request is being settled, no further updates are possible

Get a Specific Payment Request

curl "https://api.pay.bleumi.com/v1/payment/payg/011-USDC-EXCESS"
  -H "x-api-key: <key>"

The above command returns JSON structured like this:

{
  "amountPaid": "16",
  "createdAt": 1555497174,
  "fromAddress": "0xA82960eB02D559F3f2E26aa5a8109b5004e16CFb",
  "id": "011-USDC-EXCESS",
  "isProcessing": false,
  "processingCompleted": true,
  "paymentAddress": {
    "addr": "0xe44D7b4AAC155D2c80C911b495A302c3Ad000EFe"
  },
  "paymentAmount": "15",
  "currency": "USD",
  "status": "paid",
  "toAddress": "0x8c9Ca106c78633F91Bc90dF47b3dDAb13043b0D1",
  "token": {
    "addr": "0xc12488475df4137919b4e0f93d66c37018979ab4",
    "network": "ropsten"
  },
  "transfers": [
    {
      "status": "processed",
      "timestamp": 1555500375,
      "toAddr": "0x8c9ca106c78633f91bc90df47b3ddab13043b0d1",
      "transferDest": "toAddress",
      "transferType": "ethereum",
      "txHash": "0x54476c44846f84a5963ba0068345e3126f3998fa46cd9e7ec781691b2f79856a",
      "value": "13.11"
    },
    {
      "status": "processed",
      "timestamp": 1555501275,
      "toAddr": "0x13e4acefe6a6700604929946e70e6443e4e73447",
      "transferDest": "bleumi",
      "transferType": "ethereum",
      "txHash": "0x7ab23d63ba410c3a74fc654f9bafe7ce8b56dc33324178d0f3c8cb11bd3eb261",
      "value": "1.89"
    },
    {
      "status": "processed",
      "timestamp": 1555501876,
      "toAddr": "0xa82960eb02d559f3f2e26aa5a8109b5004e16cfb",
      "transferDest": "fromAddress",
      "transferType": "ethereum",
      "txHash": "0x0f2ba9ce8f917e11380bf568b2faddad14097fe5199f1dcf4d59a351423bf1e3",
      "value": "1"
    }
  ]
}

This endpoint retrieves a specific payment request.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the payment request to retrieve

Ethereum Payment Response

Field Type Description
amountPaid string Total amount received on 'paymentAddress.addr'
createdAt number (optional) Timestamp (unix) when the request was created
updatedAt number (optional) Timestamp (unix) when request was last updated
fromAddress string Ethereum address. Refunds will be sent to this address.
id string Payment request id
isProcessing boolean Indicates whether payment fulfillment is in process. Request cannot be updated once this is set to 'true'.
processingCompleted boolean Indicates when all transfers for the payment request have been executed.
paymentAddress.
addr
string Ethereum address to which payments must be sent.
paymentAmount string Payment amount requested
currency string Currency of payment request
status string Status of the payment request. Possible values are 'outstanding', 'partiallyPaid', 'paid', 'cancelled', 'settled' & 'failed'
toAddress string Ethereum address. Payment amount (minus charges) will be sent to this address.
token.
addr
string ERC20 token address
token.
network
string Ethereum network used
transfers.
status
string Status of transfer. Possible values are 'processed' and 'not_processed'
transfers.
timestamp
number Timestamp (unix) when the transfer was made
transfers.
toAddr
string Ethereum address to which transfer was made
transfers.
transferDest
string 'toAddress' - Payment amount transferred to the address specified in toAddress field.
'fromAddress' - Refund sent to address specified in fromAddress field.
'bleumi' - Charges for payment request sent to Bleumi
transfers.
transferType
string Used to distinguish the type of payment. For Ethereum payments value will be 'ethereum'.
transfers.
txHash
string Transaction hash of transfer
transfers.
value
string Amount that was transferred

Stellar Payment Response

Field Type Description
amountPaid string Total amount received on 'paymentAddress.addr'
createdAt number (optional) Timestamp (unix) when request was created
updatedAt number (optional) Timestamp (unix) when request was last updated
fromAddress string Stellar address. Refunds will be sent to this address.
id string Payment request id
isProcessing boolean Indicates whether payment fulfillment is in process. Request cannot be updated once this is set to 'true'.
processingCompleted boolean Indicates when all transfers for the payment request have been executed.
paymentAddress.
addr
string Stellar address to which payments must be sent.
paymentAddress.
memo
string Memo to be set while making payment.
Incoming payments without a memo will not be processed automatically, please contact support@bleumi.com if you have received payments without a corresponding memo.
paymentAmount string Payment amount requested
currency string Currency of payment request
status string Status of the payment request. Possible values are 'outstanding', 'partiallyPaid', 'paid', 'cancelled', 'settled' & 'failed'
toAddress string Stellar address. Payment amount (minus charges) will be sent to this address.
token.
code
string Asset code.
token.
issuer
string Asset issuer.
token.
network
string Stellar network used.
transfers.
status
string Status of transfer. Possible values are 'processed' and 'not_processed'
transfers.
timestamp
number Timestamp (unix) when the transfer was made
transfers.
toAddr
string Stellar address to which the transfer was made
transfers.
transferDest
string 'toAddress' - Payment amount transferred to the address specified in toAddress field.
'fromAddress' - Refund sent to address specified in fromAddress field.
'bleumi' - Charges for payment request sent to Bleumi
transfers.
transferType
string Used to distinguish the type of payment. For Stellar payments value will be 'stellar'.
transfers.
txHash
string Transaction hash of transfer
transfers.
value
string Amount that was transferred

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

Get All Requests

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

The above command returns JSON structured like this:

{
  "nextToken": "",
  "results": [
    {
      "amountPaid": "10",
      "createdAt": 1555851114,
      "fromAddress": "0x13e4ACeFE6a6700604929946E70E6443E4E73447",
      "id": "1",
      "isProcessing": false,
      "processingCompleted": false,
      "paymentAddress": {
        "addr": "0x1532095DDE3255330f1CE8B0d6700122b1157b92"
      },
      "paymentAmount": "10",
      "currency": "USD",
      "status": "paid",
      "toAddress": "0xc65e620A3A55451316168d57E268f5702EF56a11",
      "token": {
        "addr": "0xe1922b025ac05e7ee7640de4f3c5e19104cdce02",
        "network": "ropsten"
      },
      "transfers": []
    },
    {
      "amountPaid": "2",
      "createdAt": 1555854615,
      "fromAddress": "GDWDREWGE2P367TMHYOL5EGUM2YOTKFPBH4UU4WPXCCZMJL6Z4J4YELK",
      "fromMemo": "483948",
      "id": "2",
      "isProcessing": false,
      "processingCompleted": false,
      "paymentAddress": {
        "addr": "GC6HB77CRUVFHOYZG4JSCMRDA2XDK3FDHTYUI3OMBTQC7IVKZVV43AQ4",
        "memo": "v5wAsLzUQk2ZYTCSUKfFEA"
      },
      "paymentAmount": "2",
      "currency": "USD",
      "status": "paid",
      "toAddress": "GB4MKIEEAJMYJPMYD4VWTEY7N2YIIB67UDFMSBB6SIJZCVVKIA7TIMMY",
      "toMemo": "309582",
      "token": {
        "code": "USD",
        "issuer": "GDWEVA6U7ZUKAWERV336BIQ7T3UNLLKSF4ENFK3GZ3Q35ZSU7SWH6AYV",
        "network": "test"
      },
      "transfers": []
    }
  ]
}

This endpoint retrieves all PAYG payment requests.

HTTP Request

GET https://api.pay.bleumi.com/v1/payments/payg

Pagination

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

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

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.

Ethereum Payment Response

Field Type Description
amountPaid string Total amount received on 'paymentAddress.addr'
createdAt number (optional) Timestamp (unix) when the request was created
updatedAt number (optional) Timestamp (unix) when request was last updated
fromAddress string Ethereum address. Refunds will be sent to this address.
id string Payment request id
isProcessing boolean Indicates whether payment fulfillment is in process. Request cannot be updated once this is set to 'true'.
processingCompleted boolean Indicates when all transfers for the payment request have been executed.
paymentAddress.
addr
string Ethereum address to which payments must be sent.
paymentAmount string Payment amount requested
currency string Currency of payment request
status string Status of the payment request. Possible values are 'outstanding', 'partiallyPaid', 'paid', 'cancelled', 'settled' & 'failed'
toAddress string Ethereum address. Payment amount (minus charges) will be sent to this address.
token.
addr
string ERC20 token address
token.
network
string Ethereum network used
transfers.
status
string Status of transfer. Possible values are 'processed' and 'not_processed'
transfers.
timestamp
number Timestamp (unix) when the transfer was made
transfers.
toAddr
string Ethereum address to which transfer was made
transfers.
transferDest
string 'toAddress' - Payment amount transferred to the address specified in toAddress field.
'fromAddress' - Refund sent to address specified in fromAddress field.
'bleumi' - Charges for payment request sent to Bleumi
transfers.
transferType
string Used to distinguish the type of payment. For Ethereum payments value will be 'ethereum'.
transfers.
txHash
string Transaction hash of transfer
transfers.
value
string Amount that was transferred

Stellar Payment Response

Field Type Description
amountPaid string Total amount received on 'paymentAddress.addr'
createdAt number (optional) Timestamp (unix) when request was created
updatedAt number (optional) Timestamp (unix) when request was last updated
fromAddress string Stellar address. Refunds will be sent to this address.
id string Payment request id
isProcessing boolean Indicates whether payment fulfillment is in process. Request cannot be updated once this is set to 'true'.
processingCompleted boolean Indicates when all transfers for the payment request have been executed.
paymentAddress.
addr
string Stellar address to which payments must be sent.
paymentAddress.
memo
string Memo to be set while making payment.
Incoming payments without a memo will not be processed automatically, please contact support@bleumi.com if you have received payments without a corresponding memo.
paymentAmount string Payment amount requested
currency string Currency of payment request
status string Status of the payment request. Possible values are 'outstanding', 'partiallyPaid', 'paid', 'cancelled', 'settled' & 'failed'
toAddress string Stellar address. Payment amount (minus charges) will be sent to this address.
token.
code
string Asset code.
token.
issuer
string Asset issuer.
token.
network
string Stellar network used.
transfers.
status
string Status of transfer. Possible values are 'processed' and 'not_processed'
transfers.
timestamp
number Timestamp (unix) when the transfer was made
transfers.
toAddr
string Stellar address to which the transfer was made
transfers.
transferDest
string 'toAddress' - Payment amount transferred to the address specified in toAddress field.
'fromAddress' - Refund sent to address specified in fromAddress field.
'bleumi' - Charges for payment request sent to Bleumi
transfers.
transferType
string Used to distinguish the type of payment. For Stellar payments value will be 'stellar'.
transfers.
txHash
string Transaction hash of transfer
transfers.
value
string Amount that was transferred

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

Cancel a Specific Payment

curl "https://api.pay.bleumi.com/v1/payment/payg/2/cancel"
  -X POST
  -H "x-api-key: <key>"

This endpoint cancels a specific payment request. Any amount received will be refunded (minus charges) to the address specified in fromAddress.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/payg/{ID}/cancel

URL Parameters

Parameter Description
ID The ID of the payment request to cancel

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
payment_id_not_found
URL parameter 'ID' not found
PaymentUnderProcess The payment request is being settled, no further updates are possible

Settle a Specific Payment

curl "https://api.pay.bleumi.com/v1/payment/payg/2/settle"
  -X POST
  -H "x-api-key: <key>"

This endpoint settles a specific payment request which has been partially paid. Current balance (minus charges) will be sent to the address specified in toAddress.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the payment request to settle

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
payment_id_not_found
URL parameter 'ID' not found
PaymentUnderProcess The payment request is being settled, no further updates are possible
ValidationError
payment_not_ppaid
The payment is not in 'partiallyPaid' status
ValidationError
paid_not_less
The request has received sufficient payment and cannot be settled now

Extend a Specific Payment

curl "https://api.pay.bleumi.com/v1/payment/payg/2/extend"
  -X POST
  -H "x-api-key: <key>"

By default, a payment request is processed for 7 days (2 days for non-production network) from the time of payment request creation. This endpoint extends the payment request processing window by 7 days (2 days for non-production network) from the time this endpoint is called.

HTTP Request

POST https://api.pay.bleumi.com/v1/payment/payg/{ID}/extend

URL Parameters

Parameter Description
ID The ID of the payment request to settle

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
payment_id_not_found
URL parameter 'ID' not found
PaymentUnderProcess The payment request is being settled, no further updates are possible
ValidationError
payment_not_ppaid
The payment is not in 'partiallyPaid' status
ValidationError
paid_not_less
The request has received sufficient payment and cannot be settled now

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.

Ethereum Notifications

Currently, Bleumi Pay checks for incoming payments every 60 minutes. To synchronize changes in your database, you can run an hourly batch process which uses the query endpoint to fetch payment requests sorted by the last updated time.

Transactions for payment request fulfillment are delivered via webhooks.

Stellar Notifications

Bleumi Pay supports real-time notifications for payments made on the Stellar network. Due to time constraints, real-time notifications will only aggregate the last 3 transactions for a payment request.

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.

Transactions for payment request fulfillment are delivered via webhooks.

Webhook Data Model

Payment

{
  "event_type": "payment",
  "event_source": "stream",
  "payment_data": {
    "id": "2",
    "status": "partiallyPaid",
    "amountPaid": {
      "total": "9",
      "paidOnline": "9",
      "paidOffline": "0"
    }
  }
}
'

These events are sent from two systems,

Transfer

{
  "event_type": "transfer",
  "transfer_data": {
    "transferType": "stellar",
    "txHash": "cd9aade2fbe7d4d53d3584e43a7d6de441de2175110bf2fedad1699624372aa0",
    "toAddr": "GDWDREWGE2P367TMHYOL5EGUM2YOTKFPBH4UU4WPXCCZMJL6Z4J4YELK",
    "value": 4,
    "timestamp": 1560099345,
    "transferDest": "fromAddress",
    "status": "processed",
    "id": "2"
  }
}
'

These events are sent once the transaction has been confirmed on the blockchain. The schema is the same as described in get endpoint

Utility

Gas Estimate

curl "https://api.pay.bleumi.com/v1/gas/estimate?network=ropsten&addr=0xe1922b025ac05e7ee7640de4f3c5e19104cdce02"
  --H "x-api-key: <key>"

The above command returns JSON structured like this:

{
  "amount": "0.60"
}

This endpoint provides an estimate of the Ethereum Network Fee for an ERC20 Token.

HTTP Request

GET https://api.pay.bleumi.com/v1/gas/estimate

Query Parameters

Parameter Default Description
network Ethereum network used. Must be one of the supported networks
addr ERC20 token address. Must be one of the supported tokens
currency USD USD - United States Dollar
EUR - Euro

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
dest_account_not_found
Query parameter 'addr' is empty
MalformedRequest
network_not_found
Query parameter 'network' is empty
MalformedRequest
unsupported_network
The provided network is not supported
MalformedRequest
eth_address_invalid
The provided address is not a valid Ethereum address

Friendbot

This endpoint provides 10,000 tokens to any Stellar address on the test network.

curl "https://api.pay.bleumi.com/v1/friendbot?addr=GDWDREWGE2P367TMHYOL5EGUM2YOTKFPBH4UU4WPXCCZMJL6Z4J4YELK&issuer=GDWEVA6U7ZUKAWERV336BIQ7T3UNLLKSF4ENFK3GZ3Q35ZSU7SWH6AYV"
  --H "x-api-key: <key>"

HTTP Request

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

Query Parameters

Field Description
addr Stellar address to which tokens will be sent.
issuer Asset issuer. Must be one of the supported assets

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
dest_account_not_found
Query parameter 'addr' is empty
MalformedRequest
stellar_address_invalid
The provided address is not a valid Stellar address
MalformedRequest
issuer_not_found
Query parameter 'issuer' is empty
MalformedRequest
bad_issuer
Query parameter 'issuer' contains an unsupported asset
ValidationError
dest_account_not_found
The provided address does not exist on the Stellar network
ValidationError
dest_account_trustline_missing
The provided address does not have a Trustline for the asset requested

Ethereum

Bleumi Pay supports ERC20 stablecoin token payments on the Ethereum network.

Supported Ethereum Networks

You may use one of the following Ethereum networks,

Name Code
Mainnet (production) mainnet
Ropsten ropsten

Supported ERC20 Tokens

Mainnet

Name Currency Code Decimals Address
Dai v1.0 USD DAI 18 0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359
Gemini Dollar USD GUSD 2 0x056fd409e1d7a124bd7017459dfea2f387b6d5cd
Paxos USD PAX 18 0x8e870d67f660d95d5be530380d0ec0bd388289e1
TrueUSD USD TUSD 18 0x8dd5fbce2f6a956c3022ba3663759011dd51e73e
USD Coin USD USDC 6 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
Stasis EURS EUR EURS 2 0xdb25f211ab05b1c97d595516f45794528a807ad8

Ropsten

Name Currency Code Decimals Address
USD p18 USD USD18 18 0xe1922b025ac05e7ee7640de4f3c5e19104cdce02
USD p6 USD USD6 6 0x3e704967192d4824e50efded536a5642f03a7e17
USD p2 USD USD2 2 0x234ccca3f0d0c2f55d4c303480654e6620fb43e8
EUR p2 EUR EUR2 2 0x29d86b2cd5643c6fbd7c7940ceafd45ac8cd9aff

Funding for Ropsten

To test payments on the Ropsten network you can send a transfer of 0 ETH to the contract address from any Ethereum wallet. Each payment to the contract will provide the caller with 10,000 tokens.

Stellar

Bleumi Pay supports stablecoin asset payments on the Stellar network.

Please ensure your Stellar account meets the Minimum Account Balance & Trustline requirements to receive and make stablecoin asset payments. For details, please visit How to establish Stellar Trustline documentation.

Supported Stellar Networks

You may use one of the following Stellar networks,

Name Code
Public (production) public
Test test

Supported Assets

Public

Name Currency Code Issuer
White Standard Dollar USD WSD GDSVWEA7XV6M5XNLODVTPCGMAJTNBLZBXOFNQD3BNPNYALEYBNT6CE2V
Tempo EURT EUR EURT GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S

Test

Name Currency Code Issuer
USD USD USD GDWEVA6U7ZUKAWERV336BIQ7T3UNLLKSF4ENFK3GZ3Q35ZSU7SWH6AYV
EUR EUR EUR GDEQRLV3Y4TZTBSIQ76OEKCHH6O4IV266WF3TPAIUAF42APA2ASSO2UM

Funding for Test

To test payments on the Test network you can use the friendbot endpoint to request tokens for a particular address. Each request to the endpoint will provide the caller with 10,000 tokens.

Payment requests are fulfilled every 15 minutes. Please wait for 15-20 minutes before trying again.

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.