POST /payment-session/checkout

Creates a payment session and initiates checkout, returning a URL to redirect the payer.

Request

curl -X POST https://api.givepay.co/api/v1/payment-session/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": "one_time",
    "currency": "GBP",
    "line_items": [
      {
        "quantity": 1,
        "amount": 5000,
        "country_iso": "GB",
        "intention": "General Donation",
        "project": "Winter Appeal 2024"
      }
    ],
    "payer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+447700900000",
      "billing_address": {
        "country": "GB",
        "city": "London",
        "line1": "123 Main Street",
        "postcode": "SW1A 1AA"
      }
    },
    "metadata": { "campaign_id": "winter-2024" },
    "return_url": "https://yoursite.com/payment-complete"
  }'

Authentication. Pass your publishable key (gp_live_pk_... or gp_test_pk_...) in the Authorization header. Both Authorization: Bearer <key> and Authorization: <key> are accepted.

Request Body

Field	Type	Required	Description
`payment_type`	`string`	Yes	`"one_time"` or `"subscription"`
`currency`	`string`	Yes	Three-letter ISO 4217 currency code (e.g. `"GBP"`)
`line_items`	`array`	Yes	Array of line items (minimum 1). For subscriptions, these are the recurring items
`payer`	`object`	Yes	Payer information
`return_url`	`string`	No	HTTPS URL the payer is redirected to after the hosted checkout completes. Falls back to the organisation's default if omitted
`subscription`	`object`	Conditional	Required when `payment_type` is `"subscription"`; must be omitted otherwise
`one_time_items`	`array`	No	Additional one-off items charged on the first invoice (subscription only — e.g. setup or enrollment fees)
`metadata`	`object`	No	Arbitrary JSON key/value pairs stored on the payment session and forwarded to the payment provider

Line Item Object

Field	Type	Required	Description
`quantity`	`integer`	Yes	Quantity (must be > 0)
`amount`	`integer`	Yes	Amount in pence (e.g., 5000 = £50.00)
`country_iso`	`string`	No	ISO 3166-1 alpha-2 country code (e.g., `"GB"`)
`intention`	`string`	No	Purpose of payment (e.g., `"General Donation"`)
`project`	`string`	No	Project name (e.g., `"Winter Appeal 2024"`)

Payer Object

Field	Type	Required	Description
`email`	`string`	Yes	Valid email address
`first_name`	`string`	No	First name
`last_name`	`string`	No	Last name
`phone`	`string`	No	Phone number
`billing_address`	`object`	No	Billing address details

Billing Address Object

Field	Type	Required	Description
`country`	`string`	Yes*	ISO 3166-1 alpha-2 code - *Required when billing_address is provided
`city`	`string`	No	City name
`line1`	`string`	No	Address line 1
`line2`	`string`	No	Address line 2
`postcode`	`string`	No	Postal code
`state`	`string`	No	State or province

Subscription Object (for recurring payments)

Field	Type	Required	Description
`interval`	`string`	Yes	Billing frequency: `"day"`, `"week"`, `"month"`, or `"year"`
`interval_count`	`integer`	Yes	Number of intervals between billings
`name`	`string`	Yes	Product name displayed to customer

Response

One-Time Payment

{
  "checkout_url": "https://checkout.givepay.com/checkout?p=cHNfMDFIR1c1TjhKOUs3...",
  "expires_at": "2026-02-17T10:30:00Z",
  "slug": "ps_01HGW5N8J9K7M2Q4R6S8T1V3W5",
  "type": "one_time"
}

You can retrieve the payment session details using the Get Payment Session endpoint with the returned slug.

Subscription

{
  "checkout_url": "https://checkout.givepay.com/checkout?p=c3ViXzAxSEdXNU44Sjl...",
  "expires_at": null,
  "slug": "sub_01HGW5N8J9K7M2Q4R6S8T1V3W5",
  "type": "subscription"
}

You can retrieve the subscription details using the Get Subscription endpoint with the returned slug.

Response Fields

Field	Type	Description
`checkout_url`	`string`	URL to redirect the payer to complete payment
`expires_at`	`string` or `null`	ISO 8601 expiration timestamp (may be `null` for some providers)
`slug`	`string`	Payment session or subscription slug identifier
`type`	`string`	Payment type: `"one_time"` or `"subscription"`

Error Responses

Status	Description
`400`	Invalid request body or validation error
`401`	Unauthorized - invalid or missing API key
`500`	Internal server error

See Checkout Examples for complete code examples including one-off, daily, monthly, and mixed payments.

Create Checkout