API Documentation:Billing: Application Charge APIs
Go back to read introductory information about the billing API and its usage guidelines.
The ApplicationCharge request is performed to charge merchant a fee during the app installation. The request includes
- plan_name - charge name appears on owners invoice
- plan_price - the price your application charging
- return_url - the url Yahoo Commerce Central redirecting to the merchant site after they had accepted or declined the charges.
Figure: The figure Above details the typical create application charge workflow as explained in this section
App Installation After the developer app was created and published on the Commerce Central App Gallery, The merchants can thereafter search and install those apps onto their websites. The workflow to install the apps is outlined as here below:
-
Merchant clicks install app button in Yahoo Commerce Central app gallery page.
-
Commerce Central then redirects control over to the app's welcome_url page that was configured during the developer portal app on-boarding process. The redirect url contains parameters that allows you to create API store connection password as described in our API documentation. Here's an example of the redirect URL: http://your_app.com/?store_url=<store_url>&pid=<commerce_central_store_id>×tamp=1484251365&token=&app_token=<app_token>&email=<customer_email>&p=<store_type>&id=&signature=
NOTE: Refer to the API documentation link above to create the right values of the URL parameters.
-
Once redirected, the app should presents the merchant any other information that is needed for the completing the installation like plan selection and other App specific settings that merchant needs configuring.
-
After the app configuration and plan/price details are picked/configured by the merchants, the app then makes the Commerce Central's ADD charge API call.
This request includes a return_url, which is used by Commerce Central for any subsequent steps. The API response data from Commerce Central also includes: - ID - A Charge ID specific to the current installation which would be used in further calls to confirm / activate. - Confirmation_URL - The Commerce Central URL to which you have to redirect, after this response is consumed (along with any other details).
-
The app can then verify the response of the ADD which would contain the Plan, Price details and then redirect to the confirmation_url received in the ADD response.
-
Commerce Central renders a page with the selected plan and price for the merchant to accept/decline the selections. If accepted, the payment flow is completed and Commerce Central would confirm ( but not activate ) the charge in our system.
-
As payment is confirmed, Commerce Central would redirect to the return_url previously provided by the app, during the ADD call.
-
The app can now request the status of the charge using a GET
This call lets the app know, if the merchant had accepted/declined the charge. So, if the merchant had, - Accepted - Then the charge status will be marked as "pending" and you can activate calling the ACTIVATE endpoint. - Declined - The charge status will be set to "new" and you can delete the charge calling the CANCEL endpoint. -
An one-time Application charge will be created with "pending" status on Commerce Central side. The app can then perform one of the following actions on this charge: - Activate - Charge the merchant's payment method which was authorized earlier. - Modify - Change the plan or price associated - Each merchant can only have one active charge per application. - When a new ApplicationCharge is activated, the existing charge will be cancelled and replaced by the new charge and effective from the next billing cycle. - Cancel - Cancel the monthly payment/ subscription. - The ApplicationCharge will be cancelled and status is set to as cancelled by merchant. The billing cycle is stopped right after current cycle ends. Therefore the App is expected to continue working until the billing period ends.
Update App Plan details
- When the merchant wants to update their current plan, the app is expected to call create charge with the new plan details and obtain a new charge-id. the rest of the workflow to update the plans would remain the identical to the original create plan flow as detailed above. NOTE: There are a few caveats for the plan updates to take effect such as,
- The new charge has to be activated to be effective and replace the original plan charges.
- The updates occurring in the middle of a billing period would be effective only from start of the next billing cycle.
- At any instance there would always be only one charge in effect for the merchant during a billing cycle.
- All the pending charges not in the activated state would automatically be deleted and purged by the system by 48 hours., App Developers are therefore expected to verify the charge_id before further changes or obtain a new charge-id.
- PENDING - The first status of the charge when it is created.
- ACCEPTED - Once the merchant "Accepts" the charge, the status moves to ACCEPTED
- ACTIVE - Once Commerce Central's "Activate" API is called by the app, the merchant is charged and the status moves to this. Unless the Activate API is called, the merchant is not charged and the status remains in ACCEPTED.
- MERCHANT_CANCELLED - If the merchant uninstalls the app, the charge status moves to this status
- UPDATE_CANCELLED - If current charges were superseded by a newly activated charge(charge-id) the current charges is set to this state.
- COMPLETED - This would applicable only for charge of type one-time upon their activation.
- DELETED - This would be applicable for charges that were not confirmed within the stipulated period and got swept out of the DB also it includes the charges that were deleted by the users after being accepted. Such DELETED charges would not make it part of a GET Charge call and would result in a 404 as they are no longer available for updates.
NOTES:
- ERRORS in any part of the flows would not change the state of the Charges , therefore it is recommended to do a GET charge call to confirm the state of the charge ( by using the charge_id identifiers).
All the APIs are HTTP authenticated and all calls should be in the following format:
https://APP_TOKEN:PASSWORD@api.lexity.com/api/v1/store/<STORE_ID>/<ENDPOINT>
Charge request for app installation
POST /application_charges.json
Request data
{
"applicationCharge":{
"plan_price":"9.99",
"plan_name":"Basic plan",
"return_url":"http://thirdpartyapp.com/return_to_url"
}
}
HTTP/1.1 201 OK
{
"applicationCharge": {
"id":"CHARGE_ID",
"name":"Basic plan",
"price":"9.99",
"status":"pending",
"return_url":"http://localhost:3000/",
"billing_on":"",
"created_at":"2017-01-12 01:35:59",
"updated_at":"2017-01-12 01:35:59",
"test":"false",
"decorated_return_url":"http://your_app.com/return_to_url/?charge_id=CHARGE_ID",
"confirmation_url":"https://commercecentral.luminate.com/apps/your_app/install_confirm?charge_id=CHARGE_ID"
}
}
Request
PUT /application_charges/activate.json
Request data
{
"applicationCharge": {
"id": "14750024276"
}
}
Example response
HTTP/1.1 200 Created
{
"version":"1.0",
"applicationCharge":
{
"id":"14750024276"
}
}
Request
DELETE /application_charges/cancel.json
Request data
{
"applicationCharge": {
"id": "CHARGE_ID"
}
}
Example response (No Content)
HTTP/1.1 204 Ok
GET /application_charges/CHARGE_ID.json
Request data
HTTP/1.1 200 OK
{
"applicationCharge": {
"id":"CHARGE_ID",
"name":"Basic plan",
"price":"9.99",
"status":"PENDING/ACCEPTED/ACTIVE/CANCELLED_BY_MERCHANT",
"created_at":"2017-01-12 01:35:59",
"updated_at":"2017-01-12 01:35:59",
"test":"false",
}
}