Create a recurring donation

This POST operation creates a recurring donation by passing the donorPlanId and groupId in a JSON payload. If successful, you receive an HTTP response code of 201 and a JSON response outlining the information passed in the JSON request payload along with an auto-created id.

This operation configures a donation to be executed upon plan renewal, but does not actually donate anything at the time of the request.

Only 1 recurring donation is allowed per donor plan and donor id. The donorId is set to the group owner automatically.

See HTTP response codes for other response codes.

POST /sqs/api/recurringDonations + JSON payload

HEADER INFO

authorisation: HTTP Basic Auth

tenant: <tenantName>

content-type: application/JSON

accept: application/JSON

By default, accept is XML. You must explicitly set accept in your header to application/JSON to receive a JSON response.

permissions: SQS_RECURRING_DONATION_CREATE_UPDATE_PERMISSION

JSON request payload

You pass the donorPlanId and groupId in the JSON payload.

The owner ID|name pair must be unique as an owner cannot have two groups with the same name.

{
   "donorPlanId" : 123,
   "groupId" : "ASDS"
}

JSON response

The JSON response includes the information passed in the JSON payload with an auto-assigned id.

See recurring donation data type descriptions for more details on the fields in the JSON request and response.

{
   "id" : "E5B412",
   "donorPlanId" : 123,
   "groupId" : "ASDS",
   "donorId" : "4564563",
   "planName" : "SharePlan",
   "created": "2019-08-07T15:01:58.000+0000",
   "updated": "2019-08-07T15:01:58.000+0000"
}

SQS recurring donations data type descriptions

Field Type Description

id

string

The auto-assigned ID given to the recurring donation upon creation.

donorId

string

The MSISDN of the donor subscriber.

The subscriber’s MSISDN in international format.

donorPlanId

integer

The ID of the donor’s shareable plan.

groupId

string

The unique ID of the group. Group IDs are auto-assigned upon creation.

created

string

The date and time at which the group was created.

This is in ISO 8601 standard format.

updated

string

The date and time at which the group was updated.

This is in ISO 8601 standard format.

HTTP response codes

Code Description

201/204

success!

If you receive a 204 code, you will not see a JSON response.

207

Multistatus response

Check out HTTP statuses for more details.

This is not applicable to all operations.

400

malformed request

401

unauthorised; bad username or password

403

forbidden; user does not have appropriate privileges

404

recurring donation not found

409

conflict with target resource

This often occurs if the item already exists, such as a plan, group, or name.

This is not applicable to all operations.

412

failed validation; this typically means that a property was not set or a value is out of range.

example

HTTP 412
{
  "errors" : [
        {
          "field" : "name",
          "description" : "name is mandatory"
        }
    ]
}

422

failed processing (after passing validation).

example

HTTP 422
{
    "message": "Subscriber max plan count exceeded",
    "errorCode": 1
}

Example 1. SQS response codes

0 = no error
1 = undefined general error
2 = group owner/name pair is not unique
3 = group owner cannot be a member
4 = total member quota exceeds 100%
5 = group does not exist
6 = maximum group size exceeded
7 = the donor does not exist
8 = the shareable plan does not exist
9 = the shareable plan is not a recurring plan
10 = charging group owner unsupported
11 = the recurring donation for this plan already exists
12 = the recipient does not exist
13 = the donor plan max recipient limit was exceeded
14 = subscriber not found
15 = quota is unavailable
16 = donor plan is not shareable

500

internal error

503

request rejected due to overload