Skip to main content
Billing & Finance

Payment Plans

Create and manage polymorphic payment plans with automatic IBAN mandate generation and audit history.

Base URL: /api/v1/fileable-payment-plan

Auth required: Yes (auth:api) for all endpoints.

Payment plans are polymorphic: they are attached to any fileable entity (typically a customer_file). They define how a customer will pay (payment method, IBAN, mandate, etc.).

Model Properties

Payment Plan (fileable_payment_plan)

Property Type Required Description
id integer auto Unique identifier
fileable_type string auto PHP class name of the owning entity (set from query param, not the body)
fileable_id integer auto ID of the owning entity (set from query param, not the body)
payment_method_id integer Required on creation FK to payment_methods. The payment method (e.g. SEPA direct debit, bank transfer, credit card)
deposit_method string No Deposit method enum (e.g. bank_transfer, sepa, card)
end_of_month boolean No Whether to apply end-of-month payment adjustment (default: false)
delay_in_days integer No Payment delay in days
iban string No IBAN for SEPA direct debit. Setting this auto-generates a mandate reference
bic string No BIC/SWIFT code
mandate string No SEPA mandate reference. Auto-generated when IBAN is provided
signature_date date No Date the SEPA mandate was signed (format: Y-m-d)
referenced_email_address_for_payment string No Email address referenced for payment communications
customer_reference_for_payment string No Customer reference used in payment communications
free_information string No Free-form additional information for the payment plan
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Note: This endpoint uses POST for both creation and update (upsert). GET /v1/fileable-payment-plan/history returns an audit log of all changes to the IBAN, BIC, mandate, and signature_date fields.

GET /v1/fileable-payment-plan

Get the payment plan for a fileable entity.

Query parameters:

Parameter Type Required Description
fileable_type string Yes PHP class name of the fileable entity
fileable_id integer Yes ID of the fileable entity

Response 200:

{
  "payment_plan": { ...payment plan object... }
}

Returns null for payment_plan if no plan exists yet.

Examples:

curl -X GET "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan?fileable_type=App%5CModels%5CCustomerFile&fileable_id=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan",
    params={
        "fileable_type": "App\\Models\\CustomerFile",
        "fileable_id": 10
    },
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
payment_plan = response.json()["payment_plan"]

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan', [
        'fileable_type' => 'App\\Models\\CustomerFile',
        'fileable_id' => 10,
    ]);

$paymentPlan = $response->json()['payment_plan'];

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan?fileable_type=App%5CModels%5CCustomerFile&fileable_id=10",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const { payment_plan } = await response.json();

POST /v1/fileable-payment-plan

Create or update the payment plan for a fileable entity.

Note: this endpoint uses POST for both creation and update (not PUT).

Query parameters:

Parameter Type Required Description
fileable_type string Yes PHP class name of the fileable entity
fileable_id integer Yes ID of the fileable entity

Body (JSON): Validated via fileable_payment_plan::attributes('common').

Field Type Required Description
payment_method_id integer Required when creating new Payment method ID
signature_date string No Date format Y-m-d
... ... Other payment plan fields (IBAN, mandate reference, etc.)

If creating a new plan, payment_method_id is required. If an IBAN is provided, a mandate is auto-generated.

Response 200:

{
  "payment_plan": { ...updated payment plan object... }
}

Response 422: Validation error (e.g. missing payment_method_id on creation).

Examples:

curl -X POST "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan?fileable_type=App%5CModels%5CCustomerFile&fileable_id=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": 2,
    "signature_date": "2026-03-24",
    "iban": "FR7630006000011234567890189"
  }'

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan",
    params={
        "fileable_type": "App\\Models\\CustomerFile",
        "fileable_id": 10
    },
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "payment_method_id": 2,
        "signature_date": "2026-03-24",
        "iban": "FR7630006000011234567890189"
    }
)
payment_plan = response.json()["payment_plan"]

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan?fileable_type=App\\Models\\CustomerFile&fileable_id=10', [
        'payment_method_id' => 2,
        'signature_date' => '2026-03-24',
        'iban' => 'FR7630006000011234567890189',
    ]);

$paymentPlan = $response->json()['payment_plan'];

const params = new URLSearchParams({
  fileable_type: "App\\Models\\CustomerFile",
  fileable_id: 10
});

const response = await fetch(
  `https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan?${params}`,
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      payment_method_id: 2,
      signature_date: "2026-03-24",
      iban: "FR7630006000011234567890189"
    })
  }
);
const { payment_plan } = await response.json();

GET /v1/fileable-payment-plan/history

Get the activity audit log (changelog) for a payment plan.

Query parameters:

Parameter Type Required Description
fileable_type string Yes PHP class name of the fileable entity
fileable_id integer Yes ID of the fileable entity

Response 200:

{
  "history": [
    {
      "id": 1,
      "event": "updated",
      "created_at": "2024-01-01T12:00:00Z",
      "causer": { "id": 5, "name": "..." },
      "properties": { ... }
    }
  ]
}

History is ordered by created_at descending and includes causer (user) data.

Examples:

curl -X GET "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan/history?fileable_type=App%5CModels%5CCustomerFile&fileable_id=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan/history",
    params={
        "fileable_type": "App\\Models\\CustomerFile",
        "fileable_id": 10
    },
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
history = response.json()["history"]

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan/history', [
        'fileable_type' => 'App\\Models\\CustomerFile',
        'fileable_id' => 10,
    ]);

$history = $response->json()['history'];

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/fileable-payment-plan/history?fileable_type=App%5CModels%5CCustomerFile&fileable_id=10",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const { history } = await response.json();
Next Bank Details and GoCardless Mandates