API Reference

REST API · Base URL: https://api.clearpay.io/v2 · All amounts in minor currency units (pence/cents)

POST /v2/payment_intents Create payment intent

Creates a PaymentIntent object. Use the returned client_secret to complete payment on the client side. Supports cards, SEPA, BACS, and 40+ local methods.

Request body

Parameter	Type	Required	Description
amount	integer	required	Amount in minor units (e.g. 1000 = £10.00)
currency	string	required	ISO 4217 currency code, lowercase
capture_method	string	optional	`automatic` or `manual`. Default: automatic
customer	string	optional	Customer ID to attach saved payment methods
description	string	optional	Internal description, max 500 chars
metadata	object	optional	Key-value pairs, max 50 keys

201 Created 400 Bad Request 402 Payment Required

application/json201 Created

{
  "id": "pi_3Pf8kL2eZvKYlo2C",
  "object": "payment_intent",
  "amount": 4800,
  "currency": "eur",
  "status": "requires_payment_method",
  "client_secret": "pi_3Pf8kL2eZvKYlo2C_secret_xK9fZj1mQ",
  "capture_method": "automatic",
  "created": 1745147600,
  "livemode": true
}

GET /v2/payment_intents/{id} Retrieve intent

Retrieves a PaymentIntent by ID. Use to poll status after client-side confirmation.

application/json200 OK

{
  "id": "pi_3Pf8kL2eZvKYlo2C",
  "status": "succeeded",
  "amount_received": 4800,
  "charges": {
    "data": [{
      "id": "ch_3Pf8kL2eZvKYlo2C",
      "paid": true,
      "outcome": { "network_status": "approved_by_network" }
    }]
  }
}

Error codes

HTTPCodeDescription

400invalid_requestMissing or malformed parameters

401authentication_errorInvalid or expired API key

402card_errorCard declined, insufficient funds, or fraud detected

403permission_errorAPI key lacks required permission scope

429rate_limit_errorToo many requests, see rate limit headers

500api_errorInternal server error, retry with backoff