RecurringApplicationCharge

Request to charge a shop a recurring fee (every 30 days) by issuing this call with the name the charge should appear under (on the shop owner’s invoice), the price your application is charging, and a return_url to where haravan will redirect the shop owner to after they have accepted or declined the charge.


Setting the test flag to true will set the RecurringApplicationCharge to not actually charge the credit card it otherwise would.

After this request returns, an RecurringApplicationCharge has been created, but is held in a pending state until the shop owner has accepted or declined it.

Proceed by redirecting the shop owner to the confirmation_url set in the response where they may accept or decline the charge.

After the charge has been accepted or declined, haravan redirects the shop owner to the return_url set in the request. At this point the shop is either in an accepted or declined state. In order to actually receive payment for this charge it must be activated by your application.

Updating

Each shop may have only one recurring charge per application.

When a new RecurringApplicationCharge is activated for a shop that already has a recurring charge for that application, the existing recurring charge will be cancelled and replaced by the new charge. The new recurring charge will then activate.

This means that upgrading and downgrading a user’s recurring charge or plan is straightforward; just change their plan, have them accept, and haravan takes care of the rest.

Reminder

Test or demo shops may not be charged.

What can you do with RecurringApplicationCharge?

The haravan API lets you do the following with the RecurringApplicationCharge resource. More detailed versions of these general actions may be available:

RecurringApplicationCharge Properties

activated_on
{ "activated_on" : "null" }

The date and time when the customer activated the recurring application charge. The API returns this value in ISO 8601 format.
Note: The recurring application charge must be activated or the returning value will be "null".

billing_on
{ "billing_on" : "null" }

The date and time when the customer will be billed. The API returns this value in ISO 8601 format.
Note: The recurring application charge must be accepted or the returning value will be "null".

cancelled_on
{ "cancelled_on" : "null" }

The date and time when the customer cancelled their recurring application charge. The API returns this value in ISO 8601 format.
Note: If the recurring application charge is not cancelled it will default to "null".

confirmation_url
{ "confirmation_url" : "https://apple.myharavan.com/admin/charges/confirm_recurring_application_charge?id=654381177&signature=BAhpBHkQASc%3D--374c02da2ea0371b23f40781b8a6d5f4a520e77b" }

The URL that the customer is taken to, to accept or decline the recurring application charge.

created_at
{ "created_at" : "2013-06-27T08:48:27-04:00" }

The date and time when the recurring application charge was created. The API returns this value in ISO 8601 format.

id
{ "id" : 675931192 }

A unique numeric identifier for the recurring application charge.

name
{ "name" : "Super Duper Expensive action" }

The name of the recurring application charge.

price
{ "price" : "100" }

The price of the the recurring application charge.

return_url
{ "return_url" : "http://super-duper.haravanapps.com" }

The URL the customer is sent to once they accept/decline a charge.

test
{ "test" : "null" }

States whether or not the application charge is a test transaction. Valid values are "true" or "null".

trial_days
{ "trial_days" : "0" }

Number of days that the customer is eligible for a free trial.

trial_ends_on
{ "trial_ends_on" : "null" }

The date and time when the free trial ends. The API returns this value in ISO 8601 format.

updated_at
{ "updated_at" : "2013-06-27T08:48:27-04:00" }

The date and time when the recurring application charge was last updated. The API returns this value in ISO 8601 format.

Endpoints

POST/admin/recurring_application_charges.json

Create a new charge called 'Super Duper Plan' for $10.00 USD per month

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.haravanapps.com"
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "activated_on": null,
    "api_client_id": 755357713,
    "billing_on": null,
    "cancelled_on": null,
    "created_at": "2015-03-28T13:32:52-04:00",
    "id": 654381177,
    "name": "Super Duper Plan",
    "price": "10.00",
    "return_url": "http:\/\/super-duper.haravanapps.com",
    "status": "pending",
    "test": null,
    "trial_days": 0,
    "trial_ends_on": null,
    "updated_at": "2015-03-28T13:32:52-04:00",
    "decorated_return_url": "http:\/\/super-duper.haravanapps.com?charge_id=654381177",
    "confirmation_url": "https:\/\/apple.myharavan.com\/admin\/charges\/654381177\/confirm_recurring_application_charge?signature=BAhpBHkQASc%3D--e354650331e8dc1167f6f1ff023a42977f196159"
  }
}

Create a recurring test charge that will not cause a credit card to be charged

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.haravanapps.com",
    "test": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "activated_on": null,
    "api_client_id": 755357713,
    "billing_on": null,
    "cancelled_on": null,
    "created_at": "2015-03-28T13:32:52-04:00",
    "id": 654381178,
    "name": "Super Duper Plan",
    "price": "10.00",
    "return_url": "http:\/\/super-duper.haravanapps.com",
    "status": "pending",
    "test": true,
    "trial_days": 0,
    "trial_ends_on": null,
    "updated_at": "2015-03-28T13:32:52-04:00",
    "decorated_return_url": "http:\/\/super-duper.haravanapps.com?charge_id=654381178",
    "confirmation_url": "https:\/\/apple.myharavan.com\/admin\/charges\/654381178\/confirm_recurring_application_charge?signature=BAhpBHoQASc%3D--dea22b020dc91111228e3904f42af4fd53b94eab"
  }
}

Create a new charge with a trial period. The trial period will go into effect at the time the recurring charge is activated.

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": "Super Duper Plan",
    "price": 10.0,
    "return_url": "http:\/\/super-duper.haravanapps.com",
    "trial_days": 5
  }
}
View Response
HTTP/1.1 201 Created
{
  "recurring_application_charge": {
    "activated_on": null,
    "api_client_id": 755357713,
    "billing_on": null,
    "cancelled_on": null,
    "created_at": "2015-03-28T13:32:52-04:00",
    "id": 654381179,
    "name": "Super Duper Plan",
    "price": "10.00",
    "return_url": "http:\/\/super-duper.haravanapps.com",
    "status": "pending",
    "test": null,
    "trial_days": 5,
    "trial_ends_on": null,
    "updated_at": "2015-03-28T13:32:52-04:00",
    "decorated_return_url": "http:\/\/super-duper.haravanapps.com?charge_id=654381179",
    "confirmation_url": "https:\/\/apple.myharavan.com\/admin\/charges\/654381179\/confirm_recurring_application_charge?signature=BAhpBHsQASc%3D--b39f92767727130053675078d6a051f9cf86f7a7"
  }
}

Trying to create a charge without a price and name will return an error

POST /admin/recurring_application_charges.json
{
  "recurring_application_charge": {
    "name": ""
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ],
    "price": [
      "must be greater than zero"
    ]
  }
}
GET/admin/recurring_application_charges/455696195.json
fields

comma-separated list of fields to include in the response

Retrieve a single charge

GET /admin/recurring_application_charges/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charge": {
    "activated_on": null,
    "api_client_id": 755357713,
    "billing_on": "2015-03-27T00:00:00+00:00",
    "cancelled_on": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "id": 455696195,
    "name": "Super Mega Plan",
    "price": "15.00",
    "return_url": "http:\/\/yourapp.com",
    "status": "pending",
    "test": null,
    "trial_days": 0,
    "trial_ends_on": null,
    "updated_at": "2015-03-28T13:31:19-04:00",
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195",
    "confirmation_url": "https:\/\/apple.myharavan.com\/admin\/charges\/455696195\/confirm_recurring_application_charge?signature=BAhpBENfKRs%3D--a911ece9470850c96f6c7735c684b8a3f6869594"
  }
}
GET/admin/recurring_application_charges.json

All past and present recurring charge requests are retrieved by this request.

since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Retrieving all recurring charges

GET /admin/recurring_application_charges.json
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charges": [
    {
      "activated_on": null,
      "api_client_id": 755357713,
      "billing_on": "2015-03-27T00:00:00+00:00",
      "cancelled_on": null,
      "created_at": "2015-03-28T13:31:19-04:00",
      "id": 455696195,
      "name": "Super Mega Plan",
      "price": "15.00",
      "return_url": "http:\/\/yourapp.com",
      "status": "accepted",
      "test": null,
      "trial_days": 0,
      "trial_ends_on": null,
      "updated_at": "2015-03-28T13:32:52-04:00",
      "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195"
    }
  ]
}

Retrieving all recurring charges since a specified ID

GET /admin/recurring_application_charges.json?since_id=455696195
View Response
HTTP/1.1 200 OK
{
  "recurring_application_charges": [
    {
      "activated_on": null,
      "api_client_id": 755357713,
      "billing_on": null,
      "cancelled_on": null,
      "created_at": "2015-03-28T13:32:53-04:00",
      "id": 654381180,
      "name": "Super Duper Plan",
      "price": "10.00",
      "return_url": "http:\/\/super-duper.haravanapps.com",
      "status": "pending",
      "test": null,
      "trial_days": 0,
      "trial_ends_on": null,
      "updated_at": "2015-03-28T13:32:53-04:00",
      "decorated_return_url": "http:\/\/super-duper.haravanapps.com?charge_id=654381180",
      "confirmation_url": "https:\/\/apple.myharavan.com\/admin\/charges\/654381180\/confirm_recurring_application_charge?signature=BAhpBHwQASc%3D--cca69fd39e6fca8bf22db6114880ecd7cc652537"
    }
  ]
}
POST/admin/recurring_application_charges/455696195/activate.json

Activate a previously accepted recurring application charge.


Activate a recurring charge

POST /admin/recurring_application_charges/#{id}/activate.json
{
  "recurring_application_charge": {
    "activated_on": null,
    "api_client_id": 755357713,
    "billing_on": "2015-03-27T00:00:00+00:00",
    "cancelled_on": null,
    "created_at": "2015-03-28T13:31:19-04:00",
    "id": 455696195,
    "name": "Super Mega Plan",
    "price": "15.00",
    "return_url": "http:\/\/yourapp.com",
    "status": "accepted",
    "test": null,
    "trial_days": 0,
    "trial_ends_on": null,
    "updated_at": "2015-03-28T13:32:51-04:00",
    "decorated_return_url": "http:\/\/yourapp.com?charge_id=455696195"
  }
}
View Response
HTTP/1.1 200 OK
DELETE/admin/recurring_application_charges/455696195.json


Errata

Cancelled plans are not pro-rated.


Cancel the current recurring charge for a shop

DELETE /admin/recurring_application_charges/#{id}.json
View Response
HTTP/1.1 200 OK

Haravan - Công ty công nghệ cung cấp giải pháp kinh doanh thương mại điện tử, duy nhất tại Việt Nam được Google lựa chọn vào chương trình bệ phóng tiềm năng với hỗ trợ và đào tạo công nghệ để vươn ra thị trường quốc tế vững chắc.