NAV
Shell

Introduction

Peach API is an easy and comfortable way of integrating with Peach Public Node. Our solution helps merchants to accept Bitcoin for their goods and services.

The current version of the API is hosted on https://hub.lightningpeach.com. It’s a mainnet implementation. However, due to the early stage of the Lightning Network, we suggest smaller transactions. The testnet version of the API is hosted on https://hub-testnet.lightningpeach.com. You can find Peach API at Swagger by the following link: https://hub.lightningpeach.com/docs/.

The API is implemented with REST. Responses are delivered as JSON objects.

Create your account

Step 1: Sign Up in Peach Secure Server

Request example:

curl https://hub.lightningpeach.com/pss/api/v1/signup \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --request POST \
  --data '{"raw_public_key_list":["ECDSA_pubkey_secp256k1_in_base64_format"]}'

POST /pss/api/v1/signup

To create a new user in the system five steps need to be accomplished.

A user creates his private and public keys in ECDSA (secp256k1) format. Key pair can be generated using ECDSA library provided by the Peach team or any other way.

ECDSA pubkey (secp256k1) in base 64 format should be registered in Peach Secure Server (PSS).

Peach Secure Service signature validation:

PSS_SIGNATURE received in the response should be verified using Peach Secure Service public key. Signature message payload contains** content

Request parameters description:

Parameter Type Description
raw_public_key_list string ECDSA pubkey (secp256k1) in base64 format

Response parameters description:

Parameter Type Description
content string Unique identifier of a created user in PSS.
pss_signature string PSS unique signature added to prove that userId is assigned by PSS.

New merchant is registered in the PSS. content and pss_signature values should be used for the next request:

{
    "user_id": {
        "content": "9y61ceUgsu6HYWsQy3jB39oH"
    },
    "pss_signature": "3045022100a5f4ff81a12b1b7221657d1d672693c7030dbcdc58dc9379cd347439680cdb83022021d33fc79801369cc5af95ec80fc7df837a07ac000ea791e761578697195617b"
}

Step 2: Sign Up in Peach Public Node

Request example:

curl https://hub.lightningpeach.com/api/v2/auth/signup \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "X-Pss-User-Id: content.pss_signature(from Step 1)" \
  --request POST \
  --data '{ "email": "[email protected]", "password": "xxxx" }'

POST /api/v2/auth/signup

When new user and his public key is registered in PSS, user can proceed and register new user in Peach Public Node.

Request parameters description:

Parameter Type Description
X-Pss-User-Id string userId.signature, userId = content value received on PSS sign up. Signature = pss_signature provided by PSS on sign up.
email string Email of a new user.
password string Password of a new user.

New merchant is registered in the system. You can find your merchant id in the response body:

{
 "merchant_id": "9y61ceUgsu6HYWsQy3jB39oH"
}

Response parameters description:

Parameter Type Description
merchant_id string Unique identifier of a created user in Peach Public Node. It should match the one provided by PSS.

Step 3: Sign In

Request example:

curl https://hub.lightningpeach.com/api/v2/auth/signin \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --request POST \
  --data '{ "email": "[email protected]", "password": "xxxx" }'

POST /api/v2/auth/signin

Creates access token. To perform any action as a merchant in Peach Public Node, an access token is needed.

Request parameters description:

Parameter Type Description
email string Email of a user.
password string Password of a user.

Response example:

{
 "merchant_id": "vm4n6maWTn9Z7xlIO71xp6vw",
 "token_type": "Bearer",
 "refresh_token": "94483d6d3f26efa3088f861316c2896a32bf4b42cb00d1c0",
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IjdMSzhMVVNWQzdUN0szM0tFSjdPNzFSTkFHSlNJMlJTMlZWMEhBSU42VTdWMFQ4RzdOTTA9PT09IiwiZXhwIjoxNTU0NTQ4ODQxfQ.LRQKmrfgt5PJbnPgr8Ys18JzhBhda0hR26m2U-SSDnY",
 "expires_at": 1554548841
}

Merchant is authorized in the system. Access token is created. One access token is valid ONLY for 1 hour.

Response parameters description:

Parameter Type Description
merchant_id string Unique identifier of a user provided when signing up.
token_type string Type of a token.
refresh_token string Refresh token is used to update access token.
access_token string Access token is used as authorization for other API methods.
expires_at string Time when token expires. The value is provided in the Unix timestamp format.

Step 4: Register public key in Peach Public Node

Request example:

curl https://hub.lightningpeach.com/api/v2/user/pubkey/add \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"pub_key": "secp256k1_public_key_in_hex_representation"}'

POST /api/v2/user/pubkey/add

A user registers his ECDSA (secp256k1) public keys in hex representation in Peach Public Node. The public key should be the same as used in Step 1 but in different representation.

Request parameters description:

Parameter Type Description
pub_key string ECDSA pubkey (secp256k1) in hex format

Response code 200 means new public key is registered in the Peach Public node.

Step 5: Merchant Setup

Request example:

curl https://hub.lightningpeach.com/api/v2/merchant \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"merchant_id":"vm4n6maWTn9Z7xlIO71xp6vw","bitcoin_address": "L4r4Fokfv6RP6q5KGA4QUc2W8CY4qZNpfB1vugkhFHJ9reh5yydt","merchant_pubkey": "0495e0e68183081862c18a7e74ceaecc13fc93ecdc94622aed97b8e6533f09d88edaca0290488eb8b8f2e9b9de678e417c4c53484956e6b3f3cf4fe1f22b7b3516","notification_url": "https://merchant.com/notifications/lightning","notification_url_for_on_chain_payment": "https://merchant.com/notifications/onchain","notification_url_for_forward_payment": "https://merchant.com/notifications/forwarding", "approve_address_signature": "merchant_signature"}'

POST /api/v2/merchant

Sets up merchant. Before using all the features and advantages of Peach API you should configure registered merchant. User should specify merchant public key, notification URLs and BTC address needed to create and receive payments.

Merchant signature

To add the merchant values to the user account, merchant should sign the request using his private key generated on sign up in PSS. PSS checks the signature and accepts or declines the request. Signature can be generated using ECDSA library provided by the Peach team or any other way. Signature payload contains merchant_id+bitcoin_address without any separators. Payload must be hashed with SHA256.

Request parameters description:

Parameter Type Description
merchant_pubkey string Mandatory. ECDSA pubkey (secp256k1).
notification_url string Mandatory. Url which the Node should use to notify merchant about lightning payment.
notification_url_for_on_chain_payment string Mandatory. Url, which the Node should use to notify merchant about on-chain payment.
notification_url_for_forward_payment string Mandatory. Url, which the Node should use to notify merchant about forward payment.
get_r_preimage_url string Url which the Node should use to get R from hash® for this merchant.
bitcoin_address string Mandatory. Bitcoin address of a merchant. This address is used by node to send funds to a merchant.
timestamp string Unix timestamp of this request.
approve_address_signature string Obligatory. Signature of this message in hex format.

The response body will contain merchant id received during registration:

{
  "id": "vm4n6maWTn9Z7xlIO71xp6vw",
  "timestamp": 1554289718
}

Congrats! Your merchant is fully set and ready to create and receive payments.

Response parameters description:

Parameter Type Description
id string Unique identifier of a merchant created when signing up.
timestamp string Unix timestamp of this response.

Errors

Error message text Description
user not found User is not registered in system
user is already registered User with the same email is already registered in the system
invalid email or password Invalid email or password on sign in
not valid email address Invalid email used for registration
invalid BTC address When user tries to set up invalid BTC address fro merchant or sub-merchant
user is already registered User with the same email is already registered in the system
invalid signature User tries to update merchant with signature that does not correspond to merchant pubkey provided on setup

Authorization

To perform any action as a merchant in Peach Public Node user should sign in to create an access token.

Validating Access Token

Request example:

curl https://hub.lightningpeach.com/api/v2/auth/validate \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --request POST \
  --data '{ "token": "access token from Sign In"}'

POST /api/v2/auth/validate

Checks whether access token is still active. Merchant should pass their access token in request.

Request parameters description:

Parameter Type Description
token string Access token from Sign In.

Response contains merchant id

{
  "merchant_id": "vm4n6maWTn9Z7xlIO71xp6vw"
}

Response parameters description:

Parameter Type Description
merchant_id string Unique identifier of a merchant. When it is present in response, it means that access token is valid. In other cases access token should be regenerated.

Generating New Access Token

Example of request (requires refresh_token of a merchant):

curl https://hub.lightningpeach.com/api/v2/auth/token/{refresh_token} \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --request POST

POST /api/v2/auth/token/{refresh_token}

Generates new access token for specific user when previous access token is expired. To run this method, you should pass a refresh token in request URL. Refresh token is provided when signing in.

Request parameters description:

Parameter Type Description
refresh_token string Valid refresh token.

Merchant is authorized in the system again. New access token is created.

{
  "merchant_id": "vm4n6maWTn9Z7xlIO71xp6vw",
  "token_type": "Bearer",
  "refresh_token": "94483d6d3f26efa3088f861316c2896a32bf4b42cb00d1c0",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IjdMSzhMVVNWQzdUN0szM0tFSjdPNzFSTkFHSlNJMlJTMlZWMEhBSU42VTdWMFQ4RzdOTTA9PT09IiwiZXhwIjoxNTU0NTQ4ODQxfQ.LRQKmrfgt5PJbnPgr8Ys18JzhBhda0hR26m2U-SSDnY",
  "expires_at": 1554548841
}

Response parameters description:

Parameter Type Description
merchant_id string Unique identifier of a user.
token_type string Type of a token.
refresh_token string Refresh token is used to update access token.
access_token string Access token is used as authorization for other API methods.
expires_in string Time when token expires. The value is provided in the Unix timestamp format.

Errors

Error message text Description
incorrect recovery token Recovery token does not match access token
token is expired Access token expired
token already used Refresh token already used
token not found Access tocken can not be found on sign in

Payment Invoice

Once your merchant is created and set, you are ready to create and receive payments with Peach Public Node.

Signature validation

curl https://hub.lightningpeach.com/api/v2/hub/pubkey \
--header "accept: application/json"
curl https://hub.lightningpeach.com/pss/api/v1/pss/public_key \
--header "accept: application/json"

To prevent invoice substitution by attackers Peach Secure Service and Peach Public Node signs invoices generated by them. We recommend all integrators implement signature check logic. To check signatures user should retrieve Peach Secure Service and Peach Public Node public keys.

GET /api/v2/hub/pubkey

GET /pss/api/v1/pss/public_key

When public keys are retrieved user should check each message payload and signature using corresponding public key. Peach team uses ECDSA(Elliptic Curve Digital Signature Algorithm) with secp256k1 (256-bit elliptic curve) digital signature scheme like in bitcoin.

Here is the library example for Javascript: Fast Elliptic Curve Cryptography in plain javascript

Lightning Payment Request

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/lightning \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"amount": 20000,"expiry": 2000,"description": "Lightning payment"}'

POST /api/v2/payment/lightning

Creates payment request for Lightning network to receive lightning payments by merchant.

Peach Public Node and peach Secure Service signature validation:

PSS_SIGNATURE and HUB_SIGNATURE received in the response should be verified using Peach Secure Service and Peach Public Node public keys accordinly. Signature message payload contains r_hash(encoded in HEX format)+payment_request+merchant_id without any separators

Request parameters description:

Parameter Type Description
merchant_id string Unique identifier of a merchant.
amount string Mandatory. Amount in satoshi.
description string Description of a payment attached to invoice.
expiry int Expiration time for a new invoice. Value in seconds. If value is not specified, the default value is 3600 seconds.
timestamp int Unix timestamp when invoice was requested.
ntfn_url string Custom notification url for payment, which overwrites url defined in merchant configuration.

To fulfill this payment request, user should have open channel to Peach Public Node or have sibling channels to our node.

Peach Public Node charges merchant 1% of amount or 1 satoshi for payment processing. Fee and amount without fee are displayed in lightning payment notification

Response body contains lightning payment request and rhash:

{  
  "payment_request":"lntb200u1pw2vg9vpp5f8dmjqygszlqa8clt09grfd2k9hnf389vcgmwzmhz9lzy9ruq6tqdq4w3jhxapqvdex2ct5d9hkucqzysxqrp7s3jtc0zz06pta8h7hfpra0njvwt27cekaq74269x86fftx2t5f62zmt92u5d94640chd9tdz3ax8wcep95s6lvwvjks30l550rvaqcxgq8lwe2j",
  "r_hash":"49dbb9008880be0e9f1f5bca81a5aab16f34c4e56611b70b77117e22147c0696",
  "creation_time":1554391212,
  "expiry":2000,
  "timestamp":1554391212,
  "pss_signature":"304402204ce483174a98a2b83ae35541bd1114956e163ec8d5071fdd4bce1d8cc7f68cab02203c9279bc343aed096ba20f46323e760d96bf55295122161c4cfdf80301ec56c1",
  "hub_signature":"304402200fac41d0939033a26c3a2cf05d0f44fff18fbf6928b340cdc53c7a957f661492022079f069d952079c34fbdbe3b1141e03ce86eb5ea2584a19db8bbb4fb81615a8e5"
}

When payment request is settled and the “ntfn_url” parameter was not specified within request, merchant receives notification by notification URL mentioned on merchant setup. Notification will contain next data:

{
  "amount":20000,
  "description":"Lightning payment",
  "creation_date":1554298230,
  "expiry":2000,
  "settle_date":1554298272,
  "settled":true,
  "payment_request":"lntb200u1pw2vg9vpp5f8dmjqygszlqa8clt09grfd2k9hnf389vcgmwzmhz9lzy9ruq6tqdq4w3jhxapqvdex2ct5d9hkucqzysxqrp7s3jtc0zz06pta8h7hfpra0njvwt27cekaq74269x86fftx2t5f62zmt92u5d94640chd9tdz3ax8wcep95s6lvwvjks30l550rvaqcxgq8lwe2j",
  "r_hash":"49dbb9008880be0e9f1f5bca81a5aab16f34c4e56611b70b77117e22147c0696",
  "fee":200,
  "amount_without_fee":19800
}

Response parameters description:

Parameter Type Description
payment_request string Encoded payment request for lightning payment.
r_hash string Random hash number for created payment request.
creation_time int Unix timestamp of payment creation.
expiry int Expiration time for current payment request. Value in Unix timestamp.
timestamp int Unix timestamp when invoice was requested.
pss_signature string Signature provided by Peach Secure Service.
hub_signature string Signature provided by Peach Public Node.

Below there is a diagram showing the flow of lightning payment, where PEACH is Peach Public Node.

Lightning payment diagram

Lightning Payment Request with Custom Notification Url

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/lightning \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"amount": 20000, "expiry": 2000, "ntfn_url": "https://merchant.com/notifications/lightning_new", "description": "Lightning payment"}'

Merchant can define where to receive notifications in each invoice. For this merchant should specify “notification_url” when creating lightning payment.

Response body will contain lightning payment request and rhash as well. When payment is settled, merchant will receive notification to new URL specified on payment creation.

Requesting Status of Lightning Payment Request

Example of request (requires rhash of Lightning payment):

curl https://hub.lightningpeach.com/api/v2/payments/{rhash}\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET

GET /api/v2/payment/lightning/{rhash}

Shows created lightning payment request by its RHash. RHash is a unique identifier of lightning payment which is assigned during its creation.

Response contains information of one requested lightning payment:

{
    "amount": 20000,
    "description": "Lightning payment",
    "creation_date": 1554298230,
    "expiry": 2000,
    "settle_date": 1554298272,
    "settled": true,
    "payment_request": "lntb200u1pw2vg9vpp5f8dmjqygszlqa8clt09grfd2k9hnf389vcgmwzmhz9lzy9ruq6tqdq4w3jhxapqvdex2ct5d9hkucqzysxqrp7s3jtc0zz06pta8h7hfpra0njvwt27cekaq74269x86fftx2t5f62zmt92u5d94640chd9tdz3ax8wcep95s6lvwvjks30l550rvaqcxgq8lwe2j",
    "r_hash": "{rhash from tne request}",
    "fee": 200,
    "amount_without_fee": 19800
}

Response parameters description:

Parameter Type Description
amount string Amount in satoshi.
description string Description of a payment attached to invoice.
creation_date string Unix timestamp when invoice was added to the system.
expiry string Expiration time for created invoice. Value in seconds.
settled bool Parameter to identify this invoice has been fulfilled.
settle_date int Unix timestamp when invoice is fulfilled.
payment_request string Encoded payment request for lightning payment.
rhash string Hex encoded hash® of a payment.
wihtdraw_tx string Unique identifier of withdraw transaction. It is specified only when merchant sent their balance to their BTC address using ‘Balance withdrawal’ API method.
fee string Amount of fee taken by the Node.
amount_without_fee string Amount of payment without fee. Specified in satoshi.

Retrieving List of All Created Lightning Payment Requests

Request example:

curl https://hub.lightningpeach.com/api/v2/payments/lightning\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET

GET /api/v2/payments/lightning

This method allows to retrieve a list of created invoices with all information related to them.

Response contains all lightning payments created by merchant:

{  
  "payments":[  
    {  
      "amount":20000,
      "description":"Lightning payment",
      "creation_date":1554298230,
      "expiry":2000,
      "settle_date":1554298272,
      "settled":true,
      "payment_request":"lntb200u1pw2vg9vpp5f8dmjqygszlqa8clt09grfd2k9hnf389vcgmwzmhz9lzy9ruq6tqdq4w3jhxapqvdex2ct5d9hkucqzysxqrp7s3jtc0zz06pta8h7hfpra0njvwt27cekaq74269x86fftx2t5f62zmt92u5d94640chd9tdz3ax8wcep95s6lvwvjks30l550rvaqcxgq8lwe2j",
      "r_hash":"49dbb9008880be0e9f1f5bca81a5aab16f34c4e56611b70b77117e22147c0696",
      "fee":200,
      "amount_without_fee":19800
    },
    {  
      "amount":20000,
      "description":"Lightning payment new notification URL",
      "creation_date":1554298230,
      "expiry":2000,
      "payment_request":"lntb200u1pw2h8n3pp5zgu7xgq04xxr9qhszxsgry4cw6enxrlhyl28n37hjc3kvqyrhrrsdq4w3jhxapqvdex2ct5d9hkucqzysxqrp7sdqqr4w3jekqmhqfwkm4ykj0qn5tu8n7wqsc9h9yrpm8h3f3kla79vgddyv0eg5xg9p7yeu8dg39c4j3d7sdk3mwsd0vw0j94sdsgnqgqfynxj2",
      "r_hash":"1239e3200fa98c3282f011a08192b876b3330ff727d479c7d79623660083b8c7",
      "fee":200,
      "amount_without_fee":19800,
      "ntfn_url":"https://merchant.com/notifications/lightning_new"
    }
  ]
}

Response parameters description:

Array of payments – List of created payments in the Node:

Parameter Type Description
amount string Amount in satoshi.
description string Description of a payment attached to invoice.
creation_date string Unix timestamp when invoice was added to the system.
expiry string Expiration time for created invoice.
settle_date string Unix timestamp when invoice was fulfilled.
settled string Specifies whether payment was fulfilled.
payment_request string Encoded payment request.
rhash string Hex encoded hash® of a payment.
withdraw_tx string Unique identifier of withdraw transaction. It is specified only when merchant sent his balance to his BTC address using ‘Balance withdrawal’ API method.
fee string Amount of fee taken by the Node.
amount_without_fee string Amount of payment without fee. Specified in satoshi.

On-Chain Invoice with Open Amount

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/on_chain_open_amount \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"description": "invoice with open amount","ntfn_url": "http://10.2.2.233:9999"}'

POST /api/v2/payment/on_chain_open_amount

Creates payment invoice to receive payments by on-chain. Each on-chain payment invoice is assigned to its unique BTC address provided in response body.

Peach Public Node and peach Secure Service signature validation:

PSS_SIGNATURE and HUB_SIGNATURE received in the response should be verified using Peach Secure Service and Peach Public Node public keys accordinly. Signature message payload contains btc_address+merchant_id without any separators

Request parameters description:

Parameter Type Description
description string Description of a payment.
ntfn_url string Notification URL for this transaction. If not specified, notification url from merchant configuration is used.

Peach Public Node charges merchant 1% of amount or 1 satoshi for payment processing. Fee and amount without fee are displayed in on-chain payment notification.

Response contains only BTC address, where payment can be fulfilled:

{
"btc_address":"tb1q0nakp2fef0v90xr4y2e9xlf9z5dnv9h6m0f6du",
"pss_signature":"304402204ce483174a98a2b83ae35541bd1114956e163ec8d5071fdd4bce1d8cc7f68cab02203c9279bc343aed096ba20f46323e760d96bf55295122161c4cfdf80301ec56c1",
"hub_signature":"304402200fac41d0939033a26c3a2cf05d0f44fff18fbf6928b340cdc53c7a957f661492022079f069d952079c34fbdbe3b1141e03ce86eb5ea2584a19db8bbb4fb81615a8e5"
}

To settle this payment request, user should send any amount to BTC address provided by Peach Public Node. The payment settlement requires 1 block confirmation, merchant will receive notification by notification URL mentioned on merchant setup or within this request. Notification will contain next data:

{  
  "payment_id":"1de97d051f25f5b00874c301a03f35f68bec28556c024a2b",
  "amount":20000,
  "description":"test invoice without amount",
  "fee":0,
  "amount_without_fee":20000,
  "tx":["565c99f5625cc10e52f1797a11259c02b5930c281a82682e646c1a8158b70a42"],
  "type":"success",
  "bitcoin_address":"tb1q0nakp2fef0v90xr4y2e9xlf9z5dnv9h6m0f6du"}
}

Response parameters description:

Parameter Type Description
btc_address string BTC address for sending funds on-chain.
pss_signature string Signature provided by Peach Secure Service.
hub_signature string Signature provided by Peach Public Node.

On-Chain Invoice with Set Amount

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/on_chain \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"amount": 20000,"description": "Onchain payment"}'

POST /api/v2/payment/on_chain

Creates payment invoice to receive payments by on-chain. Each on-chain payment invoice sets specific amount and is assigned to its unique BTC address provided in response body.

Peach Public Node and peach Secure Service signature validation:

PSS_SIGNATURE and HUB_SIGNATURE received in the response should be verified using Peach Secure Service and Peach Public Node public keys accordinly. Signature message payload contains btc_address+merchant_id without any separators

Request parameters description:

Parameter Type Description
merchant_id string Mandatory. Unique identifier of a merchant.
amount string Mandatory. Amount in satoshi.
description string Description of a payment.
ntfn_url string Notification URL for this transaction. If not specified, notification url from merchant configuration is used.

Peach Public Node charges merchant 1% of amount or 1 satoshi for payment processing. Fee and amount without fee are displayed in on-chain payment notification.

Response contains only BTC address, where payment can be fulfilled:

{
"btc_address":"tb1qzesnayx603wj4u5e0q5csdz5n7mv6mgprr62c8",
"pss_signature":"304402204ce483174a98a2b83ae35541bd1114956e163ec8d5071fdd4bce1d8cc7f68cab02203c9279bc343aed096ba20f46323e760d96bf55295122161c4cfdf80301ec56c1",
"hub_signature":"304402200fac41d0939033a26c3a2cf05d0f44fff18fbf6928b340cdc53c7a957f661492022079f069d952079c34fbdbe3b1141e03ce86eb5ea2584a19db8bbb4fb81615a8e5"
}

To settle this payment request, user should send requested amount to BTC address provided by Peach Public Node. The payment settlement requires 1 block confirmation, merchant will receive notification by notification URL mentioned on merchant setup or within this request. Notification will contain next data:

{  
  "amount":20000,
  "description":"test onchain",
  "fee":200,
  "amount_without_fee":19800,
  "type":"success",
  "bitcoin_address":"tb1qzesnayx603wj4u5e0q5csdz5n7mv6mgprr62c8"
}

Response parameters description:

Parameter Type Description
btc_address string BTC address for sending funds on-chain.
pss_signature string Signature provided by Peach Secure Service.
hub_signature string Signature provided by Peach Public Node.

On-Chain Invoice with Custom Notification Url

Request example:

curl https://hub.lightningpeach.comapi/v2/payment/on_chain \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"amount": 20000,"ntfn_url": "https://merchant.com/notifications/onchain_new","description": "Onchain payment"}'

Merchant can define where to receive notifications for each payment. To make it possible merchant should specify “notification_url” for on-chain payment creation method.

Response body will contain BTC address as well. When payment is settled, merchant will receive notification to new URL specified on payment creation.

Retrieving List of Created On-Chain Invoices

Request example:

curl https://hub.lightningpeach.com/api/v2/payments/on_chain\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET
}

GET /api/v2/payments/on_chain

Retrieves list of created on-chain payments with all related information.

Response contains all on-chain payments created by merchant.

{  
  "payments":[  
    {  
      "amount":"20000",
      "description":"test onchain",
      "merchant_id":"7LK8LUSVC7T7K33KEJ7O71RNAGJSI2RS2VV0HAIN6U7V0T8G7NM0====",
      "status":"Settled",
      "fee":"200",
      "amount_without_fee":"19800",
      "withdraw_tx":"",
      "btc_address":"tb1qzesnayx603wj4u5e0q5csdz5n7mv6mgprr62c8",
      "ntfn_url":"https://merchant.com/notifications/onchain"
    },
    {  
      "amount":"20000",
      "description":"test onchain new notification URL",
      "merchant_id":"7LK8LUSVC7T7K33KEJ7O71RNAGJSI2RS2VV0HAIN6U7V0T8G7NM0====",
      "status":"Pending",
      "fee":"200",
      "amount_without_fee":"19800",
      "withdraw_tx":"",
      "btc_address":"tb1qte689gt9mrf8vup567hfvu47rx49ncfd9tpymm",
      "ntfn_url":"https://merchant.com/notifications/onchain_new"
    }
  ]
}

Response parameters description:

Array of payments – List of created on-chain payments within the Node.

Parameter Type Description
amount string Amount in satoshi.
description string Description of on-chain payment.
merchant_id string Unique identifier of a merchant, payment recipient.
status string Status of payment. Possible values: created, paid or error.
fee string Amount of a fee received by the Node.
amount_without_fee string Amount without fee, exact amount that will be received by merchant.
withdraw_tx string Hash of withdraw transaction. If the value is empty than there was no withdraw.
btc_address string Bitcoin address for receiving funds.
ntfn_url string Notification url.

Errors

Error message text Description
cannot pay to self Merchant cannot send lightning payment or internal payment to self
not enough funds to complete payment Merchant tries to send more than the funds he owns
merchant does not exist Merchant cannot send internal payment to not valid merchant id
wrong destination There is no path to user by lightning. Merchant cannot sends payment to user who does not have lightning channels
expiry is too small, minimal allowed is **, got: ** Expiry set on payment creation is less than 10 seconds
expiry is too big, maximum allowed is **, got: ** Expiry set on payment creation is more than 3600 seconds

Not Fully Paid On-Chain Invoice

Making the first Bitcoin payment can be quite challenging for a new user. The first step requires to find proper wallet or service, then to install and setup them. The second one demands from a user to pay the exact amount to buy any service or product. And this very step can be tricky for them.

Let’s consider two different scenarios for a case when a user sends less than required amount of payment.

The first scenario is the following:

User wants to buy a product from merchant and pays 13 amount of invoice. Paid amount is blocked. Merchant sees underpaid invoice and informs user that invoice is not fully paid. User decides not to pay the rest of invoice amount. Merchant sees that invoice is still not fully paid and decides to cancel invoice. Paid amount is returned to user. The notification flow of such scenario is shown on the diagram below:

On-chain not fully paid payment diagram

The second scenario is more complicated but has a positive outcome after all:

User wants to buy a product from merchant and pays 13 amount of invoice. Paid amount is blocked. Merchant sees that invoice is not fully paid and notifies a user about the rest amount that should be paid. User makes extra payment but amount is still less than initial invoice amount. Merchant now sees that total paid amount is equal 12 of required amount. Merchant notifies user again about the rest amount that should be paid. User pays the rest amount. Now invoice is fully paid. User receives notification about successful settlement and now can get the product from merchant. The notification flow of this scenario is shown below:

On-chain not fully paid payment settlement diagram

Getting Locked Balance

Request example:

curl https://hub.lightningpeach.com/api/v2/merchant/balance/locked\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET

GET /api/v2/merchant/balance/locked

Retrieves locked balance of a merchant.

Balance can be locked in case some merchants invoices are partially paid. That means the invoice is not in status Settled, so the incoming funds referred to the partially paid invoices are stored in Locked balance. Merchant receives the notification when invoice is partially paid.

When the invoice is fully paid and moves to status Settled, the funds from Locked balance is transferred to Merchants balance.

Response contains merchant balance in satoshi:

{"balance":"60000"}

Response parameters description:

Parameter Type Description
balance string Locked merchant balance in satoshi.

Refunding Partially Paid On-Chain Invoice

Request example:

curl https://hub.lightningpeach.comapi/v2/payment/on_chain/cancel \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{"btc_address": tb1qzesnayx603wj4u5e0q5csdz5n7mv6mgprr62c8,"refund_btc_address": "tb1qte689gt9mrf8vup567hfvu47rx49ncfd9tpymm"}'

POST /api/v2/payment/on_chain/cancel

Allows merchant to return funds to user when there is partially paid on-chain invoice.

Request parameters description:

Parameter Type Description
btc_address string BTC address from which refund is taken.
refund_btc_address string BTC address to which refund amount should be sent.

Response example:

{"refund_txtd":"88bc1d09sdjfk33ee03c268131d10d63j3j3l3jl3j5aafab737e90bc4e"}

Response parameters description:

Parameter Type Description
refund_txtd string Blockchain transaction ID, which contains requested payment.

Outgoing payment

Outgoing Internal Payment

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/internal \
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}" \
  --header "X-Signature: {merchant_signature}" \
  --request POST \
  --data '{"amount": "100","description": "Internal payment 100", "destination": "VTA8HF78MMV101LDA8HVI0D7RK9BTOQE7MSKQ23JOCUVOS9QLR7G===="}'

POST /api/v2/payment/internal

Internal payment is a payment between two merchants. Merchants do not need channels between each other to send payment. Both merchants should be registered in the Peach Public Node system.

Merchant signature

Merchant should sign the request using their private key generated on sign up in PSS. PSS checks the signature and accepts or declines the request. The signature can be generated using ECDSA library provided by the Peach team or any other way. The signature payload contains amount+destination without any separators. The payload must be hashed with SHA256.

Peach Public Node doesn’t charge any fees for internal payment processing.

Request parameters description:

Parameter Type Description
amount string Mandatory. Amount in satoshi.
description string Description of payment.
destination string Mandatory. Merchant ID of internal payment recipient.

Response code 200 means that internal payment is successful. No errors should be shown in response body.

Outgoing Lightning Payment

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/outgoing/lightning\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}" \
  --header "X-Signature: {merchant_signature}" \
  --request POST \
  --data '{"payment_request": "lntb100n1pwa2yyqpp5r4cr3tuy2a20jczlkhcwqnp0vqsgzqrp3zr486yy2ejkd4jhfa8sdqqcqzpghw4leva96c68phd63j8t0pm6asqh6ayhxr7q6q6lqh7zasg70g494pglgvy2c0884q9889rqr8p67c70282l085l9wuwwf4x9jhaakqpjwtv5g","amount": "10","ntfn_url": "http://notification.url/"}'

POST /api/v2/payment/outgoing/lightning Lightning payment is an instant payment between two users in Lightning Network. Peach Public Node manages channels that allow to send payments within Lightning Network.

Merchant signature

Merchant should sign the request using their private key generated on sign up in PSS. PSS checks the signature and accepts or declines the request. The signature can be generated using ECDSA library provided by the Peach team or any other way. The signature payload contains amount+payment_request without any separators. The payload must be hashed with SHA256.

Request parameters description:

Parameter Type Description
amount string Mandatory. Amount in satoshi.
description string Description of payment.
payment_request string Mandatory. Lightning payment request provided by the third party to fulfill.
ntfn_url string Notification URL to receive the payment status update.

Response example:

{
  "payment_id":"6866d78da7fac35f86f653d1b433279099121856a95b7e74",
  "converted_to_internal":false
}

Response parameters description:

Parameter Type Description
payment_id string Internal payment identifier in the system
converted_to_internal string Identifier to check whether payment is managed as internal payment. It is possible when a  provided lightning payment request generated by Peach Public Node user.

Outgoing On-Chain Payment

Request example:

curl https://hub.lightningpeach.com/api/v2/payment/outgoing/on_chain\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}" \
  --header "X-Signature: {merchant_signature}" \
  --request POST \
  --data '{"destination": "2N3PzMYoLud9bKkd34SKnjy5WA44jSge1rG","amount": "10","blocks": 0,"description": "string","ntfn_url": "http://notification.url/"}'

POST /api/v2/payment/outgoing/on_chain On-chain transactions refer to those cryptocurrency transactions which occur on the Bitcoin blockchain - that is, on the records of the blockchain - and remain dependent on the state of the blockchain for their validity. All such on-chain transactions occur and are considered to be valid only when the blockchain is modified to reflect these transactions on the public ledger records.

Merchant signature

Merchant should sign the request using their private key generated on sign up in PSS. PSS checks the signature and accepts or declines the request. The signature can be generated using ECDSA library provided by the Peach team or any other way. The signature payload contains amount+destination without any separators. The payload must be hashed with SHA256.

Request parameters description:

Parameter Type Description
amount string Mandatory. Amount in satoshi.
description string Description of payment.
blocks integer Blocks that is required for confirmation. It determines fee of transaction.
destination string Mandatory. BTC address of the receiver of the funds.
ntfn_url string Notification URL to receive the payment status update.

Response example:

{
  "payment_id":"6866d78da7fac35f86f653d1b433279099121856a95b7e74"
}

Response parameters description:

Parameter Type Description
payment_id string Internal payment identifier in the system.

Websocket Notifications

Javascript Starter Template:

const connectionUrl = `wss://${BASE_URL}/api/v2/user/messages/subscribe`;
const ws = new WebSocket(connectionUrl, [token_type, access_token]);
ws.on("message", function incoming(data) {
    console.log("received message");
    console.log(data);
});
ws.on("open", function open() {
    ws.send("{}");
});

GET /api/v2/payments/subscribe.

Another way to receive notifications is using WebSockets protocol. We recommend to use WebSocket protocol instead of receiving notification to notification_URL to achieve asynchronous messaging. Secure WebSocket connection (WSS) need to be established to receive notifications.

Lightning notification:

{"result":
  {"ntfn_type":"lightning",
    "lightning_payment_status":
    {"amount":"100",
      "description":"test creation",
      "creation_date":"1569399587",
      "expiry":"3600",
      "settle_date":"1569399716",
      "settled":true,
      "payment_request":"lnbc1u1pwckgerpp5jsavwcv93jgyjxnaptf6p3trx0pd8gxdl6xmr98sm8h7ssfrj9uqdq4w3jhxapqvdex2ct5d9hkucqzpgxqrrssr05a8lvqr9wr65h6jcn9j30tu3d6ft80yla043vd7qmexdhuaxfrpl5f7ym9easavdf37s6env9egv4kc7w35drg49dcnejnk3pyrpqp2v8peq",
      "r_hash":"943ac761858c90491a7d0ad3a0c56333c2d3a0cdfe8db194f0d9efe841239178",
      "fee":"1",
      "amount_without_fee":"99"
      }}}}  

On-chain notification:

{"result":
  {"ntfn_type":"on_chain",
    "on_chain_payment_status":
    {"amount":"20000",
      "description":"test onchain",
      "fee":"200",
      "amount_without_fee":"19800",
      "bitcoin_address":"bc1qz8m4cl2gqzp0r48xkc4en33yktrgak28a888v5"
      }}}

Forward notification:

{"result":
  {"payment":
    {"payment_id":"ae02e69cc3697664efbf4649a1741463fbd67ca9bc72f34b",
      "payment_type":"FORWARD",
      "forward":{
        "payment_id":"ae02e69cc3697664efbf4649a1741463fbd67ca9bc72f34b",
        "merchant_bitcoin_address":"2NG6GbG5SQxmu896892qJE8FJo1g8WDUMsJ",
        "amount":"20000",
        "status":"Settled",
        "hade_pay_fee_in_percents":50,
        "extra_data":"test forward",
        "merchant_id_for_fee_collection":"ML28EGS90ENO396EPQ07229IDTQAB36RLSQP3NF9RDQ2K847CJ2G====",
        "hub_fee":"200",
        "hade_pay_fee":"10000",
        "amount_without_fee":"9800",
        "our_bitcoin_address":"tb1q3g56qv9gu5060lxc2kxg95dl9snxmy73zvaj7c",
        "ntfn_url":"http://test.test",
        "created_at":1568813496}}}}    

Notification about partial payment:

{"result":
  {"payment":
    {"payment_id":"db83126d6cf53e64743d27e568015866d8f3f7fb651c1388",
      "payment_type":"PARTIAL",
      "partial":{
        "payment_id":"db83126d6cf53e64743d27e568015866d8f3f7fb651c1388",
        "btc_address":"tb1qnsf49u7dmsclpq2urrfcjdwun973zwlm5gnwk7",
        "already_paid_amount":"20000",
        "merchant_id":"ML28EGS90ENO396EPQ07229IDTQAB36RLSQP3NF9RDQ2K847CJ2G====",
        "status":"Pending",
        "created_at":1568815366
        }}}}

Notification types

Parameter Description
lightning Notification for incoming lightning payment.
on_chain Notification for incoming on-chain payment.
forward Notification for incoming forward payment.
partial Notification for received less amount than was requested by on-chain.

Merchant Balance Management

Getting Merchant’s Balance

Request example:

curl https://hub.lightningpeach.com/api/v2/merchant/balance\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET

GET /api/v2/merchant/balance

Retrieves current balance of a merchant.

Response contains merchant balance in satoshi:

{"balance":"60000"}

Response parameters description:

Parameter Type Description
balance string Merchant balance in satoshi.

Withdrawing Funds

Request example:

curl https://hub.lightningpeach.com/api/v2/merchant/withdraw\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request POST \
  --data '{}'

POST /api/v2/merchant/withdraw

This method allows to withdraw all merchant funds at ones. Withdrawal is an on-chain transaction where total balance in satoshi is sent to merchant’s BTC address specified on merchant setup.

System collects all withdrawal transactions for 10 minutes and sends all of them as one on-chain transaction to Mining pool.

Response contains withdrawal transaction id and the total amount in satoshi that were sent:

{
  "id":"91ccabc337c50f7aeaaa2ee5ec612af59937e590dbd818a2",
  "tx":"",
  "amount":"12250"
}

Response parameters description:

Parameter Type Description
id string The identifier of withdrawal transaction within the System.
tx string Hash of bitcoin transaction sent from the Node to a merchant. Usually is empty because withdrawals are sent to tne Mining pool once in 10 minutes
amount string Amount of transaction in satoshi.

Requesting Status of Withdraw Transaction

Request example:

curl https://hub.lightningpeach.com/api/v2/merchant/withdraw/3443\
  --header "Content-Type: application/json" \
  --header "cache-control: no-cache" \
  --header "Authorization: Bearer {access_token}"\
  --request GET

GET /api/v2/merchant/withdraw/{id}

This method allows to get status of withdraw transaction.

Response example:

{
  "id": "3443",
  "merchant_id": "7LK8LUSVC7T7K33KEJ7O71RNAGJSI2RS2VV0HAIN6U7V0T8G7NM0====",
  "sent_amount": "2000000",
  "sent_tx": "88bc1d09c6e1c0a8ee03c26812k410d69b9045568884949f5aafab737eso3c4e",
  "btc_address": "tb1qzesnayx603wj3u5e0q5csdz5n7mv6mgprr62c8",
  "status": "Withdrawn",
  "withdrawn_at": "2019-09-20T08:22:35.661Z",
  "created_at": "2019-09-20T08:22:35.661Z"
}

Response parameters description:

Parameter Type Description
id string Unique identifier of registered withdraw request.
merchant_id string Unique identifier of merchant that requested withdraw.
sent_amount string Amount of funds sent from hub to merchant. Value in Satoshi.
sent_tx string Unique identifier of transaction published to on-chain.
btc_address string BTC address registered on time of requested withdraw.
status string Status of withdraw. Possible values: Pending, Processing, Withdrawn, Canceled.
withdrawn_at string Time when withdraw was applied.
created_at string Time when withdraw was requested by merchant.

Errors

Error message text Description
internal inconsistency with merchant balance The withdrawal cannot be made due to some internal error, contact development team to investigate
amount to withdraw: ** is less than minimum allowed: ** The withdrawal cannot be made if amount is less than 1000 Satoshi

Error codes

The Peach API responds in an uniform way to all errors, HTTP codes are mapped to the following meaning:

Error example:

{
  "error":"cannot get merchant: rpc error: code = Unknown desc = cannot load merchant: not found",
    "code":2,
    "message":"cannot get merchant: rpc error: code = Unknown desc = cannot load merchant: not found",
    "details":[]
  }
Error Code Error Name Description
400 Bad Request Your request contains malformed or missing parameters
401 Unauthorized Wrong or no auth supplied
404 Not Found The specified method could not be found.
500 Internal Server Error We had a problem with our server. Try again later.