Getting Started

We provide API in two different flavors: REST and gRPC.

With either one, you can easily create an invoice with a dedicated cryptocurrency address which your customer will send funds to, and then track its status.

Prerequisites

To do this, you will first need to create an API Key. You can create one in Settings panel after logging in. You can also invalidate an existing API key when necessary. But please be aware that invalidating an API key will take effect immediately and any subsequent request with that key will fail. So always double check if the key is still in use by any of your service before invalidating it.

Then you will need a working e-commerce website with a publicly accessible address. Either a domain or an ip address is acceptable. You will need to set up an url endpoint to receive the notifications from Payscrypt on invoice status changes.

Workflow using Payscrypt Payment UI

Your site calls create_order to create an invoice, and gets back an invoice id.
Your site redirects or opens up a blank page to Payscrypt Payment UI url with the invoice id to allow user payment.
Your site gets a webhook callback when the invoice status changes (no matter it’s paid for or expired)
Your site calls get_public_order to verify the invoice status and do the rest of the processing.

Workflow using your own UI

Your site calls create_order to create an invoice, and gets back the invoice id with cryptocurrency address.
Your site shows the address and all the necessary information to allow user payment.
Your site gets a webhook callback when the invoice status changes (no matter it’s paid for or expired)
Your site calls get_public_order to verify the invoice status and do the rest of the processing.

Customize Your Own Payment UI

We will opensource our Payment UI module. So you can easily customize on top of it or use it as a reference to build your own. Please see the documentation inside the repo.

Coming Soon

Integration

Currently we provide integration for following e-commerce solutions. Usually it just requires some simple installation and tweaking to get it going. Please find the details inside each repo.

Woocommerce

Authentication

Some of the APIs require the API Key to be included in the request.

For http, a header should be present:

apikey: {{APIKEY}}

For gRPC, a key-value pair should be present in the metadata:

apikey: {{APIKEY}}

API

gRPC

gRPC API Endpoint: https://payscrypt.com

Use the following to proto file to generate your clent stub.

pg-api.proto

REST

REST API Base: https://payscrypt.com

For REST requests, POST data in application/json format. Return code and message will be in response headers as follows while data will be in response body. The HTTP response code is also mapped accordig to gRPC error codes. See grpc-gateway for details of gRPC to HTTP mapping.

// Return code and message in HTTP headers grpc-code: ... grpc-message: ...

Types and Constants

Order

Order represents an order/invoice related to a merchant order.

Field	Type	Label	Description
id	string		Unique order ID.
type	Order.Type		Order type.
asset_name	string		Asset name.
target_value	string		Value to be paid in this order.
target_confirmations	int64		Confirmations needed by this order.
variants	string	repeated	Receiving address variants (usually use the first).
expired_at	int64		The timestamp this order expired (or will expire) at.
merchant_order_id	string		Merchant order ID.
description	string		Order description.
status	Order.Status		Order status.
value	string		Value received by this order up to now.
confirmations	int64		Order confirmations
created_at	int64		Order created time.
updated_at	int64		Order updated time.
chain	string		The chain of this order.
network	string		The network of this order.
callback_url	string		Callback url on the merchant site to redirect user to when an order is in a final state.
redirect_url	string		redirect url of Payment UI for user to proceed after creating an order

Order.Type

Order type, reserved for future use, and always "NORMAL" now.

Name	Number	Description
NORMAL	0	Order is normal.

Order.Status

Order status.

Name	Number	Description
PENDING	0	Order is pending (waiting for enough payment value).
CONFIRMING	1	Order is confirming, (waiting for enough confirmations).
SUCCESSFUL	2	Order is successful.
EXPIRED	3	Order is expired.
CANCELED	4	Order is canceled.

WebhookOrder

Data received from a webhook.

Field	Type	Description
id	int64	Unique order ID.
pg_wallet_id	int64	Wallet ID.
merchant_order_id	string	Merchant order ID.
status	Order.Status	Order status.

Error Codes

TBD

Private API

These APIs require authentication

createOrder

Creates an order/invoice.

Params

Field	Type	Description
merchant_order_id	string	Merchant order ID.
asset_name	string	Asset name.
target_value	string	Value to be paid.
callback_url	string	Callback url.
pg_wallet_id	int64	Wallet ID.

Return Value

Field	Type	Label	Description
order	Order		The created order.

Public API

These APIs are intended for browsers to call on behalf of your users. Thus they don’t require authentication and return only limited information.

getPublicOrderById

Returns the information of an order/invoice.

Params

Field	Type	Label	Description
id	string		Order ID.
with_payments	bool		Whether return related payments.

Return Value

Field	Type	Label	Description
order	PublicOrder		Details of order.

Notification

Webhook

You can set up one or more webhooks in Settings panel to receive order changes. The webhook urls have to be publicly accessible.

Only limited data will be sent over webhook. See WebhookOrder for details. The data will be sent by a POST to the webhook url as application/json.

Please DO NOT completely rely on data from webhook notifications. Public urls can be accessed by anyone and exploited. Always do a getPublicOrderById after a webhook to confirm the status of an order.