Build your own custom checkout

Your frontend collects the data, your backend sends it to Riseact's authenticated APIs, which record the donation.

Prerequisites

You need an access token from a private application.

Two scenarios

Manual payment (e.g. bank transfer)

The backend creates the donation with a single call; the donor pays offline.

1. The frontend sends the data to your backend.
2. The backend calls POST /admin/api/v1/checkouts/.
3. The donation is recorded with CLOSED state.

Online payment (Stripe, PayPal, Satispay)

The backend creates a prefilled checkout and the donor pays on the Riseact checkout.

1. The frontend sends the data to your backend.
2. The backend calls checkout_create (GraphQL) and obtains a token.
3. The backend redirects the donor to the Riseact checkout (?co=<token>).
4. The donor completes the payment.
5. Riseact sends the checkout.paid webhook to your backend.

Campaign configuration

The campaign sets the enabled frequencies, the fields to show and the amounts to suggest. Read it when the form starts to build the interface. It is edited from the campaign detail on Riseact.

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

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
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.

Payment methods

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

By default no method is excluded. The checkout offers the methods enabled on the channel and not excluded by the campaign: the Riseact one already applies this filter, in a custom checkout do not offer the IDs listed in excluded_payment_methods.

Manual payment: create the donation

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) or "MONTHLY" (monthly).
• payment_method_id: ID of a payment method of type MANUAL (e.g. bank transfer), from the organization settings or a GraphQL query.

With a MANUAL method the checkout is created and closed right away: donation in CLOSED state, payment 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
  }
}

Online payment: create a prefilled checkout

GraphQL returns the token 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 starts in OPEN state, with no donation recorded.

Response:

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

Redirect to the Riseact checkout

Redirect the donor to the checkout with the token: the data is already filled in and the checkout starts at the payment step.

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

When the payment is complete the checkout moves to CLOSED and the donation is recorded.

Completion notification

To know when the checkout is paid, configure a webhook on Riseact.

Topic: checkout.paid

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

To configure the endpoint see Webhook.