Skip to content

Latest commit

 

History

History
122 lines (86 loc) · 3.74 KB

platform_API.md

File metadata and controls

122 lines (86 loc) · 3.74 KB

Platform API

The platform API allows you to read and write data to the Pi Servers related with your app deployed on the Pi App Platform, and your app's users.

Overview

Base path:

The latest version of the Platform API is available at api.minepi.com/v2.

Note about API versioning:

The platform API is currently in v2. As much as possible, we will not make any breaking changes to a version of an API, and only release breaking changes as new major versions. However, we might make breaking changes to an existing version without notice, if those are necessary (e.g security or privacy fixes).

Authorization

The Platform API supports two different authorization mechanisms.

Access token authorization

Some API calls require that you provide a user's access token to access the resource. They are generally related with a user's data (e.g: /me). Those endpoints can be accessed using the following Authorization header:

Authorization: Bearer <user access token>

Those endpoints can be indifferently accessed from your backend / server app, or from your frontend / client app.

Server API Key authorization

For various reasons, some API calls must be made from your backend / server app. Those endpoints can be accessed using the following Authorization header:

Authorization: Key <your Server API Key>

Warning: Server API keys are for servers only

Your Server API Key must be kept on your server, and must not be sent to clients (do not use it in your client javascript code). In the future, your server API key might enable sensitive operations on your app itself that your users should not be allowed to perform. Letting users access your server API key is a serious security breach.

API Reference

Payments

Base path: /payments.

Create a payment:

Do not create payments using the Platform API. Use the client-side Javascript SDK for this purpose.

Get a payment:

GET /payments/:payment_id
  • Authorization method: User access token
  • Response type: PaymentDTO

Coming soon: Server API Key Authorization on this endpoint, to remove the need from passing the user's access token to your server.

Approve a payment:

POST /payments/:payment_id/approve
  • Authorization method: Server API Key
  • Response type: PaymentDTO

Complete a payment:

POST /payments/:payment_id/complete
  • Authorization method: Server API Key
  • Response type: PaymentDTO

Resource types

PaymentDTO

{
  // Payment data:
  "identifier": string, // The payment identifier
  "user_uid": string, // The user's app-specific ID
  "amount": number, // The payment amount
  "reason": string, // A string provided by the developer, shown to the user
  "metadata": Object, // An object provided by the developer for their own usage
  "to_address": string, // The recipient address of the blockchain transaction
  "created_at": string, // The payment's creation timestamp
  
  // Status flags representing the current state of this payment
  "status": {
    "developer_approved": boolean, // Server-Side Approval
    "transaction_verified": boolean, // Blockchain transaction verified
    "developer_completed": boolean, // Server-Side Completion
    "cancelled": boolean, // Cancelled by the developer or by Pi Network
    "user_cancelled": boolean, // Cancelled by the user
  },
  
  // Blockchain transaction data:
  "transaction": null | { // This is null if no transaction has been made yet
    "txid": string, // The id of the blockchain transaction
    "verified": boolean, // True if the transaction matches the payment, false otherwise
    "_link": string, // A link to the operation on the Blockchain API
  },
};