> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt > Use this file to discover all available pages before exploring further. # Initialize a Flutterwave v4 campaign charge > Starts the direct-card Flutterwave v4 charge flow for a public campaign donation. The controller creates or refreshes a frontend session, validates card or saved-payment-method input, validates designation items against the client/program, enforces checkout settings such as single-designation mode, creates or reuses a Flutterwave customer/payment method, creates the charge, stores charge state in Redis, and returns the provider charge status plus any next action. Existing donors must verify their checkout session before using saved payment methods. ## OpenAPI ````yaml post /frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id} openapi: 3.0.0 info: title: Gratona API description: >- REST API for the Gratona fundraising platform, including donor, donation, sponsorship, program, event, and integration workflows. Endpoints are organized by tag. Most endpoints require either a Passport bearer token or an issued API key — see the Security Schemes section. contact: name: Gratona Engineering url: https://gratona.com email: devs@gratona.com version: 1.0.0 servers: - url: https://api.gratona.com/v1 description: Server Version 1.0.0 security: [] tags: - name: Auth description: >- Login, signup, logout, password reset, and email verification for admin users and donors. - name: Donors description: >- Donor records: CRUD, profile fields, household linkage, search, filters, merge, and duplicate detection. - name: Donations description: >- Individual donation records, recurring commitments, soft credits, refunds, designations, and exports. - name: Sponsorships description: >- Donor-to-entity sponsorship relationships, lifecycle transitions, and sponsorship-specific filters. - name: Entities description: >- Recipient records (children, families, projects, animals, etc.), their status, and entity-level fields. - name: Programs description: >- Program / campaign configuration: hierarchy, settings, and program-level metadata. - name: Forms description: >- Custom form builder (HysForm), form fields, standardized donor fields, and field migrations. - name: Trips description: >- Mission-trip management: trips, participants, budgets, tasks, e-signatures, fundraising milestones, and background checks. - name: Communications description: >- Email templates, SMS, newsletters, donor email manager, and per-donor notes. - name: Payments description: >- Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks). Excludes inbound webhooks — see the Webhooks tag. - name: Reports description: Dashboards, analytics, scheduled reports, and exports. - name: Admin description: >- Client-account administration: users, groups/permissions, settings, integrations, and account lifecycle. - name: Donor Portal description: >- Endpoints consumed by the donor-facing portal (donor login, dashboard, donation history, messages). - name: Recipient Portal description: Endpoints consumed by the recipient-facing portal. - name: Public description: >- Unauthenticated public endpoints: donor signup, public trip pages, peer-to-peer campaigns, public checkout. - name: Webhooks description: >- Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr, DropboxSign). Annotated minimally for reference; payload shapes are owned by the upstream provider. - name: Client description: Client - name: Email Settings description: Email Settings - name: Admin Dashboard description: Admin Dashboard - name: Historical Archived Updates description: Historical Archived Updates - name: Team & access description: Team & access - name: Files description: Files - name: Wrapped description: Wrapped - name: Donor SignUp description: Donor SignUp - name: Frontend description: Frontend - name: User description: User paths: /frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}: post: tags: - Payments summary: Initialize a Flutterwave v4 campaign charge description: >- Starts the direct-card Flutterwave v4 charge flow for a public campaign donation. The controller creates or refreshes a frontend session, validates card or saved-payment-method input, validates designation items against the client/program, enforces checkout settings such as single-designation mode, creates or reuses a Flutterwave customer/payment method, creates the charge, stores charge state in Redis, and returns the provider charge status plus any next action. Existing donors must verify their checkout session before using saved payment methods. operationId: initializeFlutterwaveV4CampaignCharge parameters: - name: client_id in: path description: >- Client id that owns the campaign program, gateway configuration, entities, and checkout session. required: true schema: type: integer example: 207 - name: program_id in: path description: >- Campaign program id. Designation entity ids must belong to this program. required: true schema: type: integer example: 11 - name: session_id in: path description: >- Optional Redis frontend session id used to store and later validate the Flutterwave charge state. required: true schema: type: string example: 7f2c8f8d64b8a1d4a9e2 requestBody: description: >- Campaign checkout card details or saved payment method plus designation amount data. required: true content: application/json: schema: required: - email - paymentMethod properties: email: description: 'Donor email. Validator rule: `required|email`.' type: string format: email example: jane@example.org paymentMethod: description: >- Payment method family. Validator rule: `required|string|in:credit_card`. type: string enum: - credit_card example: credit_card payment_method: description: >- Saved Flutterwave payment method id. When present it replaces card field requirements and must belong to a verified session donor. type: string example: pm_123 nullable: true card_number: description: >- Card number required when `payment_method` is absent. Alias `number` is normalized to this field. type: string example: '5531886652142950' nullable: true cvv: description: Card CVV required when `payment_method` is absent. type: string example: '564' nullable: true expiry_month: description: >- Two-digit card expiry month required when `payment_method` is absent. Aliases are normalized from `expiryMonth` or `cardExpiry`. type: string example: '09' nullable: true expiry_year: description: >- Two-digit card expiry year required when `payment_method` is absent. Aliases are normalized from `expiryYear` or `cardExpiry`. type: string example: '32' nullable: true card_holder_name: description: >- Optional cardholder name. If absent, first and last name are combined. type: string example: Jane Donor nullable: true designations: description: >- Preferred campaign cart format. Validator rules require at least one item when present. type: array items: required: - entity_id - amount - frequency properties: entity_id: type: integer example: 4711 amount: type: number format: float minimum: 0.01 example: 50 frequency: type: string example: one time is_custom_amount: type: boolean example: false nullable: true type: object nullable: true entity_id: description: >- Fallback single-designation entity id required when `designations` is absent. type: integer example: 4711 nullable: true amount: description: >- Fallback amount required without `designations` unless `donation_amount` is supplied. type: number format: float minimum: 0.01 example: 50 nullable: true donation_amount: description: >- Legacy fallback amount alias required without `designations` unless `amount` is supplied. type: number format: float minimum: 0.01 example: 50 nullable: true additional_gifts: description: >- Optional extra designation gifts admitted by the checkout program and donor form. type: array items: required: - designation_id - amount properties: designation_id: description: >- Client-owned designation id; required with an additional gift. type: integer example: 88 amount: description: Gift amount; required, numeric and at least 0.01. type: number minimum: 0.01 example: 10 attach_to_other_entity: description: Whether this extra gift targets another recipient. type: boolean example: false nullable: true other_entity_id: description: >- Optional recipient id validated against the checkout routing settings. type: integer example: 4711 nullable: true type: object nullable: true peer_to_peer_allow_multi_designations: description: >- Peer-to-peer override that can allow multiple designations even when program settings normally disallow them. type: boolean example: true nullable: true type: object responses: '200': description: Flutterwave charge initialized. content: application/json: schema: properties: status: type: string example: success session_id: type: string charge_status: type: string nullable: true data: type: object next_action: type: object nullable: true type: object '404': description: Program was not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: >- Validation failed, gateway missing, duplicate donor verification required, or saved payment method was invalid. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: Unexpected checkout failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: Flutterwave provider failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: [] components: schemas: NotFoundResponse: title: NotFoundResponse description: >- Returned with HTTP 404 when a resource lookup misses (typically because the id doesn't exist OR is scoped to a different `client_id`). Note: many endpoints intentionally collapse 'not found' and 'forbidden' into a single 404 to avoid leaking which records exist in another tenant. required: - message properties: message: description: >- Human-readable message. Often a more specific string like `Donor not found` or `Trip not found`. type: string example: Not Found status: type: string example: error type: object ValidationErrorResponse: title: ValidationErrorResponse description: >- Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The `errors` map is keyed by the failing field name; each value is an array of human-readable error messages for that field. Most controllers also include a top-level `status: error`. required: - errors properties: errors: description: >- Map of field name to array of validator error messages. Example: `{email: [The email field is required.], amount: [The amount must be a number.]}`. type: object additionalProperties: type: array items: type: string status: description: Always the literal string `error`. type: string example: error message: description: >- Optional summary message — present on some endpoints, absent on others. type: string example: The given data was invalid. nullable: true type: object ErrorResponse: title: ErrorResponse description: >- Generic error envelope used by most controllers. Most error responses pair a human-readable `message` with `status: error`. Some endpoints additionally include `errors` (validator errors), `error` (legacy single-error string), `code`, or domain-specific context fields. required: - message properties: message: description: Human-readable error message. type: string example: Something went wrong. Please try again. status: description: >- Always the literal string `error` for failures. Some endpoints omit this field. type: string example: error error: description: Legacy single error code/string used by older endpoints. type: string example: invalid_request nullable: true code: description: >- Optional application-level error code (not all endpoints populate this). type: string example: DONOR_NOT_FOUND nullable: true type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.