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

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"
}

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.

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:

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:

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 ¹⁄₃ 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 ¹⁄₃ 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 ¹⁄₂ 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

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.

Introduction

Create your account

Step 1: Sign Up in Peach Secure Server

Step 2: Sign Up in Peach Public Node

Step 3: Sign In

Step 4: Register public key in Peach Public Node

Step 5: Merchant Setup

Errors

Authorization

Validating Access Token

Generating New Access Token

Errors

Payment Invoice

Signature validation

Lightning Payment Request

Lightning Payment Request with Custom Notification Url

Requesting Status of Lightning Payment Request

Retrieving List of All Created Lightning Payment Requests

On-Chain Invoice with Open Amount

On-Chain Invoice with Set Amount

On-Chain Invoice with Custom Notification Url

Retrieving List of Created On-Chain Invoices

Errors

Not Fully Paid On-Chain Invoice

Getting Locked Balance

Refunding Partially Paid On-Chain Invoice

Outgoing payment

Outgoing Internal Payment

Outgoing Lightning Payment

Outgoing On-Chain Payment

Websocket Notifications

Merchant Balance Management

Getting Merchant’s Balance

Withdrawing Funds

Requesting Status of Withdraw Transaction

Errors

Error codes