Crea il tuo checkout personalizzato

Il tuo frontend raccoglie i dati, il tuo backend li invia alle API autenticate di Riseact, che registrano la donazione.

Prerequisiti

Serve un token di accesso di un'applicazione privata.

Due scenari

Pagamento manuale (es. bonifico)

Il backend crea la donazione con una sola chiamata; il donatore paga offline.

1. Il frontend invia i dati al tuo backend.
2. Il backend chiama POST /admin/api/v1/checkouts/.
3. La donazione è registrata con stato CLOSED.

Pagamento online (Stripe, PayPal, Satispay)

Il backend crea un checkout precompilato e il donatore paga sul checkout Riseact.

1. Il frontend invia i dati al tuo backend.
2. Il backend chiama checkout_create (GraphQL) e ottiene un token.
3. Il backend reindirizza il donatore al checkout Riseact (?co=<token>).
4. Il donatore completa il pagamento.
5. Riseact invia il webhook checkout.paid al tuo backend.

Configurazione della campagna

La campagna stabilisce frequenze abilitate, campi da mostrare e importi da proporre. Leggila all'avvio del form per costruire l'interfaccia. Si modifica dal dettaglio della campagna su 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>"

Campi della risposta

Frequenze abilitate

Campo	Tipo	Descrizione
has_one_off	bool	Donazione una tantum abilitata
has_subscription	bool	Donazione mensile abilitata

Importi

Campo	Tipo	Descrizione
default_amount	decimal|null	Importo di default per donazioni una tantum
default_subscription_amount	decimal|null	Importo di default per donazioni mensili
min_amount	decimal|null	Importo minimo accettato (una tantum)
max_amount	decimal|null	Importo massimo accettato (una tantum)
min_subscription_amount	decimal|null	Importo minimo per donazioni mensili
max_subscription_amount	decimal|null	Importo massimo per donazioni mensili
asks	list[decimal]|null	Importi rapidi proposti (una tantum). Es. ["10.00", "25.00", "50.00"]
asks_subscription	list[decimal]|null	Importi rapidi proposti (mensili)
allow_custom_amount	bool	Il donatore può inserire un importo libero (una tantum)
allow_custom_subscription_amount	bool	Il donatore può inserire un importo libero (mensile)

Se allow_custom_amount è false e asks è valorizzato, il donatore può scegliere solo tra gli importi proposti.

Campi anagrafici

Campo	Tipo	Descrizione
shown_fields	list[string]|null	Campi da mostrare nel form
required_fields	list[string]|null	Campi obbligatori. Deve essere un sottoinsieme di shown_fields
privacy_note	string|null	Testo informativo sulla privacy da mostrare prima del consenso

Un campo in required_fields ma non in shown_fields non viene né mostrato né validato.

Metodi di pagamento

Campo	Tipo	Descrizione
excluded_payment_methods	list[int]	ID dei metodi di pagamento disabilitati per questa campagna

Di default nessun metodo è escluso. Il checkout offre i metodi abilitati sul canale e non esclusi dalla campagna: quello di Riseact applica già il filtro, in un checkout personalizzato non offrire gli ID presenti in excluded_payment_methods.

Pagamento manuale: crea la donazione

Tramite 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" (una tantum) o "MONTHLY" (mensile).
• payment_method_id: ID di un metodo di pagamento di tipo MANUAL (es. bonifico), dalle impostazioni dell'organizzazione o da una query GraphQL.

Con un metodo MANUAL il checkout viene creato e chiuso subito: donazione in stato CLOSED, pagamento PAID.

Risposta:

{
  "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
}

Tramite 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
  }
}

Pagamento online: crea un checkout precompilato

Con GraphQL ottieni il token per il 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
  }
}

Il checkout nasce in stato OPEN, senza donazione registrata.

Risposta:

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

Redirect al checkout Riseact

Reindirizza il donatore al checkout con il token: i dati sono già compilati e si parte dal passo di pagamento.

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

A pagamento completato il checkout passa a CLOSED e la donazione viene registrata.

Notifica di completamento

Per sapere quando il checkout è pagato, configura un webhook su Riseact.

Topic: checkout.paid

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

Per configurare l'endpoint vedi Webhook.