Session Fields

Complete field reference for the Payment Session API endpoints.

Create Session Request

POST /api/v1/payment-sessions/

Authentication: Bearer rk_xxx (API key required)

Campaign Mode vs Direct Mode

The create endpoint operates in two modes depending on whether campaign_id is provided:

• Campaign mode (campaign_id present): Pricing, gateway, and branding resolve from the campaign and its linked offer. All pricing and gateway fields are optional overrides.
• Direct mode (campaign_id absent): gateway_id, amount, currency, and billing_type become required.

Top-Level Fields

Field	Type	Required	Description
campaign_id	uuid	Conditional	Campaign UUID. When absent, activates direct mode.
lead	object	Yes	Lead data object. See Lead Fields.
amount	decimal(10,2)	Direct mode	Payment amount. Overrides offer price in campaign mode.
currency	string(3)	Direct mode	ISO 4217 currency code. Overrides offer currency in campaign mode.
billing_type	string	Direct mode	One of: ONE_OFF, RECURRING, TRIAL_RECURRING.
billing_frequency	string	No	One of: WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY, YEARLY.
trial_interval_unit	string	No	One of: day, week, month.
trial_period	integer	No	Trial period duration. Min: 1.
trial_price	decimal(10,2)	No	Trial price.
gateway_id	uuid	Direct mode	PaymentGateway UUID. Optional override in campaign mode.
max_payment_attempts	integer	No	Max retry attempts (1-10). Campaign mode defaults to campaign value; direct mode defaults to 3.
webhook_profile_id	uuid	No	WebhookProfile UUID for direct-mode webhook routing.
hosted_page_id	uuid	No	HostedPage UUID for explicit HPP branding. Overrides campaign page_config.
customer_ip	string (IPv4/IPv6)	No	Customer's real IP address. When provided, this IP is forwarded to the payment gateway instead of the auto-detected server IP. Recommended for server-side integrations.

Lead Fields

Nested under the lead key in the request body.

Field	Type	Required	Description
first_name	string(255)	Yes	Customer first name.
last_name	string(255)	Yes	Customer last name.
email	email	Yes	Customer email address.
country	string(2)	Yes	ISO 3166-1 alpha-2 country code.
address	string(500)	No	Street address.
city	string(255)	No	City.
postal_code	string(20)	No	Postal/ZIP code.
phone	string(50)	No	Phone number.

Validation Rules

When campaign_id is absent (direct mode), the following fields are all required:

• gateway_id
• amount
• currency
• billing_type

Missing any of these in direct mode returns a 400 with per-field error messages.

Create Session Response

201 Created

Field	Type	Description
session_token	string	Opaque session token (ps_ prefix, 47 characters).
status	string	Always PENDING on creation.
payment_url	string	Full URL to the hosted payment page.

Retrieve Session Response

GET /api/v1/payment-sessions/{token}/

Authentication: None (the token serves as implicit authentication).

Field	Type	Description
session_token	string	Opaque session token.
status	string	Current session status. See Status Lifecycles.
amount	string	Payment amount.
currency	string	Currency code.
attempts_remaining	integer	Number of payment retry attempts remaining.
campaign	object	Campaign display data. See Campaign Display.
offer	object	Offer display data. See Offer Display.
mandate	object	Mandate configuration (optional).
lead	object	Lead display data (optional).

Campaign Display

Field	Type	Presence	Description
name	string	Always	Campaign name.
branding	object	HPP mode only	Contains logo_url (nullable string), primary_color (string), accent_color (string).
content	object	HPP mode only	Free-form content dictionary (e.g., headline text).
show_product_name	boolean	HPP mode only	Whether to display the product name.
show_product_price	boolean	HPP mode only	Whether to display the price.
show_product_description	boolean	HPP mode only	Whether to display the product description.
offer_overrides	object	HPP mode only	Offer display overrides.
success_redirect_url	string	HPP mode only	Redirect URL after successful payment.
failure_redirect_url	string	HPP mode only	Redirect URL after failed payment.

In S2S mode (no CampaignPageConfig), only name is returned.

Offer Display

Field	Type	Presence	Description
name	string	Always	Offer name.
price	string	Always	Offer price.
currency	string	Always	Currency code.
billing_type	string	Always	Billing type.
product_name	string	Optional	Product name.
product_description	string	Optional	Product description.

Mandate Display

Field	Type	Description
acceptance_mode	string	Mandate acceptance mode (e.g., checkbox, IMPLICIT).

Lead Display

Field	Type	Description
first_name	string	Customer first name.
last_name	string	Customer last name.
email	email	Customer email address.

Submit Payment Request

POST /api/v1/payment-sessions/{token}/pay/

Authentication: None (public endpoint).

Field	Type	Required	Description
iban	string	Yes	SEPA IBAN.
iban_holder_name	string	Yes	Account holder name.
tenant_reference_id	string(255)	No	Optional merchant-owned reconciliation reference. Must be unique per tenant when provided. Echoed back in the Reconciliation API and outbound webhooks. Not forwarded to the payment gateway. Returns 409 if the value is already in use.

Submit Payment Response

200 OK

Every response shares the same envelope. All documented keys are present on every response — absent sources are emitted as null, not omitted.

Top-level fields

Field	Type	Description
object	string	Always "payment_session.result". Discriminator for future response types.
session_token	string	Session token.
status	string	One of: completed, awaiting_verification, declined, failed. Branch on this.
livemode	boolean	true in production, false in staging/test. Independent of payment_gateway.test_mode.
created_at	string (ISO-8601, nullable)	Transaction creation timestamp (UTC, Z suffix).
processed_at	string (ISO-8601, nullable)	When the gateway processed the transaction.
order_number	string (nullable)	Legacy — prefer order.order_number.
verification_url	string (nullable)	Mandate verification URL. Populated only when status is awaiting_verification.
error	string (nullable)	Legacy human-readable decline message. Prefer error_details.
retry_allowed	boolean (nullable)	Whether the customer can submit another payment attempt. Only meaningful for declined/failed.
amount	string (nullable)	Fixed 2-decimal string (e.g. "79.00").
currency	string (nullable)	ISO 4217 currency code.
transaction	object (nullable)	See transaction block.
order	object (nullable)	See order block.
subscription	object (nullable)	See subscription block. null for one-off purchases.
lead	object (nullable)	{ "id": "<uuid>" }.
payment_method	object	See payment_method block.
sepa	object	See sepa block.
adapter	object	{ "name": "<adapter display name>" }.
payment_gateway	object (nullable)	See payment_gateway block.
error_details	object (nullable)	See error_details block. null on non-error outcomes.

transaction block

Field	Type	Description
id	uuid	CatalystPay's internal transaction UUID.
merchant_transaction_id	string	CatalystPay-generated TXN-YYYYMMDD-XXXXXXXX reference.
gateway_reference	string (nullable)	Gateway-assigned tracking ID. null until the gateway returns it (batch adapters populate at settlement).
tenant_reference_id	string (nullable)	Echo of the merchant-owned reference supplied on submission. null when not provided.
status	string	Adapter-mapped status (e.g. approved, pending, declined).
type	string	Transaction type (e.g. sdd_sale, sdd_rebill).

order block

Field	Type	Description
id	uuid	Order UUID.
order_number	string	Human-readable order reference (ORD-XXXXXXXX).
status	string	One of: PENDING_PAYMENT_SUBMISSION, PENDING, COMPLETED, FAILED, REFUNDED, CHARGEDBACK.

subscription block

Populated only for recurring/trial_recurring purchases. null for one-off.

Field	Type	Description
id	uuid	Subscription UUID.
status	string	See Status Lifecycles.
billing_frequency	string (nullable)	WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY, or YEARLY.
next_billing_date	string (ISO date, nullable)	Next rebill date.

payment_method block

Field	Type	Description
type	string	Always "sepa_debit".
iban_last4	string (nullable)	Last 4 characters of the IBAN.
iban_country	string (nullable)	First 2 characters of the IBAN (ISO 3166-1 alpha-2).
bic	string (nullable)	BIC/SWIFT code resolved from the IBAN.
bank_name	string (nullable)	Bank name from the SEPA registry. null for smaller banks not in the registry.
holder_name	string (nullable)	Account holder name as submitted.

sepa block

Field	Type	Description
mandate_reference	string (nullable)	SEPA mandate reference ID.
sequence_type	string (nullable)	FRST for first/one-off collections, RCUR for recurring rebills.
creditor_identifier	string (nullable)	SEPA Creditor Identifier. Currently always null (reserved for future use).

payment_gateway block

Field	Type	Description
id	uuid	PaymentGateway UUID.
name	string	Display name.
descriptor	string (nullable)	Bank statement descriptor.
test_mode	boolean	true when the MID is configured against the gateway's sandbox endpoint. Independent of livemode.

error_details block

null for completed and awaiting_verification outcomes. Populated for declined and failed.

Field	Type	Description
code	string	Normalized decline code. One of: insufficient_funds, invalid_iban, mandate_rejected, account_closed, do_not_honor, gateway_unavailable, unknown. Prefer this over string-matching error.
message	string	Human-readable message (falls back to a normalized default when the gateway provides none).
gateway_code	string (nullable)	Raw adapter error code preserved for debugging (e.g. AM04).
gateway_message	string (nullable)	Raw adapter error message.

Verify Mandate Request

POST /api/v1/payment-sessions/{token}/verify/

Authentication: None (public endpoint).

Field	Type	Required	Description
verification_id	string	No	Verification ID from Vendo return URL parameters.

Response format is identical to Submit Payment Response.

Cancel Session

POST /api/v1/payment-sessions/{token}/cancel/

Authentication: Bearer rk_xxx (API key required).

Request body: None.

Cancel Session Response

200 OK

Field	Type	Description
session_token	string	Session token.
status	string	Always EXPIRED after successful cancellation.

Validate IBAN Request

POST /api/v1/iban-validate/

Authentication: Bearer rk_xxx (API key) or Bearer ps_xxx (session token).

Field	Type	Required	Description
iban	string	Yes	IBAN to validate.

Validate IBAN Response (Valid)

200 OK

Field	Type	Description
valid	boolean	true
bank_name	string	Bank name resolved from IBAN.
bic	string	BIC/SWIFT code.

Validate IBAN Response (Invalid IBAN)

200 OK

Field	Type	Description
valid	boolean	false
error	string	Validation error message (e.g., invalid checksum, unknown country code).

Validate IBAN Response (Missing IBAN)

400 Bad Request

Field	Type	Description
valid	boolean	false
error	string	"IBAN is required"