🚀Quick Start

Start taking payments with our quick start API guide.

Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can get your API key in your Dashboard at any time, here:

Pi eCard

Install the library

The best way to interact with our API is to use one of our official libraries:

$ npm install @decentapps/piecard

const { PieCard } = require('@decentapps/piecard')

// Initialise
const piecard = new PieCard("Client_ID", "Client_Secret", "Access_Token");

Good to know: You can also use our APIs in any server-side language. Just see our API Reference.

Create a Payment

Creating a payment requires a simple request, containing just API keys as authorisation and the payment parameters.

Create a new payment

POST https://api.piecard.app/payment

Request Body

Name	Type	Description
amount*	number	The amount of Pi being requested. This includes the transaction fee.
memo*	string	Something to describe the payment to the user.
successURL*	string	The redirect URL for a successful payment.
cancelURL*	string	The redirect URL for a failed payment.
metadata	object	Any set object-key pairs for the developer's use. This will be included in the webhook.
sandbox	boolean	Set to true for testing you payment integration. Default is false.

200 Payment successfully created

{
    success: true,
    id: 'YOUR_PAYMENT_ID'
}

401 Permission denied

Test Mode: You can set sandbox mode to true to easily test you integration. Please see here for test mode usage.

Usage with NPM Package

// Create payment
const paymentData = {
  amount: NUMBER, // amount of service
  memo: STRING, // memo of the transaction
  metadata: OBJECT // metadata,
};

piecard.createPayment(paymentData)
  .then((response) => {
    console.log("Create payment : ", response);
  })
  .catch((err) => {
    console.log("Create payment error : ", err);
  });

From the POST /payment endpoint, you will receive a payment ID.

To initiate the payment, you must redirect the user to 'https://piecard.app/pay/YOUR_PAYMENT_ID'

Get a payment

Get a payment

GET https://api.piecard.app/payment/:paymentId

Path Parameters

Name	Type	Description
paymentId*	string	The unique ID of the payment. This is returned when the payment is created.

200 Payment found and returned

{
    success: true,
    payment: {
        _id,
        amount,
        fee,
        memo,
        payee, // your Pi eCard username
        metadata,
        successURL,
        cancelURL,
        sandbox
    }
}

401 Permission denied

404: Not Found Payment not found

Usage with NPM Package

// Get a payment
const payment = await piecardInstance.getPayment(paymentId);

Webhooks

To be able to deliver your product safely, you must listen for a Payment Complete webhook from our servers.

To begin receive webhooks, you must first enter a valid URL to your server in the Pi eCard Gateway Dashboard.

When a payment is completed, our servers with sent an HTTP request to this specified URL, which will consist of the payment data and status, encoded with your secret key.

Usage with NPM Package

// Decode payment details on your server
const {
    event_type,
    created,
    payment // an object containing the payment info, including metadata
} = await piecardInstance.decode(req.body);

If success is true, then the payment was fulfilled and you should deliver the product. If the success is false, do not deliver the product.

Working example with Express.js

// Decode payment details on your server
app.use('/piecard-webhook', (req, res) => {  // or any valid endpoint

    // decode the request body
    const data = await piecardInstance.validate(req.body);

    // destructure the decoded payment info
    const {
        id,
        amount,
        client,
        memo,
        sandbox,
        metadata,
        success,
    } = data.payment;
    
    // deliver the product if payment was fulfilled
    if (data.event_type === 'completed') {
        const { productId } = metadata; // this is whatever you set it
        // deliver the product here ...
    }
    
    return res.status(200);
    
};