Introduction

The PrivacyGate API provides a simple and powerful REST API to integrate Bitcoin, Bitcoin Cash, DAI, Ethereum, Litecoin, Dogecoin, and USDC payments into your business or application. This API reference provides information on available endpoints and how to interact with them.

Authentication

Example authenticated request:

curl https://api.privacygate.io/checkouts \
     -H "X-CC-Api-Key: <Your API Key>"

Most requests to the Commerce API must be authenticated with an API key. You can create an API key in your Settings page after creating a PrivacyGate account.

Authenticated API requests should be made with a X-CC-Api-Key header. Your secret API key should be passed as the value.

If authentication fails, a JSON object with an error message will be returned as a response along with HTTP status 401.

Versioning

Example request:

curl https://api.privacygate.io/checkouts \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

All API calls should include an X-CC-Version header containing the API version with which you would like to make your request. API versions are of the form YYYY-MM-DD, indicating the date on which that version was released; a new version will be released for every breaking change to the API. The latest API version is 2018-03-22.

If no version is passed, or if an unknown or invalid version is given, the latest API version will be used and a warning will be included in the response. Be sure to include a valid version with every request in order to avoid unexpected breakage. Do not pass the current date as your version header.

Pagination

Example request:

curl https://api.privacygate.io/checkouts?limit=20 \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response:

{
    "pagination": {
        "order": "desc",
        "starting_after": null,
        "ending_before": null,
        "total": 25,
        "yielded": 20,
        "limit": 20,
        "previous_uri": null,
        "next_uri": "https://api.privacygate.io/checkouts?limit=20&starting_after=fb6721f2-1622-48f0-b713-aac6c819b67a",
        "cursor_range": ["a76721f2-1611-48fb-a513-aac6c819a9d6", "fb6721f2-1622-48f0-b713-aac6c819b67a"]
    },
    "data": [
        ...
    ]
}

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API will construct the next call into next_uri together with all the currently used pagination parameters. You know that you have paginated all the results when the response’s next_uri is empty. Default limit is set to 25 but values up to 100 are permitted.

Arguments

Field	Description
order optional	Order of the resources in the response. desc (default), asc
limit optional	Number of results per call. Accepted values: 0 - 100. Default 25
starting_after optional	A cursor for use in pagination. starting_after is a resource ID that defines your place in the list.
ending_before optional	A cursor for use in pagination. ending_before is a resource ID that defines your place in the list.

Errors

Error response

Error response 400

{
    "error": {
        "type"  : "invalid_request",
        "message": "Required parameter missing: name"
    }
}

All error messages include a type identifier and a human readable message.

validation_error with status code 400 is returned when the validation of the resource fails on POST or PUT requests. Response contains errors field with a list of errors.

Warnings

Example warning

{
    "warnings": [
      "Missing X-CC-Version header; serving latest API version (2018-03-22)"
    ]
}

Responses can include a warnings parameter to notify the developer of best practices, implementation suggestions or deprecation warnings. While you don’t need show warnings to the user, they are usually something you need to act on.

Rate limiting

Rate limiting error (429)

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  }
}

The PrivacyGate API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users. By default, every user is rate limited at 25 requests per minute on the charge creation endpoint and 200 requests per minute for all other endpoints. If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error.

Webhooks

Example of a webhook payload

{
    "id": 1,
    "scheduled_for": "2017-01-31T20:50:02Z",
    "event": {
        "id": "24934862-d980-46cb-9402-43c81b0cdba6",
        "resource": "event",
        "type": "charge:created",
        "api_version": "2018-03-22",
        "created_at": "2017-01-31T20:49:02Z",
        "data": {
          "code": "66BEOV2A",
          "name": "The Sovereign Individual",
          "description": "Mastering the Transition to the Information Age",
          "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
          "created_at": "2017-01-31T20:49:02Z",
          "expires_at": "2017-01-31T21:49:02Z",
          "timeline": [
            {
              "time": "2017-01-31T20:49:02Z",
              "status": "NEW"
            }
          ],
          "metadata": {},
          "pricing_type": "no_price",
          "payments": [],
          "addresses": {
            "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
            "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
          }
        }
    }
}

Webhooks make it easier to integrate with PrivacyGate by allowing you to subscribe to a set of charge events. You can subscribe to the events by going to your settings page and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for. Below is the list of all available webhook events:

Event	Description
charge:created	New charge is created
charge:confirmed	Charge has been confirmed and the associated payment is completed
charge:failed	Charge failed to complete
charge:delayed	Charge received a payment after it had been expired
charge:pending	Charge has been detected but has not been confirmed yet
charge:resolved	Charge has been resolved

Fields

Field	Type	Description
id	number	Delivery attempt number
scheduled_for	timestamp	Delivery schedule time
event	hash	Corresponding event object

Securing webhooks

Every PrivacyGate webhook request will include a User-Agent header set to privacygate-webhooks (like weipay-webhooks).

Every PrivacyGate webhook request includes an X-CC-Webhook-Signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret from your settings page. Always make sure that you verify the webhook signature before acting on it inside your system. All integrations on our public github page verify this already, but if you need to implement it yourself please take a look at our reference ruby implementation.

Every PrivacyGate webhook request will originate from an IP Address in the following CIDR Block: 54.175.255.192/27 – that is, in the range from 54.175.255.192 to 54.175.255.223.

Valid origin IP addresses fully enumerated: link

Charges

To request a cryptocurrency payment, you create a charge. You can create and view charges. Since cryptocurrency payments are push payments, a charge will expire after a waiting period (payment window) if no payment has been detected. Charges are identified by a unique code.

Charge resource

Example of a charge resource

{
  "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
  "resource": "charge",
  "code": "66BEOV2A",
  "name": "The Sovereign Individual",
  "description": "Mastering the Transition to the Information Age",
  "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
  "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
  "created_at": "2017-01-31T20:49:02Z",
  "expires_at": "2017-01-31T21:49:02Z",
  "confirmed_at": "2017-01-31T20:50:02Z",
  "checkout": {
    "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
  },
  "timeline": [
    {
      "time": "2017-01-31T20:49:02Z",
      "status": "NEW"
    },
    {
      "time": "2017-01-31T20:50:02Z",
      "status": "PENDING"
    },
    {
      "time": "2017-01-31T20:50:02Z",
      "status": "COMPLETED"
    },
    {
      "time": "2017-01-31T20:50:02Z",
      "status": "UNRESOLVED",
      "context": "UNDERPAID"
    },
    {
      "time": "2017-01-31T20:50:02Z",
      "status": "RESOLVED"
    }
  ],
  "metadata": {},
  "pricing_type": "fixed_price",
  "pricing": {
    "local": { "amount": "100.00", "currency": "USD" },
    "bitcoin": { "amount": "1.00", "currency": "BTC" },
    "ethereum": { "amount": "10.00", "currency": "ETH" }
  },
  "payment_threshold": {
    "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
    "overpayment_relative_threshold": "0.05",
    "underpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
    "underpayment_relative_threshold": "0.05"
  },
  "applied_threshold": { "amount": "5.00", "currency": "USD" },
  "applied_threshold_type": "RELATIVE",
  "payments": [
    {
      "network": "ethereum",
      "transaction_id": "0xe02fead885c3e4019945428ed54d094247bada2d0ac41b08fce7ce137bf29587",
      "status": "CONFIRMED",
      "value": {
        "local": { "amount": "100.0", "currency": "USD" },
        "crypto": { "amount": "10.00", "currency": "ETH" }
      },
      "block": {
        "height": 100,
        "hash": "0xe02fead885c3e4019945428ed54d094247bada2d0ac41b08fce7ce137bf29587",
        "confirmations_accumulated": 8,
        "confirmations_required": 2
      }
    }
  ],
  "addresses": {
    "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
    "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
  }
}

Fields

Field	Type	Description
id	string	Charge UUID
resource	string	Resource name: "charge"
code	string	Charge user-friendly primary key
name	string	Charge name
description	string	Charge description
logo_url	string	Charge image URL
hosted_url	string	Hosted charge URL
created_at	timestamp	Charge creation time
expires_at	timestamp	Charge expiration time
confirmed_at	timestamp	Charge confirmation time
checkout	hash	Associated checkout resource
timeline	array	Array of status update objects
metadata	hash	Metadata associated with the charge
pricing_type	string	Pricing type: no_price or fixed_price
pricing	hash	Charge price information object
payments	array	Array of charge payment objects
addresses	hash	Set of addresses associated with the charge

Charge Timeline

Every charge object has a timeline of status updates. Charge timeline is an array of objects of the following format:

Field	Type	Description
time	timestamp	Time of the status update
status	string	One of the following statuses: NEW, PENDING, COMPLETED, EXPIRED, UNRESOLVED, RESOLVED, CANCELED, REFUND PENDING, REFUNDED
context	string, optional	For charges with UNRESOLVED status, additional context is provided. Context can be one of the following: UNDERPAID, OVERPAID, DELAYED, MULTIPLE, MANUAL, OTHER

Pricing

If a charge has a fixed_price pricing type, then there will be a pricing object associated with it. Pricing object is composed of local price which is set by the merchant in their native fiat currency and corresponding prices in every cryptocurrency that the merchant has activated for their account

Field	Type	Description
local	money	Price set by the merchant in local fiat currency
bitcoin	money, optional	Price in BTC
bitcoincash	money, optional	Price in BCH
ethereum	money, optional	Price in ETH
litecoin	money, optional	Price in LTC
dogecoin	money, optional	Price in DOGE
usdc	money, optional	Price in USDC
dai	money, optional	Price in DAI

Addresses

For every active cryptocurrency for a charge addresses object will contain an address that the buyer will be expected to pay to

Field	Type	Description
bitcoin	string, optional	Bitcoin address
bitcoincash	string, optional	Bitcoin Cash address
ethereum	string, optional	Ethereum address
litecoin	string, optional	Litecoin address
dogecoin	string, optional	Dogecoin address
usdc	string, optional	USD Coin address
dai	string, optional	DAI address

List charges

Example request

curl https://api.privacygate.io/charges \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "pagination": {
    ...
  },
  "data": [{
     "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
     "resource": "charge",
    "code": "66BEOV2A",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
    "created_at": "2017-01-31T20:49:02Z",
    "expires_at": "2017-01-31T21:49:02Z",
    "checkout": {
      "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
    },
    "timeline": [
      {
        "time": "2017-01-31T20:49:02Z",
        "status": "NEW"
      }
    ],
    "metadata": {},
    "pricing_type": "fixed_price",
    "pricing": {
      "local": { "amount": "100.00", "currency": "USD" },
      "bitcoin": { "amount": "1.00", "currency": "BTC" },
      "ethereum": { "amount": "10.00", "currency": "ETH" }
    },
    "payment_threshold": {
      "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "overpayment_relative_threshold": "0.05",
      "underpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "underpayment_relative_threshold": "0.05"
    },
    "payments": [],
    "addresses": {
      "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
    }
  }]
}

Lists all the charges

HTTP Request

GET https://api.privacygate.io/charges

Show a charge

Example request

curl https://api.privacygate.io/charges/66BEOV2A \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
    "resource": "charge",
    "code": "66BEOV2A",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
    "created_at": "2017-01-31T20:49:02Z",
    "expires_at": "2017-01-31T21:49:02Z",
    "checkout": {
      "id": "a76721f2-1611-48fb-a513-aac6c819a9d6"
    },
    "timeline": [
      {
        "time": "2017-01-31T20:49:02Z",
        "status": "NEW"
      }
    ],
    "metadata": {},
    "pricing_type": "fixed_price",
    "pricing": {
      "local": { "amount": "100.00", "currency": "USD" },
      "bitcoin": { "amount": "1.00", "currency": "BTC" },
      "ethereum": { "amount": "10.00", "currency": "ETH" }
    },
    "payment_threshold": {
      "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "overpayment_relative_threshold": "0.05",
      "underpayment_absolute_threshold": {
        "amount": "5.00",
        "currency": "USD"
      },
      "underpayment_relative_threshold": "0.05"
    },
    "payments": [],
    "addresses": {
      "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
    }
  }
}

Retrieves the details of a charge that has been previously created. Supply the unique charge code that was returned when the charge was created. This information is also returned when a charge is first created.

HTTP Request

GET https://api.privacygate.io/charges/:charge_code|:charge_id

Create a charge

Example request

curl https://api.privacygate.io/charges \
     -X POST \
     -H 'Content-Type: application/json' \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22" \
     -d '{
       "name": "The Sovereign Individual",
       "description": "Mastering the Transition to the Information Age",
       "local_price": {
         "amount": "100.00",
         "currency": "USD"
       },
       "pricing_type": "fixed_price",
       "metadata": {
         "customer_id": "id_1005",
         "customer_name": "Satoshi Nakamoto"
       },
       "redirect_url": "https://charge/completed/page",
       "cancel_url": "https://charge/canceled/page"
     }'

Response (201)

{
  "data": {
    "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
    "resource": "charge",
    "code": "66BEOV2A",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
    "created_at": "2017-01-31T20:49:02Z",
    "expires_at": "2017-01-31T21:49:02Z",
    "timeline": [
      {
        "time": "2017-01-31T20:49:02Z",
        "status": "NEW"
      }
    ],
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    },
    "pricing_type": "fixed_price",
    "pricing": {
      "local": { "amount": "100.00", "currency": "USD" },
      "bitcoin": { "amount": "1.00", "currency": "BTC" },
      "ethereum": { "amount": "10.00", "currency": "ETH" }
    },
    "payments": [],
    "payment_threshold": {
      "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "overpayment_relative_threshold": "0.05",
      "underpayment_absolute_threshold": {
        "amount": "5.00",
        "currency": "USD"
      },
      "underpayment_relative_threshold": "0.05"
    },
    "addresses": {
      "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
    },
    "redirect_url": "https://charge/completed/page",
    "cancel_url": "https://charge/canceled/page"
  }
}

To get paid in cryptocurrency, you need to create a charge object and provide the user with a cryptocurrency address to which they must send cryptocurrency. Once a charge is created a customer must broadcast a payment to the blockchain before the charge expires.

HTTP Request

POST https://api.privacygate.io/charges

Arguments

Parameter	Type	Required	Description
name	string	Required	Charge name, 100 characters or less
description	string	Required	More detailed description of the charge, 200 characters or less
pricing_type	string	Required	Charge pricing type: no_price or fixed_price
local_price	money	Optional	Price in local fiat currency
metadata	hash	Optional	Developer defined key value pairs
redirect_url	string	Optional	Redirect URL
cancel_url	string	Optional	Cancel URL

Cancel a charge

Example request

curl https://api.privacygate.io/charges/66BEOV2A/cancel \
     -X POST \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
    "resource": "charge",
    "code": "66BEOV2A",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
    "created_at": "2017-01-31T20:49:02Z",
    "expires_at": "2017-01-31T21:49:02Z",
    "timeline": [
      {
        "time": "2017-01-31T20:49:02Z",
        "status": "NEW"
      },
      {
        "time": "2017-01-31T20:52:02Z",
        "status": "CANCELED"
      }
    ],
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    },
    "pricing_type": "fixed_price",
    "pricing": {
      "local": { "amount": "100.00", "currency": "USD" },
      "bitcoin": { "amount": "1.00", "currency": "BTC" },
      "ethereum": { "amount": "10.00", "currency": "ETH" }
    },
    "payment_threshold": {
      "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "overpayment_relative_threshold": "0.05",
      "underpayment_absolute_threshold": {
        "amount": "5.00",
        "currency": "USD"
      },
      "underpayment_relative_threshold": "0.05"
    },
    "payments": [],
    "addresses": {
      "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
    },
    "redirect_url": "https://charge/completed/page",
    "cancel_url": "https://charge/canceled/page"
  }
}

Cancels a charge that has been previously created. Supply the unique charge code that was returned when the charge was created.

Note: Only new charges can be successfully canceled. Once payment is detected, charge can no longer be canceled.

HTTP Request

POST https://api.privacygate.io/charges/:charge_code|:charge_id

Resolve a charge

Example request

curl https://api.privacygate.io/charges/66BEOV2A/resolve \
     -X POST \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "f765421f2-1451-fafb-a513-aac6c819fba9",
    "resource": "charge",
    "code": "66BEOV2A",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
    "created_at": "2017-01-31T20:49:02Z",
    "expires_at": "2017-01-31T21:49:02Z",
    "timeline": [
      {
        "time": "2017-01-31T20:49:02Z",
        "status": "NEW"
      },
      {
        "status": "EXPIRED",
        "time": "2017-01-31T21:49:02Z"
      },
      {
        "status": "UNRESOLVED",
        "time": "2017-01-31T22:00:00Z",
        "context": "DELAYED"
      },
      {
        "status": "RESOLVED",
        "time": "2017-01-31T23:00:00Z"
      }
    ],
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    },
    "pricing_type": "fixed_price",
    "pricing": {
      "local": { "amount": "100.00", "currency": "USD" },
      "bitcoin": { "amount": "1.00", "currency": "BTC" },
      "ethereum": { "amount": "10.00", "currency": "ETH" }
    },
    "payment_threshold": {
      "overpayment_absolute_threshold": { "amount": "5.00", "currency": "USD" },
      "overpayment_relative_threshold": "0.05",
      "underpayment_absolute_threshold": {
        "amount": "5.00",
        "currency": "USD"
      },
      "underpayment_relative_threshold": "0.05"
    },
    "applied_threshold": { "amount": "5.00", "currency": "USD" },
    "applied_threshold_type": "RELATIVE",
    "payments": [
      {
        "network": "ethereum",
        "transaction_id": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "status": "CONFIRMED",
        "detected_at": "2017-01-31T22:00:00Z",
        "value": {
          "local": { "amount": "100.0", "currency": "USD" },
          "crypto": { "amount": "10.00", "currency": "ETH" }
        },
        "block": {
          "height": 100,
          "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "confirmations_accumulated": 8,
          "confirmations_required": 2
        }
      }
    ],
    "addresses": {
      "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
    },
    "redirect_url": "https://charge/completed/page",
    "cancel_url": "https://charge/canceled/page"
  }
}

Resolve a charge that has been previously marked as unresolved. Supply the unique charge code that was returned when the charge was created.

Note: Only unresolved charges can be successfully resolved. For more on unresolved charges, check out at Charge timeline

HTTP Request

POST https://api.privacygate.io/charges/:charge_code|:charge_id

Checkouts

Checkouts make it possible to sell a single fixed price item or accept arbitrary amounts of cryptocurrency very easily. Checkouts can have many charges and each charge is automatically generated on a per customer basis. Checkouts can also be quickly integrated into a website by embedding payment buttons. Each checkout has a publicly accessible hosted page that can be shared with anyone.

Checkout resource

Example of a checkout resource

{
    "id": "30934862-d980-46cb-9402-43c81b0cabd5",
    "resource": "checkout",
    "name": "The Sovereign Individual",
    "description": "Mastering the Transition to the Information Age",
    "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
    "requested_info": [ "name", "email" ],
    "pricing_type": "fixed_price",
    "local_price": { "amount": "100.0", "currency": "USD" }
}

Fields

Field	Type	Description
id	string	Checkout UUID
resource	string	Resource name: "checkout"
name	string	Checkout name
description	string	Checkout description
logo_url	string, optional	Checkout image URL
requested_info	array, optional	Array of strings specifying what information the merchants wants to collect from the buyers: name, email
pricing_type	string	Pricing type: no_price or fixed_price
local_price	money, optional	If pricing_type is fixed_price, then this field will specify the price

List checkouts

Example request

curl https://api.privacygate.io/checkouts \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
    "pagination": {
        ...
    },
    "data": [{
        "id": "30934862-d980-46cb-9402-43c81b0cabd5",
        "resource": "checkout",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
        "requested_info": [ ],
        "pricing_type": "no_price"
    }]
}

Lists all the checkouts

HTTP Request

GET https://api.privacygate.io/checkouts

Show a checkout

Example request

curl https://api.privacygate.io/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
    "data": {
        "id": "30934862-d980-46cb-9402-43c81b0cabd5",
        "resource": "checkout",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "logo_url": "https://dash.privacygate.io/charges/ybjknds.png",
        "requested_info": [ ],
        "pricing_type": "no_price"
    }
}

Show a single checkout

HTTP Request

GET https://api.privacygate.io/checkouts/:checkout_id

Create a checkout

Example request

curl https://api.privacygate.io/checkouts \
     -X POST \
     -H 'Content-Type: application/json' \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22" \
     -d '{
         "name": "The Sovereign Individual",
         "description": "Mastering the Transition to the Information Age",
         "local_price": {
             "amount": "100.00",
             "currency": "USD"
         },
       "pricing_type": "fixed_price",
         "requested_info": ["email"]
     }'

Response (201)

{
    "data": {
        "id": "30934862-d980-46cb-9402-43c81b0cabd5",
        "resource": "checkout",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "requested_info": ["email"],
        "pricing_type": "fixed_price",
        "local_price": {"amount": "100.00", "currency": "USD"}
    }
}

Create a new checkout.

HTTP Request

POST https://api.privacygate.io/checkouts

Arguments

Parameter	Type	Required	Description
name	string	Required	Checkout name, 100 characters or less
description	string	Required	More detailed description, 200 characters or less
pricing_type	string	Required	Checkout pricing type: no_price or fixed_price
local_price	money	Optional	Price in local fiat currency
requested_info	array	Optional	Information to collect from the customer: email, name

Update a checkout

Example request

curl https://api.privacygate.io/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
     -X PUT \
     -H 'Content-Type: application/json' \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22" \
     -d '{
         "local_price": {
             "amount": "200.00",
             "currency": "USD"
         }
     }'

Response (200)

{
    "data": {
        "id": "30934862-d980-46cb-9402-43c81b0cabd5",
        "resource": "checkout",
        "name": "The Sovereign Individual",
        "name": "The Sovereign Individual",
        "description": "Mastering the Transition to the Information Age",
        "requested_info": ["email"],
        "pricing_type": "fixed_price",
        "local_price": {"amount": "200.00", "currency": "USD"}
    }
}

Update a checkout.

HTTP Request

PUT https://api.privacygate.io/checkouts/:checkout_id

Arguments

Parameter	Type	Required	Description
name	string	Required	Checkout name
description	string	Required	More detailed description
local_price	money	Optional	Price in local fiat currency
requested_info	array	Optional	Information to collect from the customer: email, name

Delete a checkout

Example request

curl https://api.privacygate.io/checkouts/30934862-d980-46cb-9402-43c81b0cabd5 \
     -X DELETE \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Response (200)

Delete a checkout.

HTTP Request

DELETE https://api.privacygate.io/checkouts/:checkout_id

Invoices

An invoice can be created and sent to customers for payment by constructing a url with the generated 8 character short-code. Invoice url's have the format https://dash.privacygate.io/invoices/:code. Invoice urls can be sent to the payee to collect payment, and will associate a new charge on the invoice object once it has been viewed. Charges associated with invoices will automatically refresh their 1-hour payment window if they expire.

Invoice resource

Example of an invoice resource

{
  "id": "d0bb39fc-3690-4c88-bb41-74ca60b77df0",
  "resource": "invoice",
  "code": "8LA8E2WX",
  "status": "OPEN",
  "business_name": "Crypto Accounting LLC",
  "customer_name": "Test Customer",
  "customer_email": "[email protected]",
  "memo": "Accounting and tax consultation services",
  "local_price": { "amount": "50.00", "currency": "USD" },
  "hosted_url": "https://dash.privacygate.io/invoices/8LA8E2WX",
  "created_at": "2021-01-12T21:06:42Z",
  "updated_at": "2021-01-12T21:07:58Z"
}

Fields

Field	Type	Description
id	string	Charge UUID
resource	string	Resource name: "invoice"
code	string	Charge user-friendly primary key
status	string	Status of the invoice
business_name	string	Your business name
customer_name	string	Customer's name (optional)
customer_email	string	Customer's email
memo	string	Invoice memo
local_price	hash	Invoice price information object
hosted_url	string	Hosted invoice URL
created_at	timestamp	Invoice creation time
updated_at	timestamp	Invoice updated time
charge	hash	Associated charge resource (only exists if viewed)

List invoices

Example request

curl https://api.privacygate.io/invoices \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "pagination": { ... },
  "data": [{
    "id": "d0bb39fc-3690-4c88-bb41-74ca60b77df0",
    "resource": "invoice",
    "code": "8LA8E2WX",
    "status": "VIEWED",
    "business_name": "Crypto Accounting LLC",
    "customer_name": "Test Customer",
    "customer_email": "[email protected]",
    "memo": "Accounting and tax consultation services",
    "local_price": { "amount": "50.00", "currency": "USD" },
    "hosted_url": "https://dash.privacygate.io/invoices/8LA8E2WX",
    "created_at": "2021-01-12T21:06:42Z",
    "updated_at": "2021-01-12T21:07:58Z",
    "charge": { ... }
  }]
}

Lists all the invoices

HTTP Request

GET https://api.privacygate.io/invoices

Show an invoice

Example request

curl https://api.privacygate.io/invoices/8LA8E2WX \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "d0bb39fc-3690-4c88-bb41-74ca60b77df0",
    "resource": "invoice",
    "code": "8LA8E2WX",
    "status": "VIEWED",
    "business_name": "Crypto Accounting LLC",
    "customer_name": "Test Customer",
    "customer_email": "[email protected]",
    "memo": "Accounting and tax consultation services",
    "local_price": { "amount": "50.00", "currency": "USD" },
    "hosted_url": "https://dash.privacygate.io/invoices/8LA8E2WX",
    "created_at": "2021-01-12T21:06:42Z",
    "updated_at": "2021-01-12T21:07:58Z",
    "charge": { ... }
  }
}

Retrieves the details of an invoice that has been previously created. Supply the unique short code that was returned when the invoice was created. This information is also returned when an invoice is first created.

HTTP Request

GET https://api.privacygate.io/invoices/:code|:id

Create an invoice

Example request

curl https://api.privacygate.io/invoices \
     -X POST \
     -H 'Content-Type: application/json' \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22" \
     -d '{
       "business_name": "Crypto Accounting LLC",
       "customer_email": "[email protected]",
       "customer_name": "Test Customer",
       "local_price": {
         "amount": "100.00",
         "currency": "USD"
       },
       "memo": "Taxes and Accounting Services"
     }'

Response (201)

{
  "data": {
    "id": "b76f81ec-3e8d-4342-aacb-582fab083660",
    "business_name": "Crypto Accounting LLC",
    "resource": "invoice",
    "code": "BV9KGDVA",
    "status": "OPEN",
    "customer_name": "Test Customer",
    "customer_email": "[email protected]",
    "local_price": { "amount": "100.00", "currency": "USD" },
    "memo": "Taxes and Accounting Services",
    "hosted_url": "https://dash.privacygate.io/invoices/BV9KGDVA",
    "created_at": "2021-01-12T21:38:24Z",
    "updated_at": "2021-01-12T21:38:24Z"
  }
}

To send an invoice in cryptocurrency, you need to create an invoice object and provide the user with the hosted url where they will be able to pay. Once an invoice is viewed at the hosted url, a charge will be generated on the invoice.

HTTP Request

POST https://api.privacygate.io/invoices

Arguments

Parameter	Type	Required	Description
business_name	string	Required	Your business name
customer_email	string	Required	The email address of the customer
customer_name	string	Optional	The name of the customer
local_price	money	Required	Price in local fiat currency
memo	hash	Optional	A memo for the invoice

Void an invoice

Example request

curl https://api.privacygate.io/invoices/BV9KGDVA/void \
     -X POST \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "b76f81ec-3e8d-4342-aacb-582fab083660",
    "business_name": "Crypto Accounting LLC",
    "resource": "invoice",
    "code": "BV9KGDVA",
    "status": "VOID",
    "customer_name": "Test Customer",
    "customer_email": "[email protected]",
    "local_price": { "amount": "100.00", "currency": "USD" },
    "memo": "Taxes and Accounting Services",
    "hosted_url": "https://dash.privacygate.io/invoices/BV9KGDVA",
    "created_at": "2021-01-12T21:38:24Z",
    "updated_at": "2021-01-12T22:13:09Z"
  }
}

Voids an invoice that has been previously created. Supply the unique invoice code that was returned when the invoice was created.

Note: Only invoices with OPEN or VIEWED status can be voided. Once a payment is detected, the invoice can no longer be voided.

HTTP Request

POST https://api.privacygate.io/invoices/:code|:id

Resolve an invoice

Example request

curl https://api.privacygate.io/invoices/BV9KGDVA/resolve \
     -X POST \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
  "data": {
    "id": "b76f81ec-3e8d-4342-aacb-582fab083660",
    "business_name": "Crypto Accounting LLC",
    "resource": "invoice",
    "code": "BV9KGDVA",
    "status": "PAID",
    "customer_name": "Test Customer",
    "customer_email": "[email protected]",
    "local_price": { "amount": "100.00", "currency": "USD" },
    "memo": "Taxes and Accounting Services",
    "hosted_url": "https://dash.privacygate.io/invoices/BV9KGDVA",
    "created_at": "2021-01-12T21:38:24Z",
    "updated_at": "2021-01-12T22:13:09Z",
    "charge": {
      "timeline": [
        {
          "time": "2017-01-31T20:49:02Z",
          "status": "NEW"
        },
        {
          "status": "EXPIRED",
          "time": "2017-01-31T21:49:02Z"
        },
        {
          "status": "UNRESOLVED",
          "time": "2017-01-31T22:00:00Z",
          "context": "DELAYED"
        },
        {
          "status": "RESOLVED",
          "time": "2017-01-31T23:00:00Z"
        }
      ],
      ... // other charge data
    }
  }
}

Resolve an invoice that has been previously marked as unresolved. Supply the unique invoice code that was returned when the invoice was created.

Note: Only invoices with an unresolved charge can be successfully resolved. For more on unresolved charges, check out at Charge timeline

HTTP Request

POST https://api.privacygate.io/invoices/:code|:id

Events

Events let you know when a charge is updated. When an event occurs we create a new event object. Retrieve individual events or a list of events. You can also subscribe to webhook notifications which send event objects directly to an endpoint on your server. Learn more about webhooks.

Event resource

Example of an event resource

{
    "id": "24934862-d980-46cb-9402-43c81b0cdba6",
    "resource": "event",
    "type": "charge:created",
    "api_version": "2018-03-22",
    "created_at": "2017-01-31T20:49:02Z",
    "data": {
      "code": "66BEOV2A",
      "name": "The Sovereign Individual",
      "description": "Mastering the Transition to the Information Age",
      "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
      "created_at": "2017-01-31T20:49:02Z",
      "expires_at": "2017-01-31T21:49:02Z",
      "timeline": [
        {
          "time": "2017-01-31T20:49:02Z",
          "status": "NEW"
        }
      ],
      "metadata": {},
      "pricing_type": "no_price",
      "payments": [],
      "addresses": {
        "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
        "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
      }
    }
}

Fields

Field	Type	Description
id	string	Event UUID
resource	string	Resource name: "event"
type	string	Event type: charge:created, charge:confirmed, charge:failed, charge:delayed, charge:pending
created_at	timestamp	Event creation time
api_version	string	API version of the data payload
data	hash	Event payload: resource of the associated object (e.g. charge) at the time of the event

Types of events

This is a list of all the types of events we currently send. You should not assume that only these types exist as we may add more events over time.

Event Type	Description
charge:created	New charge is created
charge:confirmed	Charge has been confirmed and the associated payment is completed
charge:failed	Charge failed to complete
charge:delayed	Charge received a payment after it had been expired
charge:pending	Charge has been detected but has not been confirmed yet
charge:resolved	Charge has been resolved

List events

Example request

curl https://api.privacygate.io/events \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
    "pagination": {
        ...
    },
    "data": [{
        "id": "24934862-d980-46cb-9402-43c81b0cdba6",
        "resource": "event",
        "type": "charge:created",
        "api_version": "2018-03-22",
        "created_at": "2017-01-31T20:49:02Z",
        "data": {
          "code": "66BEOV2A",
          "name": "The Sovereign Individual",
          "description": "Mastering the Transition to the Information Age",
          "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
          "created_at": "2017-01-31T20:49:02Z",
          "expires_at": "2017-01-31T21:49:02Z",
          "timeline": [
            {
              "time": "2017-01-31T20:49:02Z",
              "status": "NEW"
            }
          ],
          "metadata": {},
          "pricing_type": "no_price",
          "payments": [],
          "addresses": {
            "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
            "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
          }
    }
    }]
}

Lists all the events

HTTP Request

GET https://api.privacygate.io/events

Show an event

Example request

curl https://api.privacygate.io/events/24934862-d980-46cb-9402-43c81b0cdba6 \
     -H "X-CC-Api-Key: <Your API Key>" \
     -H "X-CC-Version: 2018-03-22"

Example response

{
    "data": {
        "id": "24934862-d980-46cb-9402-43c81b0cdba6",
        "resource": "event",
        "type": "charge:created",
        "api_version": "2018-03-22",
        "created_at": "2017-01-31T20:49:02Z",
        "data": {
          "code": "66BEOV2A",
          "name": "The Sovereign Individual",
          "description": "Mastering the Transition to the Information Age",
          "hosted_url": "https://dash.privacygate.io/charges/66BEOV2A",
          "created_at": "2017-01-31T20:49:02Z",
          "expires_at": "2017-01-31T21:49:02Z",
          "timeline": [
            {
              "time": "2017-01-31T20:49:02Z",
              "status": "NEW"
            }
          ],
          "metadata": {},
          "pricing_type": "no_price",
          "payments": [],
          "addresses": {
            "bitcoin": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
            "ethereum": "0x419f91df39951fd4e8acc8f1874b01c0c78ceba6"
          }
        }
    }
}

Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.

HTTP Request

GET https://api.privacygate.io/events/:event_id