Create payment schedule

post

https://secure.mintpayments.com/mpay/v5/payment-schedules

Create a new payment schedule

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

business_unit

string

required

Business unit identifier that owns this scheduled payment.

The business unit determines Merchant account configuration and payment processing rules

amount

string

required

Payment amount in the specified currency.

Must be a positive decimal number with exactly 2 decimal places.
The amount will be charged when the scheduled payment is executed.

Validation:

Must be greater than 0.00
Minimum amount may vary by currency and payment method
Maximum amount may be subject to merchant account limits

currency

string

required

Payment currency (ISO 4217 three-letter code).

Must be a currency supported by the merchant account and payment method.
The currency cannot be changed after the scheduled payment is created.

schedule_type

string

enum

required

Type of scheduled payment.

Currently only supports "single" which represents a one-time scheduled payment
that will be executed once at the specified time.

Allowed:

booking

string

Optional associated booking ID.

Links the scheduled payment to a specific booking, reservation, or order.
Useful for:

Tracking and reconciliation
Customer service inquiries
Reporting and analytics
Automated booking updates upon payment completion

card_token

string

required

Secure token representing the payment card to be used for this scheduled payment.

Requirements:

Must be a valid, non-expired card token
Token must be associated with the same merchant account
Card must be authorized for scheduled/recurring payments
Token must have sufficient authorization for the payment amount

Token Lifecycle:

Tokens are created through the card tokenization process
Tokens may have expiration dates (typically 1-2 years)
Tokens can be revoked or invalidated by the cardholder
Invalid tokens will cause the scheduled payment to fail

execute_after

date-time

required

When to execute the scheduled payment (UTC timestamp).

Scheduling Rules:

Must be a future timestamp (at least 1 minute from now)

requires_customer_approval

boolean

Defaults to false

Whether customer approval is required before executing the scheduled payment.

false (default):

Scheduled payment will be executed automatically at the specified time
Initial status will be PENDING
No customer interaction required
Suitable for pre-authorized recurring payments

true:

Customer approval is required before execution
Initial status will be PENDING_APPROVAL
Customer must approve the payment before it can be processed
Useful for:
- High-value transactions requiring explicit approval
- One-time scheduled payments where customer consent is needed
- Compliance with regulations requiring customer approval
- Subscription renewals with customer confirmation

Approval Flow:

When true, the scheduled payment is created with PENDING_APPROVAL status
Customer receives notification to approve the payment
Upon customer approval, status changes to PENDING
Payment is then executed at the scheduled time
If not approved by execute_after time, payment expires

metadata

object

Additional metadata for the scheduled payment as key-value pairs.

Useful for storing:

Customer context information
Internal reference numbers
Business-specific data
Integration tracking information

Responses

201Payment schedule created successfully

400Bad request - invalid payment schedule data

401Unauthorized