Verified against: Public OpenAPI 2.0.0 · digest cd0bbb453245

Recurring payments · API reference

Manage subscription plans

Subscription plans hold reusable amount, interval, billing, trial, invoice, past-due, and metadata settings. The reviewed contract exposes six plan operations and uses the numeric id field as plan_id in item paths.

Create and list plans

POST/api/v2/payments/subscription-plans

Create Subscription Plan

Create a new subscription plan. This endpoint allows merchants to create recurring payment plans that customers can subscribe to. Args: payload: Subscription plan data merchant_key: Merchant API key info Returns: SubscriptionPlanResponse: Created subscription plan

Operation ID: create_subscription_plan_api_v2_payments_subscription_plans_post
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

No path or query parameters.

Request body

Required application/json body using SubscriptionPlanCreate.

Field	Type	Required	Constraints and meaning
`amount`	`number \| string`	Yes	greater than 0; maximum 999999.9999; pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Subscription amount (max 999,999)
`billing_type`	`SubscriptionBillingType`	No	one of PREPAID, POSTPAID PREPAID = pay upfront for the upcoming period; POSTPAID = bill in arrears at period end
`cancel_immediately_on_failure`	`boolean`	No	default false
`currency`	`string`	No	default "BDT"; maximum length 3 Currency code
`interval_count`	`integer`	Yes	minimum 1; maximum 365 Number of interval units
`interval_unit`	`SubscriptionIntervalUnit`	Yes	one of DAY, WEEK, MONTH, YEAR Interval unit
`invoice_lead_days`	`integer`	No	default 0; minimum 0; maximum 364 Days before the billing date to generate/send the invoice (must be shorter than the billing interval); 0 = on the billing date
`meta_data`	`object \| null`	No	— Additional metadata
`past_due_grace_days`	`integer`	No	default 7; minimum 0; maximum 365
`past_due_warnings_enabled`	`boolean`	No	default true
`plan_description`	`string \| null`	No	— Plan description
`plan_name`	`string`	Yes	minimum length 1; maximum length 200 Plan name
`trial_amount`	`number \| string \| null`	No	minimum 0; maximum 999999.9999; pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Trial amount (null for free trial, max 999,999)
`trial_notifications_enabled`	`boolean`	No	default true
`trial_period_days`	`integer \| null`	No	minimum 0 Trial period in days

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request POST "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 100,
    "billing_type": "PREPAID",
    "cancel_immediately_on_failure": false,
    "currency": "BDT",
    "interval_count": 1,
    "interval_unit": "DAY",
    "invoice_lead_days": 0,
    "past_due_grace_days": 7,
    "past_due_warnings_enabled": true,
    "plan_name": "Sandbox example",
    "trial_notifications_enabled": true
  }'

Run this reviewed operation in the API Lab →

Responses

`201` Successful Response

Content type: application/json. Schema: SubscriptionPlanResponse.

Field	Type	Required	Constraints and meaning
`amount`	`number`	Yes	—
`billing_type`	`string`	Yes	—
`cancel_immediately_on_failure`	`boolean`	Yes	—
`created_at`	`string`	Yes	—
`currency`	`string`	Yes	—
`id`	`integer`	Yes	—
`interval_count`	`integer`	Yes	—
`interval_unit`	`string`	Yes	—
`invoice_lead_days`	`integer`	Yes	—
`is_active`	`boolean`	Yes	—
`merchant_id`	`integer`	Yes	—
`merchant_name`	`string \| null`	No	—
`meta_data`	`object \| null`	Yes	—
`past_due_grace_days`	`integer`	Yes	—
`past_due_warnings_enabled`	`boolean`	Yes	—
`plan_description`	`string \| null`	Yes	—
`plan_name`	`string`	Yes	—
`trial_amount`	`number \| null`	Yes	—
`trial_notifications_enabled`	`boolean`	Yes	—
`trial_period_days`	`integer \| null`	Yes	—
`uuid`	`string`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation create_subscription_plan_api_v2_payments_subscription_plans_post · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

GET/api/v2/payments/subscription-plans

List Subscription Plans

List subscription plans for the authenticated merchant. Args: merchant_key: Merchant API key info include_inactive: Include archived plans page: Page number per_page: Results per page Returns: dict: Paginated list of subscription plans

Operation ID: list_subscription_plans_api_v2_payments_subscription_plans_get
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

Field	Type	Required	Constraints and meaning
`query.include_inactive`	`boolean`	No	default false
`query.page`	`integer`	No	default 1
`query.per_page`	`integer`	No	default 20

Request body

No request body.

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request GET "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans?include_inactive=false&page=1&per_page=20" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY"

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: PublicSubscriptionPlanListResponse.

Field	Type	Required	Constraints and meaning
`data`	`SubscriptionPlanResponse[]`	Yes	—
`data[].amount`	`number`	Yes	—
`data[].billing_type`	`string`	Yes	—
`data[].cancel_immediately_on_failure`	`boolean`	Yes	—
`data[].created_at`	`string`	Yes	—
`data[].currency`	`string`	Yes	—
`data[].id`	`integer`	Yes	—
`data[].interval_count`	`integer`	Yes	—
`data[].interval_unit`	`string`	Yes	—
`data[].invoice_lead_days`	`integer`	Yes	—
`data[].is_active`	`boolean`	Yes	—
`data[].merchant_id`	`integer`	Yes	—
`data[].merchant_name`	`string \| null`	No	—
`data[].meta_data`	`object \| null`	Yes	—
`data[].past_due_grace_days`	`integer`	Yes	—
`data[].past_due_warnings_enabled`	`boolean`	Yes	—
`data[].plan_description`	`string \| null`	Yes	—
`data[].plan_name`	`string`	Yes	—
`data[].trial_amount`	`number \| null`	Yes	—
`data[].trial_notifications_enabled`	`boolean`	Yes	—
`data[].trial_period_days`	`integer \| null`	Yes	—
`data[].uuid`	`string`	Yes	—
`pagination`	`PublicSubscriptionPagination`	Yes	— Pagination shape used by merchant-key subscription APIs.
`pagination.page`	`integer`	Yes	—
`pagination.pages`	`integer`	Yes	—
`pagination.per_page`	`integer`	Yes	—
`pagination.total`	`integer`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation list_subscription_plans_api_v2_payments_subscription_plans_get · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

Read and update a plan

GET/api/v2/payments/subscription-plans/{plan_id}

Get Subscription Plan

Get subscription plan details. Args: plan_id: ID of the subscription plan merchant_key: Merchant API key info Returns: SubscriptionPlanResponse: Subscription plan details

Operation ID: get_subscription_plan_api_v2_payments_subscription_plans__plan_id__get
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

Field	Type	Required	Constraints and meaning
`path.plan_id`	`integer`	Yes	—

Request body

No request body.

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request GET "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans/${PLAN_ID}" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY"

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: SubscriptionPlanResponse.

Field	Type	Required	Constraints and meaning
`amount`	`number`	Yes	—
`billing_type`	`string`	Yes	—
`cancel_immediately_on_failure`	`boolean`	Yes	—
`created_at`	`string`	Yes	—
`currency`	`string`	Yes	—
`id`	`integer`	Yes	—
`interval_count`	`integer`	Yes	—
`interval_unit`	`string`	Yes	—
`invoice_lead_days`	`integer`	Yes	—
`is_active`	`boolean`	Yes	—
`merchant_id`	`integer`	Yes	—
`merchant_name`	`string \| null`	No	—
`meta_data`	`object \| null`	Yes	—
`past_due_grace_days`	`integer`	Yes	—
`past_due_warnings_enabled`	`boolean`	Yes	—
`plan_description`	`string \| null`	Yes	—
`plan_name`	`string`	Yes	—
`trial_amount`	`number \| null`	Yes	—
`trial_notifications_enabled`	`boolean`	Yes	—
`trial_period_days`	`integer \| null`	Yes	—
`uuid`	`string`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation get_subscription_plan_api_v2_payments_subscription_plans__plan_id__get · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

PATCH/api/v2/payments/subscription-plans/{plan_id}

Update Subscription Plan

Update subscription plan. Args: plan_id: ID of the subscription plan payload: Update data merchant_key: Merchant API key info Returns: SubscriptionPlanResponse: Updated subscription plan

Operation ID: update_subscription_plan_api_v2_payments_subscription_plans__plan_id__patch
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

Field	Type	Required	Constraints and meaning
`path.plan_id`	`integer`	Yes	—

Request body

Required application/json body using SubscriptionPlanUpdate.

Field	Type	Required	Constraints and meaning
`amount`	`number \| string \| null`	No	greater than 0; maximum 999999.9999; pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$
`billing_type`	`SubscriptionBillingType \| null`	No	one of PREPAID, POSTPAID
`cancel_immediately_on_failure`	`boolean \| null`	No	—
`currency`	`string \| null`	No	maximum length 3
`interval_count`	`integer \| null`	No	minimum 1; maximum 365
`interval_unit`	`SubscriptionIntervalUnit \| null`	No	one of DAY, WEEK, MONTH, YEAR
`invoice_lead_days`	`integer \| null`	No	minimum 0; maximum 364
`meta_data`	`object \| null`	No	—
`past_due_grace_days`	`integer \| null`	No	minimum 0; maximum 365
`past_due_warnings_enabled`	`boolean \| null`	No	—
`plan_description`	`string \| null`	No	—
`plan_name`	`string \| null`	No	minimum length 1; maximum length 200
`trial_amount`	`number \| string \| null`	No	minimum 0; maximum 999999.9999; pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$
`trial_notifications_enabled`	`boolean \| null`	No	—
`trial_period_days`	`integer \| null`	No	minimum 0

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request PATCH "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans/${PLAN_ID}" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 100
  }'

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: SubscriptionPlanResponse.

Field	Type	Required	Constraints and meaning
`amount`	`number`	Yes	—
`billing_type`	`string`	Yes	—
`cancel_immediately_on_failure`	`boolean`	Yes	—
`created_at`	`string`	Yes	—
`currency`	`string`	Yes	—
`id`	`integer`	Yes	—
`interval_count`	`integer`	Yes	—
`interval_unit`	`string`	Yes	—
`invoice_lead_days`	`integer`	Yes	—
`is_active`	`boolean`	Yes	—
`merchant_id`	`integer`	Yes	—
`merchant_name`	`string \| null`	No	—
`meta_data`	`object \| null`	Yes	—
`past_due_grace_days`	`integer`	Yes	—
`past_due_warnings_enabled`	`boolean`	Yes	—
`plan_description`	`string \| null`	Yes	—
`plan_name`	`string`	Yes	—
`trial_amount`	`number \| null`	Yes	—
`trial_notifications_enabled`	`boolean`	Yes	—
`trial_period_days`	`integer \| null`	Yes	—
`uuid`	`string`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation update_subscription_plan_api_v2_payments_subscription_plans__plan_id__patch · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

Archive and restore a plan

Archive and restore return the complete reviewed plan response. The artifact does not state how existing subscriptions behave when a plan is archived.

DELETE/api/v2/payments/subscription-plans/{plan_id}

Archive Subscription Plan

Archive a subscription plan. Args: plan_id: ID of the subscription plan merchant_key: Merchant API key info Returns: SubscriptionPlanResponse: Archived subscription plan

Operation ID: archive_subscription_plan_api_v2_payments_subscription_plans__plan_id__delete
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

Field	Type	Required	Constraints and meaning
`path.plan_id`	`integer`	Yes	—

Request body

No request body.

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request DELETE "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans/${PLAN_ID}" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY"

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: SubscriptionPlanResponse.

Field	Type	Required	Constraints and meaning
`amount`	`number`	Yes	—
`billing_type`	`string`	Yes	—
`cancel_immediately_on_failure`	`boolean`	Yes	—
`created_at`	`string`	Yes	—
`currency`	`string`	Yes	—
`id`	`integer`	Yes	—
`interval_count`	`integer`	Yes	—
`interval_unit`	`string`	Yes	—
`invoice_lead_days`	`integer`	Yes	—
`is_active`	`boolean`	Yes	—
`merchant_id`	`integer`	Yes	—
`merchant_name`	`string \| null`	No	—
`meta_data`	`object \| null`	Yes	—
`past_due_grace_days`	`integer`	Yes	—
`past_due_warnings_enabled`	`boolean`	Yes	—
`plan_description`	`string \| null`	Yes	—
`plan_name`	`string`	Yes	—
`trial_amount`	`number \| null`	Yes	—
`trial_notifications_enabled`	`boolean`	Yes	—
`trial_period_days`	`integer \| null`	Yes	—
`uuid`	`string`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation archive_subscription_plan_api_v2_payments_subscription_plans__plan_id__delete · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

POST/api/v2/payments/subscription-plans/{plan_id}/restore

Restore Subscription Plan

Restore an archived subscription plan. Args: plan_id: ID of the subscription plan merchant_key: Merchant API key info Returns: SubscriptionPlanResponse: Restored subscription plan

Operation ID: restore_subscription_plan_api_v2_payments_subscription_plans__plan_id__restore_post
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

Field	Type	Required	Constraints and meaning
`path.plan_id`	`integer`	Yes	—

Request body

No request body.

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

curl --request POST "https://sandbox.api.moneybag.com.bd/api/v2/payments/subscription-plans/${PLAN_ID}/restore" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY"

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: SubscriptionPlanResponse.

Field	Type	Required	Constraints and meaning
`amount`	`number`	Yes	—
`billing_type`	`string`	Yes	—
`cancel_immediately_on_failure`	`boolean`	Yes	—
`created_at`	`string`	Yes	—
`currency`	`string`	Yes	—
`id`	`integer`	Yes	—
`interval_count`	`integer`	Yes	—
`interval_unit`	`string`	Yes	—
`invoice_lead_days`	`integer`	Yes	—
`is_active`	`boolean`	Yes	—
`merchant_id`	`integer`	Yes	—
`merchant_name`	`string \| null`	No	—
`meta_data`	`object \| null`	Yes	—
`past_due_grace_days`	`integer`	Yes	—
`past_due_warnings_enabled`	`boolean`	Yes	—
`plan_description`	`string \| null`	Yes	—
`plan_name`	`string`	Yes	—
`trial_amount`	`number \| null`	Yes	—
`trial_notifications_enabled`	`boolean`	Yes	—
`trial_period_days`	`integer \| null`	Yes	—
`uuid`	`string`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation restore_subscription_plan_api_v2_payments_subscription_plans__plan_id__restore_post · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe

Manage subscription plans

Create and list plans

Parameters

Request body

Sandbox example

Responses

201 Successful Response

422 Validation Error

Parameters

Request body

Sandbox example

Responses

200 Successful Response

422 Validation Error

Read and update a plan

Parameters

Request body

Sandbox example

Responses

200 Successful Response

422 Validation Error

Parameters

Request body

Sandbox example

Responses

200 Successful Response

422 Validation Error

Archive and restore a plan

Parameters

Request body

Sandbox example

Responses

200 Successful Response

422 Validation Error

Parameters

Request body

Sandbox example

Responses

200 Successful Response

422 Validation Error

`201` Successful Response

`422` Validation Error

`200` Successful Response

`422` Validation Error

`200` Successful Response

`422` Validation Error

`200` Successful Response

`422` Validation Error

`200` Successful Response

`422` Validation Error

`200` Successful Response

`422` Validation Error