Skip to main content
POST
/
api
/
v1
/
schedules
Create a new direct debit schedule
curl --request POST \
  --url https://api.config.money/api/v1/schedules \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "value": 123,
    "currency": "<string>"
  },
  "frequency": {
    "type": "daily",
    "day": 123,
    "interval": 123
  },
  "customer": {
    "type": "phone",
    "value": "<string>",
    "account_number": "<string>",
    "sort_code": "<string>"
  },
  "description": "<string>",
  "metadata": {},
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "max_retries": 3
}
'
{
  "id": "<string>",
  "status": "active",
  "amount": {
    "value": 123,
    "currency": "<string>"
  },
  "frequency": {
    "type": "daily",
    "day": 123,
    "interval": 123
  },
  "customer": {
    "type": "phone",
    "value": "<string>",
    "account_number": "<string>",
    "sort_code": "<string>"
  },
  "description": "<string>",
  "metadata": {},
  "next_payment_date": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "consent_url": "<string>"
}

​
Create Direct Debit Schedule

Create a new recurring direct debit schedule for a customer. This endpoint allows you to set up automated collections for your customers.
This endpoint requires API key authentication. Include your API key in the Authorization header.

​
Endpoint

POST /api/v1/schedules

​
Headers

NameTypeDescription
AuthorizationstringYour API key in the format Bearer YOUR_API_KEY
Content-TypestringMust be set to application/json

​
Request Body

{
  "amount": {
    "value": 2000,
    "currency": "GBP"
  },
  "frequency": {
    "type": "monthly",
    "day": 1
  },
  "customer": {
    "type": "phone",
    "value": "+447911123456"
  },
  "description": "Phone Plan Monthly Payment",
  "metadata": {
    "plan_id": "premium_monthly",
    "customer_reference": "CUST123"
  }
}

​
Amount Object

FieldTypeDescription
valueintegerAmount in smallest currency unit (e.g., pence for GBP)
currencystringThree-letter ISO currency code (e.g., “GBP”)

​
Frequency Object

FieldTypeDescription
typestringOne of: daily, weekly, monthly, quarterly, yearly
dayintegerDay of month (1-31) for monthly/quarterly/yearly, or day of week (1-7) for weekly
intervalintegerOptional. Number of intervals between payments (e.g., 2 for bi-monthly)

​
Customer Object

The customer object must specify one of the following identification methods:

​
Phone Number

{
  "type": "phone",
  "value": "+447911123456"
}

​
Bank Account

{
  "type": "bank_account",
  "account_number": "12345678",
  "sort_code": "123456"
}

​
Config.money User ID

{
  "type": "user_id",
  "value": "user_123456789"
}

​
Additional Fields

FieldTypeDescription
descriptionstringDescription of the payment for customer reference
metadataobjectOptional. Additional data to store with the schedule
start_datestringOptional. ISO 8601 date when the schedule should start. Defaults to next occurrence
end_datestringOptional. ISO 8601 date when the schedule should end
max_retriesintegerOptional. Maximum number of retry attempts for failed payments. Defaults to 3

​
Response

​
Success Response (200 OK)

{
  "id": "sched_123456789",
  "status": "active",
  "amount": {
    "value": 2000,
    "currency": "GBP"
  },
  "frequency": {
    "type": "monthly",
    "day": 1
  },
  "customer": {
    "type": "phone",
    "value": "+447911123456"
  },
  "description": "Phone Plan Monthly Payment",
  "metadata": {
    "plan_id": "premium_monthly",
    "customer_reference": "CUST123"
  },
  "next_payment_date": "2024-04-01T00:00:00Z",
  "created_at": "2024-03-15T10:30:00Z"
}

​
Error Responses

​
400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": {
      "amount": "Amount must be greater than 0"
    }
  }
}

​
401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

​
404 Not Found

{
  "error": {
    "code": "customer_not_found",
    "message": "Customer not found with the provided details"
  }
}

​
Examples

​
Create Monthly Phone Plan Payment

curl -X POST https://api.config.money/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": 2000,
      "currency": "GBP"
    },
    "frequency": {
      "type": "monthly",
      "day": 1
    },
    "customer": {
      "type": "phone",
      "value": "+447911123456"
    },
    "description": "Phone Plan Monthly Payment",
    "metadata": {
      "plan_id": "premium_monthly"
    }
  }'

​
Create Weekly Subscription with Bank Account

curl -X POST https://api.config.money/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": 500,
      "currency": "GBP"
    },
    "frequency": {
      "type": "weekly",
      "day": 1
    },
    "customer": {
      "type": "bank_account",
      "account_number": "12345678",
      "sort_code": "123456"
    },
    "description": "Weekly Subscription",
    "start_date": "2024-04-01T00:00:00Z"
  }'

​
Notes

  • All amounts are specified in the smallest currency unit (e.g., pence for GBP)
  • The first payment will be scheduled for the next occurrence of the specified frequency
  • Failed payments will be automatically retried according to your retry policy
  • You can update or cancel the schedule using the schedule ID returned in the response

Authorizations

​
Authorization
string
header
required

API key in the format 'Bearer YOUR_API_KEY'

Body

application/json
​
amount
object
required
​
frequency
object
required
​
customer
object
required
​
description
string
required

Description of the payment for customer reference

​
metadata
object

Additional data to store with the schedule

​
start_date
string<date-time>

ISO 8601 date when the schedule should start

​
end_date
string<date-time>

ISO 8601 date when the schedule should end

​
max_retries
integer
default:3

Maximum number of retry attempts for failed payments

Response

Schedule created successfully

​
id
string

Unique schedule identifier

​
status
enum<string>

Schedule status

Available options:
active,
paused,
cancelled
​
amount
object
​
frequency
object
​
customer
object
​
description
string
​
metadata
object
​
next_payment_date
string<date-time>
​
created_at
string<date-time>
​
consent_url
string<uri>

URL to the customer portal where consent for collections can be given