Build your own custom checkout

You can build a custom donation form using Riseact's authenticated APIs, called from your backend. Your frontend collects the data, your backend sends it to Riseact and records the donation.

Prerequisites

You need an access token from a Riseact private application. See Private applications for how to obtain one.

---

Two main scenarios

Manual payment (e.g. bank transfer)

Your backend creates the donation directly in a single call. The donor is instructed to pay offline (e.g. with the account details). No interaction with Stripe/PayPal is needed.

1. Frontend sends the data to your backend
2. Your backend calls POST /admin/api/v1/checkouts/
3. Donation recorded with CLOSED state

Online payment (Stripe, PayPal, Satispay)

Your backend creates a pre-filled checkout and obtains a token. The user is redirected to the Riseact checkout to complete the payment. You use a webhook to know when the donation is confirmed.

1. Frontend sends the data to your backend
2. Your backend calls checkout_create (GQL) - obtains a token
3. Your backend redirects the user to the Riseact checkout (?co=token)
4. User completes the payment
5. Riseact sends a checkout.paid webhook to your backend

---

Campaign configuration

The campaign configuration determines how the form behaves: which frequencies are enabled, which fields to show, which amounts to suggest. It should be read when the form starts up in order to build the UI correctly.

The configuration is managed from the Riseact campaign detail panel.

Endpoint

GraphQL - POST https://core.riseact.org/admin/graphql/

query {
  campaign(id: 123) {
    id
    title
    slug
    has_one_off
    has_subscription
    allow_custom_amount
    allow_custom_subscription_amount
    default_amount
    default_subscription_amount
    min_amount
    max_amount
    asks
    asks_subscription
    shown_fields
    required_fields
    privacy_note
    excluded_payment_methods
  }
}

REST - GET https://core.riseact.org/admin/api/v1/campaigns/{id}

curl https://core.riseact.org/admin/api/v1/campaigns/123 \
  -H "Authorization: Bearer <token>"

Response fields

Enabled frequencies

Field	Type	Description
has_one_off	bool	One-time donation enabled
has_subscription	bool	Monthly donation enabled

Use these fields to show or hide the frequency options in the form.

Amounts

Field	Type	Description
default_amount	decimal|null	Default amount for one-time donations
default_subscription_amount	decimal|null	Default amount for monthly donations
min_amount	decimal|null	Minimum accepted amount (one-time)
max_amount	decimal|null	Maximum accepted amount (one-time)
min_subscription_amount	decimal|null	Minimum amount for monthly donations
max_subscription_amount	decimal|null	Maximum amount for monthly donations
asks	list[decimal]|null	Suggested quick amounts (one-time). E.g. ["10.00", "25.00", "50.00"]
asks_subscription	list[decimal]|null	Suggested quick amounts (monthly)
allow_custom_amount	bool	The donor can enter a free amount (one-time)
allow_custom_subscription_amount	bool	The donor can enter a free amount (monthly)

If allow_custom_amount is false and asks is set, the donor can only choose among the suggested amounts.

Personal fields

Field	Type	Description
shown_fields	list[string]|null	Fields to show in the form. See supported values
required_fields	list[string]|null	Required fields. Must be a subset of shown_fields
privacy_note	string|null	Privacy information text to show before the consent

A field in required_fields but not in shown_fields is neither shown nor validated. A field in shown_fields but not in required_fields is optional.

Payment methods

Field	Type	Description
excluded_payment_methods	list[int]	IDs of the payment methods disabled for this campaign

Each campaign can limit the payment methods that can be used. By default no method is excluded: all those available for the organization are allowed. The methods actually offered by a checkout are the result of the intersection between the methods enabled on the channel and those not excluded by the campaign.

The checkout hosted by Riseact already applies this filter. In a custom checkout, exclude from excluded_payment_methods the IDs you offer to the donor in order to stay consistent with the campaign configuration.

---

2a. Create a donation with manual payment

Via REST

Endpoint: POST https://core.riseact.org/admin/api/v1/checkouts/

curl -X POST https://core.riseact.org/admin/api/v1/checkouts/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_slug": "nome-campagna",
    "amount": "25.00",
    "frequency": "ONEOFF",
    "payment_method_id": 3,
    "supporter_data": {
      "first_name": "Mario",
      "last_name": "Rossi",
      "email": "mario.rossi@esempio.it",
      "country": "IT",
      "privacy": true
    }
  }'

frequency: "ONEOFF" = one-time, "MONTHLY" = monthly.

payment_method_id: ID of the manual payment method configured on Riseact (type MANUAL, e.g. bank transfer). You can find it in the organization settings or through a GQL query.

With payment_method_id set to a MANUAL method, the checkout is created and immediately closed: the donation is recorded with CLOSED state and the payment as PAID.

Response:

{
  "id": 456,
  "state": "CLOSED",
  "amount": "25.00",
  "frequency": "ONEOFF",
  "completed_date": "2024-03-15T10:30:00Z",
  "campaign_id": 123,
  "supporter_id": 789,
  "donation_id": 101,
  "payment_id": 202
}

---

Via GraphQL

Endpoint: POST https://core.riseact.org/admin/graphql/

mutation {
  checkout_create(data: {
    campaign_id: 123,
    amount: 25.00,
    frequency: ONEOFF,
    payment_method_id: 3,
    supporter_data: {
      first_name: "Mario",
      last_name: "Rossi",
      email: "mario.rossi@esempio.it",
      country: "IT",
      privacy: true
    }
  }) {
    id
    state
    donation_id
    supporter_id
  }
}

---

2b. Create a pre-filled checkout for online payment

Use GraphQL to obtain the token needed for the redirect.

mutation {
  checkout_create(data: {
    campaign_id: 123,
    amount: 25.00,
    frequency: ONEOFF,
    supporter_data: {
      first_name: "Mario",
      last_name: "Rossi",
      email: "mario.rossi@esempio.it",
      country: "IT",
      privacy: true
    }
  }) {
    id
    token
    state
  }
}

The checkout is created in OPEN state - no donation recorded yet.

Response:

{
  "data": {
    "checkout_create": {
      "id": 456,
      "token": "550e8400-e29b-41d4-a716-446655440000",
      "state": "OPEN"
    }
  }
}

Redirect to the Riseact checkout

Redirect the user to the Riseact checkout with the token. The data entered by the backend is already filled in and the checkout jumps directly to the payment step.

https://<org-slug>.riseact.site/campaigns/<slug>/donate?co=<token>

Upon payment completion, the checkout moves to CLOSED state and the donation is recorded.

---

3. Receive the completion notification

Configure a webhook on Riseact to receive a notification when the checkout is confirmed.

Topic: checkout.paid

{
  "topic": "checkout.paid",
  "data": {
    "id": 456,
    "state": "CLOSED",
    "donation_id": 101,
    "supporter_id": 789,
    "amount": "25.00",
    "frequency": "ONEOFF"
  }
}

See the Webhook documentation to configure the endpoint.