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 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 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)
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.
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.
Some examples of using charges in different API scenarios.
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 1yr ago