Charges

Charges describe what you charge your users for and how much. We show this information to users when subscribing to your API and also use it to ensure only charges of certain amounts are made, this gives users knowledge about how your pricing works.

Static Charges

Static Charges are charges that can only be made once per user request, this allows you to setup a "pay per request" model of payments.

Allows charging per request (i.e £0.003 per request)

Go

user, _ := paypi.Authenticate("<USER_TOKEN>")

charge, err := user.MakeCharge(paypi.MakeChargeInput{
  ChargeIdentifier: "<CHARGE_IDENTIFIER>",
})

Node JS

const user = await paypi.authenticate("<Subscriber secret>")

await user.makeCharge("<CHARGE_IDENTIFIER>")

Python

# Async
user = await paypi.authenticate("<Subscription Secret>")
await user.make_charge("<CHARGE_IDENTIFIER>")

# Sync
user = paypi.authenticate_sync("<Subscription Secret>")
user.make_charge_sync("<CHARGE_IDENTIFIER>")

Dynamic Charges

Dynamic Charges allow you to change the cost of the charge at the time of your request. This is to account for processing time, MB of data processed etc. A Dynamic Charge requires a cost but also a unit to state how much of the charge was used. This unit is multiplied by the cost to calculate the total cost to the user.

Allows charging based on usage (i.e £0.003 per MB)

Go

user, _ := paypi.Authenticate("<USER_TOKEN>")

charge, err := user.MakeCharge(paypi.MakeChargeInput{
  ChargeIdentifier: "<CHARGE_IDENTIFIER>",
  UnitsUsed: 5,
})

Node JS

const user = await paypi.authenticate("<Subscriber secret>")

const unitsUsed = 4
await user.makeCharge("<CHARGE_IDENTIFIER>", unitsUsed)

Python

units_used = 4

# Async
user = await paypi.authenticate("<Subscription Secret>")
await user.make_charge("<CHARGE_IDENTIFIER>", units_used)

# Sync
user = paypi.authenticate_sync("<Subscription Secret>")
user.make_charge_sync("<CHARGE_IDENTIFIER>", units_used)

Extra Info

Charge Timings

When a charge is made, it is logged on the analytics dashboard in close to realtime, however it may take up to 3 hours for this charge to be shown in the "Available funds" of your account.

Errors

If a charge returns an error ensure to return this error to your user.

If there was an error after a charge has been made causing an invalid response, users are eligible to request the cost of their request back, so ensure your API is working correctly before going live.

Examples

Some examples of using charges in different API scenarios.

PDF to JPG Converter

This API converts PDF files to JPG files through an API, and wants to use PayPI to increase user uptake and reduce development work.

PDF to JPG wants to charge a different fee dependant on the size of the PDF file to convert, but also a fixed fee for each request.

The API uses the following charges to do this:

Charge Name	Charge Type	Charge Cost	Charge Identifier
PDF Size	DYNAMIC	£0.005 / MB	cid-AAAAAA
Per request cost	STATIC	£0.01	cid-BBBBBB

This then makes a conversion of a 1MB PDF file cost a total of £0.015 (£0.005 + £0.01).

They implement this in their API by passing the API Key in the Authorization header.

Go

package main

import (
  "http"
  "github.com/Paypi/paypi-go/paypi"
)

paypi.Key = "<API_SECRET_KEY>"

func handleRequest(w http.ResponseWriter, r *http.Request) {
  // Check if a user's token is valid
  user, err := paypi.Authenticate(r.Header.Get("Authorization"))
  if err != nil {
    http.Error(w, "User token is unauthorized", http.StatusUnauthorized)
    return
  }
  
  // Carry out PDF conversion and calculate usage...
  pdfSize := 1 // PDF size in MB
  
  charge, err := user.MakeCharge(paypi.MakeChargeInput{
    ChargeIdentifier: "cid-AAAAAA",
  })
  if err != nil {
    http.Error(w, err.Message, http.StatusInternalServerError)
    return
  }
  
  charge, err := user.MakeCharge(paypi.MakeChargeInput{
    ChargeIdentifier: "cid-BBBBBB",
    UnitsUsed: pdfSize,
  })
  if err != nil {
    http.Error(w, err.Message, http.StatusInternalServerError)
    return
  }

  fmt.Fprintf(w, "Returning your JPG")
}