Payment Options Reference

When calling renderButton(), you must provide a payment options object with the following properties:

Required Properties

`payment_type` (string, required)

The type of payment session to create.

"one_time" - Single payment transaction
"subscription" - Recurring payment (requires subscription object)

payment_type: "one_time";

`currency` (string, required)

The three-letter ISO currency code (e.g., 'USD', 'EUR', 'GBP').

currency: "USD";

`line_items` (array, required)

An array of items being purchased. Each item must include:

Property	Type	Description
`name`	`string` (optional)	Name of the item (recommended for clarity)
`quantity`	`number`	Quantity (must be greater than 0)
`amount`	`number`	Price in smallest currency unit, e.g., cents (must be greater than 0)
`country_iso`	`string` (optional)	ISO 3166-1 alpha-2 country code (e.g., "GB")
`intention`	`string` (optional)	The intention or purpose of the payment (e.g., "General Donation")
`project`	`string` (optional)	The specific project the payment is for (e.g., "Winter Appeal 2024")

line_items: [
  {
    name: "Winter Appeal 2024",
    quantity: 1,
    amount: 9900, // $99.00
    country_iso: "GB",
    intention: "General Donation",
    project: "Winter Appeal 2024"
  },
];

`payer` (object, required)

Information about the customer making the payment:

Property	Type	Description
`email`	`string`	Valid email address of the payer
`first_name`	`string` (optional)	First name of the payer
`last_name`	`string` (optional)	Last name of the payer
`phone`	`string` (optional)	Phone number of the payer
`billing_address`	`object` (optional)	Billing address details

billing_address is an object that contains the following properties:

Property	Type	Description
`country`	`string` (required*)	ISO 3166-1 alpha-2 country code (e.g., "GB") - Required when `billing_address` is provided
`city`	`string` (optional)	City name
`line1`	`string` (optional)	Address line 1
`line2`	`string` (optional)	Address line 2
`postcode`	`string` (optional)	Postal code
`state`	`string` (optional)	State or province

payer: {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  phone: "+447700900000",
  billing_address: {
    country: "GB",
    city: "London",
    line1: "123 Main Street",
    line2: "Flat 4",
    postcode: "SW1A 1AA",
    state: "Greater London"
  }
}

`return_url` (string, required)

The URL where the customer will be redirected after completing or canceling the payment.

Requirements:

Must use HTTPS protocol (HTTP not allowed)
Can be overridden in checkout configuration

return_url: "https://yoursite.com/payment/success";

`subscription` (object, conditional)

Required when payment_type is "subscription"

Configuration for recurring payments.

Property	Type	Description
`interval`	`string` (required)	Billing frequency: `"day"`, `"week"`, `"month"`, or `"year"`
`interval_count`	`number` (required)	Number of intervals between billings (e.g., 2 = every 2 months)
`name`	`string` (required)	Product name displayed to customer and payment provider

subscription: {
  interval: "month",
  interval_count: 1,
  name: "Monthly Orphan Sponsorship"
}

`one_time_items` (array, optional)

Only applicable when payment_type is "subscription"

Additional one-time items to charge alongside the first subscription payment. Each item has the same structure as line_items.

Use case: Setup fees, initial deposits, or one-time add-ons with a subscription.

one_time_items: [
  {
    name: "Setup Fee",
    quantity: 1,
    amount: 2500 // £25.00 one-time charge
  }
]

Complete Payment Options Examples

Example 1: One-Time Payment (Simple)

A basic single payment for a donation or purchase.

{
  payment_type: 'one_time',
  currency: 'GBP',
  line_items: [
    {
      name: 'Winter Appeal Donation',
      quantity: 1,
      amount: 5000 // £50.00
    }
  ],
  payer: {
    email: 'donor@example.com'
  },
  return_url: 'https://yoursite.com/checkout/complete'
}

Example 2: Subscription (Monthly Donation)

A recurring monthly payment with full payer details.

{
  payment_type: 'subscription',
  currency: 'USD',
  subscription: {
    interval: 'month',
    interval_count: 1,
    name: 'Monthly Orphan Sponsorship'
  },
  line_items: [
    {
      name: 'Orphan Sponsorship',
      quantity: 1,
      amount: 3000, // $30.00/month
      country_iso: 'US',
      intention: 'Orphan Sponsorship',
      project: 'Global Orphan Program'
    }
  ],
  payer: {
    email: 'supporter@example.com',
    first_name: 'John',
    last_name: 'Smith'
  },
  return_url: 'https://yoursite.com/subscription/success'
}

Example 3: Subscription with One-Time Setup Fee (Mixed)

A recurring subscription with an additional one-time enrollment fee.

{
  payment_type: 'subscription',
  currency: 'GBP',
  subscription: {
    interval: 'month',
    interval_count: 1,
    name: 'Child Education Program'
  },
  line_items: [
    {
      name: 'Monthly Education Support',
      quantity: 1,
      amount: 2500 // £25.00/month recurring
    }
  ],
  one_time_items: [
    {
      name: 'Program Enrollment Fee',
      quantity: 1,
      amount: 1000 // £10.00 one-time charge
    }
  ],
  payer: {
    email: 'parent@example.com',
    first_name: 'Sarah',
    last_name: 'Johnson',
    billing_address: {
      country: 'GB',
      city: 'London',
      line1: '123 Main Street',
      postcode: 'SW1A 1AA'
    }
  },
  return_url: 'https://yoursite.com/enrollment/complete'
}

Currency Format

All amounts in amount should be in the smallest currency unit:

Currency	Unit	Example for $50
USD	Cents	5000
EUR	Cents	5000
GBP	Pence	5000
JPY	Yen	50 (no decimals)

Create Payment Session