Skip to content

Latest commit

 

History

History
279 lines (212 loc) · 6.64 KB

client_forwarding_requests_list.md

File metadata and controls

279 lines (212 loc) · 6.64 KB
Raw

Creating a Client Forwarding Request ⇄ Status

POST https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/1114/forwarding_requests.json

Transfer money from a client donation pool to a Project. The request has to be a POST request with a JSON body.

🔒 Only available if authenticated as a client. See betterplace.org clients.

Process Flow

This flow chart describes the process….

What if the donation receiver is fully funded?

The donation will be booked in the receiver account even if the receiver is fully funded. The receiver will than show a progress percentage > 100 %. For a project that means, the project manager has to add new money needs to pay out the additional funds.

Please note that closed projects are prohibited from receiving donations.

What if the donation receiver is prohibited from receiving donations?

At the time when the forwarding request is received, the system does not check the receiver status. Therefore the API will always respond with a success message for all receivers.

Should the receiver be prohibited from receiving donations at the time when the donation is processed, the forwarding will not be inserted into the system. The forwarding request will then be marked as "failed" and the "error_reason" field holds detailed information about the problem. Learn more at Client Forwarding Request Status.

There are two possible next steps:

Option 1: Handle those cases manually with the betterplace.org-support-team. This option is only feasible in selected cases.

Option 2: The client system reacts to the error-state of the forwarding request automatically. For example by moving the donation to a fallback project.

Response and error codes:

A list of all response and error codes.

The most likely ones are:

HTTP Code 202 if a resource was successfully submitted for delayed processing. A successful request will return HTTP status 202 (accepted). The forwarding request is now saved and queued and will be processed by background workers. This part takes place asynchronously and might take up to a few minutes, especially in high traffic scenarios. Please make sure that you queue and retry your API calls until you receive clear answer (202, 422, 404, etc.) from us. Note that we will book only one donation per client_reference so there's no need to worry about retrying the forwarding.

HTTP Code 422 if the submitted resource could not be accepted due to erroneous parameters. Please remember to validate all user input on your side before submitting it to the API.

HTTP Code 404 if a requested resource could not be found. This might happen if the resource has been deleted in the timeframe between selection by the user and confirmation of the forwarding request by the client. In this case, either contact your user and change the resource (most likely a project) or redirect the donation to the client pool (the URL is provided by betterplace.org).

URL Parameters

Parameter Example Required Description
client_id volksfreund yes

The betterplace.org-internal client permalink.
project_id 1114 yes

Project id as an integer number ≥ 14.

JSON Parameters

JSON parameters have to be provided in the body of the request with the Content-Type header set to "application/json". The parameters are part of a flat JSON document without any nesting. Some parameters are required, others are optional.

Example

{
  "amount_in_cents": 100,
  "client_reference": "djksbf23u4sjkdn234p",
  "tracking_via": "campaign-0815"
}

Supported Parameters

Parameter Example Types Required Description
amount_in_cents 100 number yes

The amount of cents that are forwarded. Must be a positive integer between 1 and 1000000.
client_reference djksbf23u4sjkdn234p string yes

A unique identifier for this transaction. With this reference one can find the donation and its status later by using the client_reference-facet on the donation list endpoint.
Allowed characters are a-zA-Z0-9_-.
Attention: If you use a non-unique client reference, the donation pledge endpoint will still respond with success. However the pledge will not be processed into a donation but ignored.
This is to make sure that one transaction is only processed once.
tracking_via campaign-0815 string no

A tracking identifier for the current campaign, origin or similar information. Default is blank.
Allowed characters are a-zA-Z0-9_-.

Response Attributes

Root Attributes

Attribute Types Example Description
status string accepted

HTTP status code as a descriptive string. For a list of codes, see httpstatus.es. Example: "accepted" for code 202
status_code number 202

HTTP status code as an integer number, e.g. 202.

Response Links

Linkname Description

location

Location where the created/updated resource can be viewed or more information about it can be gathered.

Response Example

{
  "status": "accepted",
  "status_code": 202,
  "links": [
    {
      "rel": "location",
      "href": "https://api.betterplace.dev/de/api_v4/clients/some_client/forwarding_requests/1337"
    }
  ]
}