Charges

Partner Docs
Search…
Introduction
🛹
PayPI
Supported Countries (Partner)
API
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
Node JS
Python
user, _ := paypi.Authenticate("<USER_TOKEN>")
​
charge, err := user.MakeCharge(paypi.MakeChargeInput{
  ChargeIdentifier: "<CHARGE_IDENTIFIER>",
})
const user = await paypi.authenticate("<Subscriber secret>")
​
await user.makeCharge("<CHARGE_IDENTIFIER>")
# 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
Node JS
Python
user, _ := paypi.Authenticate("<USER_TOKEN>")
​
charge, err := user.MakeCharge(paypi.MakeChargeInput{
  ChargeIdentifier: "<CHARGE_IDENTIFIER>",
  UnitsUsed: 5,
})
const user = await paypi.authenticate("<Subscriber secret>")
​
const unitsUsed = 4
await user.makeCharge("<CHARGE_IDENTIFIER>", unitsUsed)
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")
}
Last modified 9mo ago
Copy link
On this page
Static Charges
Dynamic Charges
Extra Info
Charge Timings
Errors
Examples
PDF to JPG Converter