Per the Weebly App Developer Agreement, you must report all gross revenue received from the sales of your app. Use the Payment Notifications API to report app revenue or refunds as they occur. ​See Report Revenue for details on what you need to report and when, and how to correct any reporting errors.

You need to create the code that handles the actual transactions with your customers and then use this API to report those transactions to us.

Weebly doesn’t handle payment processing from your customers. You’ll need to implement that in your app. Typically, the flow looks like this:

  • The site owner downloads and installs your app.
  • You use your OAuth redirect to send the user to a page on your site where they can pay for the app.
  • You process transaction with a service of your choice.
  • You report revenue/refunds from each transaction to us via our Payment API. To limit user access (for example if a customer didn’t pay the monthly fee), you can programmatically disconnect them.

​Before your app can be accepted into the App Center, you need to create test purchases and test refunds. See examples at the end of this topic. You can review your posted payment notifications using the Payment Log.

Fields

The following table shows all fields that exist for this API, those that are returned when you retrieve a list, those that are required for PUT and POST, and those that are changeable using PATCH and PUT. All fields are returned when you retrieve a single item.

Name Description Type Required
name A short description of the transaction string X
method Type of transaction.
Valid values are:
  • purchase
  • refund
  • testpurchase
  • testrefund
string X
kind A short string that describes the type of purchase or refund transaction
Suggested values:
  • single
  • setup
  • recurring
  • trial
  • cancel
  • upgrade
  • downgrade
string
term A short string that describes the time period for the kind of transaction
Suggested values:
  • day
  • week
  • 2week
  • month
  • 3month
  • 6month
  • year
  • 2year
  • 3year
  • forever (use for onetime charge)
string
gross_amount ​​The gross amount paid by the end user. Use negative values for refunds/credits. This amount must not include any deductions for third-party fees, such as transaction processing percentages. It must be the full amount that the user paid. decimal X
payable_amount ​The payment amount owed to Weebly. This amount should be determined using the gross_amount. Use a negative value for refunds. decimal X
currency ​Currency used for the transaction. Defaults to USD. string
detail ​Long description of transaction string
​notification_id Returned only.
The unique ID (to this site and app) for this payment notification
string
parent_notification_id ​A payment notification that is a parent to this one. Notifications have a parent when you use the the Payment Log to correct a notification. The original is deleted and the corrected notification becomes a child to the original. string
created_date Date the payment notification was created. Unix GMT Timestamp
updated_date Date the payment notification was last updated. Unix GMT Timestamp

POST
Create a Payment Notification

POST /v1/admin/app/payment_notifications

Creates a new payment notification for an app. The app and site ID are known through the OAuth token.
scope: no scope required

Createable Fields

These fields can be created:

Name Description Type Notes
name A short description of the transaction string Required
method Type of transaction.
Valid values are:
  • purchase
  • refund
  • testpurchase
  • testrefund
string Required
kind A short string that describes the type of purchase or refund transaction
Suggested values:
  • single
  • setup
  • recurring
  • trial
  • cancel
  • upgrade
  • downgrade
string
term A short string that describes the time period for the kind of transaction
Suggested values:
  • day
  • week
  • 2week
  • month
  • 3month
  • 6month
  • year
  • 2year
  • 3year
  • forever (use for onetime charge)
string
gross_amount ​​The gross amount paid by the end user. Use negative values for refunds/credits. This amount must not include any deductions for third-party fees, such as transaction processing percentages. It must be the full amount that the user paid. decimal Required
payable_amount ​The payment amount owed to Weebly. This amount should be determined using the gross_amount. Use a negative value for refunds. decimal Required
currency ​Currency used for the transaction. Defaults to USD. string
detail ​Long description of transaction string

Example CURL request:

curl --request POST \
--url https://api.weebly.com/v1/admin/app/payment_notifications
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "name": "new",
            "method": "purchase",
            "kind": "single",
            "term": "forever",
            "gross_amount": 10.00,
            "payable_amount": 3.00,
            "detail": "One-time payment for MyApp."
        }'

Example response:

{
    "user_id": "123456",
    "notification_id": "3",
    "site_id": "987654321",
    "client_id": "4567890",
    "created_date": 1486491664,
    "updated_date": 1486491664,
    "name": "new",
    "method": "purchase",
    "kind": "single",
    "term": "forever",
    "gross_amount": 10,
    "net_amount": 10,
    "payable_amount": 3,
    "currency": "USD",
    "detail": "One-time payment for MyApp.",
    "parent_notification_id": null
}

More examples

Refund

Here’s a post for a refund. Note that the amounts use negative numbers:

Example CURL request:

curl --request POST \
    --url https://api.weebly.com/v1/admin/app/payment_notifications \
    --header 'accept: application/vnd.weebly.v1+json' \
    --header 'content-type: application/json' \
    --header 'x-weebly-access-token: [YOUR_TOKEN]"' \
    --data '{
                "name": "InstallRefund",
                "method": "refund",
                "kind": "cancel",
                "term": "forever",
                "gross_amount": -10.00,
                "payable_amount": -3.00,
                "detail": "One-time refund for MyApp."
            }'

Two-tierd Payment

​Let’s look at a more complicated payment. Say your app charges a monthly subscription fee of $10.00, but then also charges a “per click” fee of .05. The monthly subscription fee is always the same, but the click fee varies each month. For this, you would post two different transactions per customer each month, like this:

Example CURL request:

curl --request POST \
    --url https://api.weebly.com/v1/admin/app/payment_notifications \
    --header 'accept: application/vnd.weebly.v1+json' \
    --header 'content-type: application/json' \
    --header 'x-weebly-access-token: [YOUR_TOKEN]"' \
    --data '{
                "name": "Click Fee",
                "method": "purchase",
                "kind": "single",
                "term": "forever",
                "gross_amount": 2.00,
                "payable_amount": .60,
                "detail": "Click fee for MyApp for Oct. 2017"
            }'

And…

curl --request POST \
    --url https://api.weebly.com/v1/admin/app/payment_notifications \
    --header 'accept: application/vnd.weebly.v1+json' \
    --header 'content-type: application/json' \
    --header 'x-weebly-access-token: [YOUR_TOKEN]"' \
    --data '{
                "name": "Subscription Fee",
                "method": "purchase",
                "kind": "recurring",
                "term": "month",
                "gross_amount": 10.00,
                "payable_amount": 3.00,
                "detail": "Payment for MyApp subscription for Oct. 2017"
            }'

Test Payment

Example curl request:

curl --request POST \
    --url https://api.weebly.com/v1/admin/app/payment_notifications \
    --header 'accept: application/vnd.weebly.v1+json' \
    --header 'content-type: application/json' \
    --header 'x-weebly-access-token: [YOUR_TOKEN]"' \
    --data '{
                "name": "Test Subscription Fee",
                "method": "testpurchase",
                "kind": "recurring",
                "term": "month",
                "gross_amount": 10.00,
                "payable_amount": 3.00,
                "detail": "Test Payment for MyApp subscription for Oct. 2017"
            }'

Help make these docs better!









Tags:
app_revenue