Guides

Getting Started

Create a payment session and collect a payment in under 5 minutes.

Prerequisites

  • A CatalystPay API key (starts with rk_)
  • A campaign ID from your CatalystPay admin panel

If you do not have these yet, contact [email protected] to get set up.

Base URL

All API requests go to:

https://api.catalystpay.com/api/v1

For sandbox/staging testing, use:

https://api.staging.catalystpay.com/api/v1

Authentication

CatalystPay uses Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer rk_your_api_key

API keys use the rk_ prefix. Session tokens (used by the hosted payment page) use the ps_ prefix. Both are passed as Bearer tokens, and CatalystPay routes them to the correct authentication handler automatically.

Step 1: Create a payment session

Create a payment session by sending customer data and a campaign ID. Replace rk_your_api_key with your actual key.

curl -X POST https://api.catalystpay.com/api/v1/payment-sessions/ \
  -H "Authorization: Bearer rk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "lead": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "[email protected]",
      "country": "DE"
    }
  }'

import requests

response = requests.post(
    "https://api.catalystpay.com/api/v1/payment-sessions/",
    headers={
        "Authorization": "Bearer rk_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "campaign_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "lead": {
            "first_name": "Max",
            "last_name": "Mustermann",
            "email": "[email protected]",
            "country": "DE",
        },
    },
)
print(response.json())

const response = await fetch(
  "https://api.catalystpay.com/api/v1/payment-sessions/",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer rk_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      lead: {
        first_name: "Max",
        last_name: "Mustermann",
        email: "[email protected]",
        country: "DE",
      },
    }),
  }
);
const data = await response.json();
console.log(data);

You should see a 201 Created response:

{
  "session_token": "ps_abc123def456ghi789jkl012mno345",
  "status": "PENDING",
  "payment_url": "https://pay.catalystpay.com/s/ps_abc123def456ghi789jkl012mno345"
}

Save the session_token -- you need it for the next steps.

If you get a 401 error, double-check that your API key starts with rk_ and is in the Authorization: Bearer header.

Lead data fields

The lead object requires:

Field Type Required Description
first_name string Yes Customer first name
last_name string Yes Customer last name
email email Yes Customer email
country string Yes ISO 3166-1 alpha-2 code (e.g., DE, AT, NL)
address string No Street address
city string No City
postal_code string No Postal/ZIP code
phone string No Phone number

Step 2: Submit a payment

Use the session token to submit a payment with a test IBAN.

curl -X POST https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/pay/ \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "DE89370400440532013000",
    "iban_holder_name": "Max Mustermann"
  }'

response = requests.post(
    "https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/pay/",
    json={
        "iban": "DE89370400440532013000",
        "iban_holder_name": "Max Mustermann",
    },
)
print(response.json())

const payResponse = await fetch(
  "https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/pay/",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      iban: "DE89370400440532013000",
      iban_holder_name: "Max Mustermann",
    }),
  }
);
const payData = await payResponse.json();
console.log(payData);

The /pay/ endpoint does not require an API key. The session token in the URL serves as authentication.

The response tells you the outcome:

{
  "session_token": "ps_abc123def456ghi789jkl012mno345",
  "status": "completed",
  "verification_url": null,
  "error": null,
  "retry_allowed": false
}

"status": "completed" means the payment was approved.

Step 3: Check the session status

Confirm the session is complete by retrieving it.

curl https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/

response = requests.get(
    "https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/"
)
print(response.json())

const statusResponse = await fetch(
  "https://api.catalystpay.com/api/v1/payment-sessions/ps_abc123def456ghi789jkl012mno345/"
);
const statusData = await statusResponse.json();
console.log(statusData);

The status field reads "COMPLETED", confirming the payment went through.

{
  "session_token": "ps_abc123def456ghi789jkl012mno345",
  "status": "COMPLETED",
  "amount": "29.99",
  "currency": "EUR",
  "attempts_remaining": 2,
  "campaign": {
    "name": "Premium Membership"
  },
  "offer": {
    "name": "Monthly Premium",
    "price": "29.99",
    "currency": "EUR",
    "billing_type": "recurring"
  },
  "lead": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "[email protected]"
  }
}

You just collected your first payment through the CatalystPay API.

API endpoints summary

Method Endpoint Auth Description
POST /api/v1/payment-sessions/ API key Create a payment session
GET /api/v1/payment-sessions/{token}/ None (token = auth) Retrieve session details
POST /api/v1/payment-sessions/{token}/pay/ None (token = auth) Submit payment
POST /api/v1/payment-sessions/{token}/verify/ None (token = auth) Verify mandate
POST /api/v1/payment-sessions/{token}/cancel/ API key Cancel a session
POST /api/v1/iban-validate/ API key or session token Validate IBAN
GET /api/v1/reconciliation/transactions/ API key List transactions
GET /api/v1/reconciliation/chargebacks/ API key List chargebacks
GET /api/v1/reconciliation/subscriptions/ API key List subscriptions

Rate limits

Scope Limit
Session creation 50 requests/second per API key
Session cancellation 50 requests/second per API key
Payment submission 1 request/second per IP
Mandate verification 1 request/second per IP
Session retrieval 1 request/second per IP
IBAN validation 50 requests/second per API key
Reconciliation 50 requests/second per API key

What you learned

  • Payment sessions are created with POST /api/v1/payment-sessions/ using your API key
  • Payments are submitted with POST /api/v1/payment-sessions/{token}/pay/ (no API key needed)
  • Session status is checked with GET /api/v1/payment-sessions/{token}/
  • A COMPLETED status means the payment was approved

Next steps

Previous
Architecture
Next
Hosted Payment Page Integration