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

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

Workflow using your own UI

  1. Your site calls create_order to create an invoice, and gets back the invoice id with cryptocurrency address.
  2. Your site shows the address and all the necessary information to allow user payment.
  3. Your site gets a webhook callback when the invoice status changes (no matter it’s paid for or expired)
  4. 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.

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.

FieldTypeLabelDescription
idstringUnique order ID.
typeOrder.TypeOrder type.
asset_namestringAsset name.
target_valuestringValue to be paid in this order.
target_confirmationsint64Confirmations needed by this order.
variantsstringrepeatedReceiving address variants (usually use the first).
expired_atint64The timestamp this order expired (or will expire) at.
merchant_order_idstringMerchant order ID.
descriptionstringOrder description.
statusOrder.StatusOrder status.
valuestringValue received by this order up to now.
confirmationsint64Order confirmations
created_atint64Order created time.
updated_atint64Order updated time.
chainstringThe chain of this order.
networkstringThe network of this order.
callback_urlstringCallback url on the merchant site to redirect user to when an order is in a final state.
redirect_urlstringredirect url of Payment UI for user to proceed after creating an order

Order.Type

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

NameNumberDescription
NORMAL0Order is normal.

Order.Status

Order status.

NameNumberDescription
PENDING0Order is pending (waiting for enough payment value).
CONFIRMING1Order is confirming, (waiting for enough confirmations).
SUCCESSFUL2Order is successful.
EXPIRED3Order is expired.
CANCELED4Order is canceled.

WebhookOrder

Data received from a webhook.

FieldTypeLabelDescription
idint64Unique order ID.
pg_wallet_idint64Wallet ID.
merchant_order_idstringMerchant order ID.
statusOrder.StatusOrder status.

Error Codes

TBD

Private API

These APIs require authentication

createOrder

Creates an order/invoice.

Params

FieldTypeLabelDescription
merchant_order_idstringMerchant order ID.
asset_namestringAsset name.
target_valuestringValue to be paid.
callback_urlstringCallback url.
pg_wallet_idint64Wallet ID.

Return Value

FieldTypeLabelDescription
orderOrderThe 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

FieldTypeLabelDescription
idstringOrder ID.
with_paymentsboolWhether return related payments.

Return Value

FieldTypeLabelDescription
orderPublicOrderDetails 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.