• Introduction
  • Authentication
  • Versioning
  • Pagination
  • Errors
  • Rate limiting
  • Webhooks
  • Charges
  • Checkouts
  • Invoices
  • Events
  • 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