Payments

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.

POST

frontend

flutterwave-v4

campaign-charge

{client_id}

{program_id}

{session_id}

Initialize a Flutterwave v4 campaign charge

curl --request POST \
  --url https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jane@example.org",
  "paymentMethod": "credit_card",
  "payment_method": "pm_123",
  "card_number": "5531886652142950",
  "cvv": "564",
  "expiry_month": "09",
  "expiry_year": "32",
  "card_holder_name": "Jane Donor",
  "designations": [
    {
      "entity_id": 4711,
      "amount": 50,
      "frequency": "one time",
      "is_custom_amount": false
    }
  ],
  "entity_id": 4711,
  "amount": 50,
  "donation_amount": 50,
  "additional_gifts": [
    {
      "designation_id": 88,
      "amount": 10,
      "attach_to_other_entity": false,
      "other_entity_id": 4711
    }
  ],
  "peer_to_peer_allow_multi_designations": true
}
'

import requests

url = "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}"

payload = {
    "email": "jane@example.org",
    "paymentMethod": "credit_card",
    "payment_method": "pm_123",
    "card_number": "5531886652142950",
    "cvv": "564",
    "expiry_month": "09",
    "expiry_year": "32",
    "card_holder_name": "Jane Donor",
    "designations": [
        {
            "entity_id": 4711,
            "amount": 50,
            "frequency": "one time",
            "is_custom_amount": False
        }
    ],
    "entity_id": 4711,
    "amount": 50,
    "donation_amount": 50,
    "additional_gifts": [
        {
            "designation_id": 88,
            "amount": 10,
            "attach_to_other_entity": False,
            "other_entity_id": 4711
        }
    ],
    "peer_to_peer_allow_multi_designations": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'jane@example.org',
    paymentMethod: 'credit_card',
    payment_method: 'pm_123',
    card_number: '5531886652142950',
    cvv: '564',
    expiry_month: '09',
    expiry_year: '32',
    card_holder_name: 'Jane Donor',
    designations: [{entity_id: 4711, amount: 50, frequency: 'one time', is_custom_amount: false}],
    entity_id: 4711,
    amount: 50,
    donation_amount: 50,
    additional_gifts: [
      {
        designation_id: 88,
        amount: 10,
        attach_to_other_entity: false,
        other_entity_id: 4711
      }
    ],
    peer_to_peer_allow_multi_designations: true
  })
};

fetch('https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'jane@example.org',
    'paymentMethod' => 'credit_card',
    'payment_method' => 'pm_123',
    'card_number' => '5531886652142950',
    'cvv' => '564',
    'expiry_month' => '09',
    'expiry_year' => '32',
    'card_holder_name' => 'Jane Donor',
    'designations' => [
        [
                'entity_id' => 4711,
                'amount' => 50,
                'frequency' => 'one time',
                'is_custom_amount' => false
        ]
    ],
    'entity_id' => 4711,
    'amount' => 50,
    'donation_amount' => 50,
    'additional_gifts' => [
        [
                'designation_id' => 88,
                'amount' => 10,
                'attach_to_other_entity' => false,
                'other_entity_id' => 4711
        ]
    ],
    'peer_to_peer_allow_multi_designations' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}"

	payload := strings.NewReader("{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "session_id": "<string>",
  "charge_status": "<string>",
  "data": {},
  "next_action": {}
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

{
  "message": "Something went wrong. Please try again.",
  "status": "error",
  "error": "invalid_request",
  "code": "DONOR_NOT_FOUND"
}

{
  "message": "Something went wrong. Please try again.",
  "status": "error",
  "error": "invalid_request",
  "code": "DONOR_NOT_FOUND"
}

Path Parameters

client_id

integer

required

Client id that owns the campaign program, gateway configuration, entities, and checkout session.

program_id

integer

required

Campaign program id. Designation entity ids must belong to this program.

session_id

string

required

Optional Redis frontend session id used to store and later validate the Flutterwave charge state.

Body

application/json

Campaign checkout card details or saved payment method plus designation amount data.

string<email>

required

Donor email. Validator rule: required|email.

Example:

"jane@example.org"

paymentMethod

enum<string>

required

Payment method family. Validator rule: required|string|in:credit_card.

Available options:

credit_card

Example:

"credit_card"

payment_method

string | null

Saved Flutterwave payment method id. When present it replaces card field requirements and must belong to a verified session donor.

Example:

"pm_123"

card_number

string | null

Card number required when payment_method is absent. Alias number is normalized to this field.

Example:

"5531886652142950"

cvv

string | null

Card CVV required when payment_method is absent.

Example:

"564"

expiry_month

string | null

Two-digit card expiry month required when payment_method is absent. Aliases are normalized from expiryMonth or cardExpiry.

Example:

"09"

expiry_year

string | null

Two-digit card expiry year required when payment_method is absent. Aliases are normalized from expiryYear or cardExpiry.

Example:

"32"

card_holder_name

string | null

Optional cardholder name. If absent, first and last name are combined.

Example:

"Jane Donor"

designations

object[] | null

Preferred campaign cart format. Validator rules require at least one item when present.

Show child attributes

entity_id

integer | null

Fallback single-designation entity id required when designations is absent.

Example:

4711

amount

number<float> | null

Fallback amount required without designations unless donation_amount is supplied.

Required range: x >= 0.01

Example:

50

donation_amount

number<float> | null

Legacy fallback amount alias required without designations unless amount is supplied.

Required range: x >= 0.01

Example:

50

additional_gifts

object[] | null

Optional extra designation gifts admitted by the checkout program and donor form.

Show child attributes

peer_to_peer_allow_multi_designations

boolean | null

Peer-to-peer override that can allow multiple designations even when program settings normally disallow them.

Example:

true

Response

Flutterwave charge initialized.

status

string

Example:

"success"

session_id

string

charge_status

string | null

data

object

next_action

object | null

Initialize a Flutterwave v4 campaign charge

curl --request POST \
  --url https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jane@example.org",
  "paymentMethod": "credit_card",
  "payment_method": "pm_123",
  "card_number": "5531886652142950",
  "cvv": "564",
  "expiry_month": "09",
  "expiry_year": "32",
  "card_holder_name": "Jane Donor",
  "designations": [
    {
      "entity_id": 4711,
      "amount": 50,
      "frequency": "one time",
      "is_custom_amount": false
    }
  ],
  "entity_id": 4711,
  "amount": 50,
  "donation_amount": 50,
  "additional_gifts": [
    {
      "designation_id": 88,
      "amount": 10,
      "attach_to_other_entity": false,
      "other_entity_id": 4711
    }
  ],
  "peer_to_peer_allow_multi_designations": true
}
'

import requests

url = "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}"

payload = {
    "email": "jane@example.org",
    "paymentMethod": "credit_card",
    "payment_method": "pm_123",
    "card_number": "5531886652142950",
    "cvv": "564",
    "expiry_month": "09",
    "expiry_year": "32",
    "card_holder_name": "Jane Donor",
    "designations": [
        {
            "entity_id": 4711,
            "amount": 50,
            "frequency": "one time",
            "is_custom_amount": False
        }
    ],
    "entity_id": 4711,
    "amount": 50,
    "donation_amount": 50,
    "additional_gifts": [
        {
            "designation_id": 88,
            "amount": 10,
            "attach_to_other_entity": False,
            "other_entity_id": 4711
        }
    ],
    "peer_to_peer_allow_multi_designations": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'jane@example.org',
    paymentMethod: 'credit_card',
    payment_method: 'pm_123',
    card_number: '5531886652142950',
    cvv: '564',
    expiry_month: '09',
    expiry_year: '32',
    card_holder_name: 'Jane Donor',
    designations: [{entity_id: 4711, amount: 50, frequency: 'one time', is_custom_amount: false}],
    entity_id: 4711,
    amount: 50,
    donation_amount: 50,
    additional_gifts: [
      {
        designation_id: 88,
        amount: 10,
        attach_to_other_entity: false,
        other_entity_id: 4711
      }
    ],
    peer_to_peer_allow_multi_designations: true
  })
};

fetch('https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'jane@example.org',
    'paymentMethod' => 'credit_card',
    'payment_method' => 'pm_123',
    'card_number' => '5531886652142950',
    'cvv' => '564',
    'expiry_month' => '09',
    'expiry_year' => '32',
    'card_holder_name' => 'Jane Donor',
    'designations' => [
        [
                'entity_id' => 4711,
                'amount' => 50,
                'frequency' => 'one time',
                'is_custom_amount' => false
        ]
    ],
    'entity_id' => 4711,
    'amount' => 50,
    'donation_amount' => 50,
    'additional_gifts' => [
        [
                'designation_id' => 88,
                'amount' => 10,
                'attach_to_other_entity' => false,
                'other_entity_id' => 4711
        ]
    ],
    'peer_to_peer_allow_multi_designations' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}"

	payload := strings.NewReader("{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jane@example.org\",\n  \"paymentMethod\": \"credit_card\",\n  \"payment_method\": \"pm_123\",\n  \"card_number\": \"5531886652142950\",\n  \"cvv\": \"564\",\n  \"expiry_month\": \"09\",\n  \"expiry_year\": \"32\",\n  \"card_holder_name\": \"Jane Donor\",\n  \"designations\": [\n    {\n      \"entity_id\": 4711,\n      \"amount\": 50,\n      \"frequency\": \"one time\",\n      \"is_custom_amount\": false\n    }\n  ],\n  \"entity_id\": 4711,\n  \"amount\": 50,\n  \"donation_amount\": 50,\n  \"additional_gifts\": [\n    {\n      \"designation_id\": 88,\n      \"amount\": 10,\n      \"attach_to_other_entity\": false,\n      \"other_entity_id\": 4711\n    }\n  ],\n  \"peer_to_peer_allow_multi_designations\": true\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "session_id": "<string>",
  "charge_status": "<string>",
  "data": {},
  "next_action": {}
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

{
  "message": "Something went wrong. Please try again.",
  "status": "error",
  "error": "invalid_request",
  "code": "DONOR_NOT_FOUND"
}

{
  "message": "Something went wrong. Please try again.",
  "status": "error",
  "error": "invalid_request",
  "code": "DONOR_NOT_FOUND"
}

Overview

Admin

Admin Dashboard

Auth

Client

Communications

Donations

Donor Portal

Donor Signup

Donors

Email Settings

Entities

Files

Forms

Frontend

Historical Archived Updates

Payments

Programs

Public

Recipient Portal

Reports

Sponsorships

Team & Access

Trips

User

Webhooks

Wrapped

Initialize a Flutterwave v4 campaign charge

Path Parameters

Body

Response