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

Importi

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

Campi anagrafici

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

Metodi di pagamento

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.

Fonte: https://dev.riseact.org/docs/checkout/custom-checkout. Copia automatica da dev.riseact.org: non modificare qui, le modifiche vanno fatte sulla documentazione Docusaurus.