Crea il tuo checkout personalizzato

Puoi costruire un form di donazione custom usando le API autenticate di Riseact, chiamate dal tuo backend. Il tuo frontend raccoglie i dati, il tuo backend li invia a Riseact e registra la donazione.

Prerequisiti

Serve un token di accesso da un'applicazione privata Riseact. Consulta Applicazioni private per come ottenerlo.

---

Due scenari principali

Pagamento manuale (es. bonifico bancario)

Il tuo backend crea la donazione direttamente in un'unica chiamata. Il donatore viene istruito a pagare offline (es. con i dati del conto). Non serve interazione con Stripe/PayPal.

1. Frontend invia i dati a tuo backend
2. Tuo backend chiama POST /admin/api/v1/checkouts/
3. Donazione registrata con stato CLOSED

Pagamento online (Stripe, PayPal, Satispay)

Il tuo backend crea un checkout pre-compilato e ottiene un token. L'utente viene reindirizzato al checkout Riseact per completare il pagamento. Usi un webhook per sapere quando la donazione è confermata.

1. Frontend invia i dati a tuo backend
2. Tuo backend chiama checkout_create (GQL) — ottiene token
3. Tuo backend reindirizza l'utente al checkout Riseact (?co=token)
4. Utente completa il pagamento
5. Riseact invia webhook checkout.paid a tuo backend

---

Configurazione della campagna

La configurazione della campagna determina come si comporta il form: quali frequenze sono abilitate, quali campi mostrare, quali importi proporre. Va letta all'avvio del form per costruire l'UI correttamente.

La configurazione si gestisce dal pannello di dettaglio campagna di 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
  }
}

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

Usa questi campi per mostrare o nascondere le opzioni di frequenza nel form.

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. Vedi valori supportati
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 mostrato né validato. Un campo in shown_fields ma non in required_fields è opzionale.

---

2a. Crea una donazione con pagamento manuale

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, "MONTHLY" = mensile.

payment_method_id: ID del metodo di pagamento manuale configurato su Riseact (tipo MANUAL, es. bonifico). Puoi trovarlo nelle impostazioni dell'organizzazione o tramite query GQL.

Con payment_method_id impostato su un metodo MANUAL, il checkout viene creato e immediatamente chiuso: la donazione è registrata con stato CLOSED e il pagamento come 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
  }
}

---

2b. Crea un checkout pre-compilato per pagamento online

Usa GraphQL per ottenere il token necessario al 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 viene creato in stato OPEN — nessuna donazione ancora registrata.

Risposta:

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

Redirect al checkout Riseact

Reindirizza l'utente al checkout Riseact con il token. I dati inseriti dal backend sono già compilati e il checkout salta direttamente al passo di pagamento.

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

Al completamento del pagamento, il checkout passa a stato CLOSED e la donazione viene registrata.

---

3. Ricevi la notifica di completamento

Configura un webhook su Riseact per ricevere una notifica quando il checkout è confermato.

Topic: checkout.paid

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

Consulta la documentazione Webhook per configurare l'endpoint.