Verified against: Public OpenAPI 2.0.0 · subscription review 2026-07-30
Recurring payments · API reference
Operate subscriptions
Create a subscription from a reusable plan or inline billing fields, then read and update it through its public UUID. The reviewed contract exposes ten merchant-key subscription operations.
Use subscription plans to create and manage reusable
billing definitions. The request contract accepts either customer_uuid for an
existing merchant customer or a customer object that identifies one by phone
and email.
Create and list
/api/v2/payments/subscriptionsCreate Subscription
Create a new subscription for a customer. This endpoint creates a recurring payment subscription. You can provide either: - customer object: Customer will be get-or-created using phone/email (same as checkout API) - customer_uuid: Use an existing customer of yours, by public uuid If a trial period is configured, the subscription will start in TRIALING status. Otherwise, it will start as PENDING and require immediate payment. Args: payload: Subscription data with customer information merchant_key: Merchant API key info Returns: SubscriptionResponse: Created subscription
- Operation ID
create_subscription_api_v2_payments_subscriptions_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 SubscriptionCreate.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | string | null | No | greater than 0; maximum 999999.9999; pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ Override plan amount (max 999,999) |
billing_type | SubscriptionBillingType | null | No | one of PREPAID, POSTPAID Billing mode; inherited from the plan when omitted (defaults to PREPAID for ad-hoc subscriptions) |
currency | string | No | default "BDT"; maximum length 3 Currency code |
customer | Customer | null | No | — Customer information (will be created or fetched) |
customer.address | string | null | No | maximum length 200 Customer's address |
customer.city | string | null | No | maximum length 50 Customer's city |
customer.country | string | null | No | maximum length 50 Customer's country |
customer.email | string | When parent is present | format email; maximum length 100 Customer's email address |
customer.metadata | object | null | No | — Additional customer-specific data |
customer.name | string | When parent is present | maximum length 255 Customer's full name |
customer.phone | string | When parent is present | — Customer's phone number |
customer.postcode | string | null | No | maximum length 20 Customer's postal code |
customer.state | string | null | No | — Customer's state/division/province (e.g. 'Dhaka', 'Chattogram'). Optional. Forwarded to processors that require a billing division; supplying a real value improves AVS accuracy and therefore risk and chargeback outcomes. |
customer_uuid | string | null | No | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ Public uuid of an existing customer of this merchant |
interval_count | integer | null | No | minimum 1; maximum 365 Override plan interval count |
interval_unit | SubscriptionIntervalUnit | null | No | one of DAY, WEEK, MONTH, YEAR Override plan interval unit |
invoice_lead_days | integer | null | No | minimum 0; maximum 364 Invoice lead time in days; inherited from the plan when omitted (defaults to 0) |
meta_data | object | null | No | — Additional metadata |
subscription_plan_id | integer | null | No | — Plan ID (optional, can specify inline) |
trial_period_days | integer | null | No | minimum 0 Override plan trial period |
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/subscriptions" \
--header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
--header "Content-Type: application/json" \
--data '{
"subscription_plan_id": 1,
"customer": {
"name": "Sandbox Customer",
"email": "sandbox.customer@example.com",
"phone": "+8801700000000"
}
}'Run this reviewed operation in the API Lab →
Responses
201 Successful Response
Content type: application/json. Schema: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
/api/v2/payments/subscriptionsList Subscriptions
List subscriptions for the authenticated merchant. Args: merchant_key: Merchant API key info customer_uuid: Filter by customer uuid (must be a customer of this merchant) subscription_status: Filter by status (TRIALING, ACTIVE, PAST_DUE, PAUSED, CANCELLED, EXPIRED) page: Page number per_page: Results per page Returns: dict: Paginated list of subscriptions
- Operation ID
list_subscriptions_api_v2_payments_subscriptions_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.customer_uuid | string | null | No | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
query.subscription_status | string | null | No | — |
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/subscriptions?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: PublicSubscriptionListResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
data | SubscriptionResponse[] | Yes | — |
data[].amount | number | Yes | — |
data[].billing_cycle_count | integer | Yes | — |
data[].billing_type | string | Yes | — |
data[].cancellation_reason | string | null | Yes | — |
data[].cancelled_at | string | null | Yes | — |
data[].created_at | string | Yes | — |
data[].currency | string | Yes | — |
data[].current_period_end | string | Yes | — |
data[].current_period_start | string | Yes | — |
data[].customer | CustomerBasicInfo | null | No | — |
data[].customer.email | string | null | When parent is present | — |
data[].customer.id | integer | When parent is present | — |
data[].customer.name | string | When parent is present | — |
data[].customer.phone | string | When parent is present | — |
data[].customer.uuid | string | null | No | — |
data[].customer_id | integer | Yes | — |
data[].days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
data[].failed_payment_count | integer | Yes | — |
data[].id | integer | Yes | — |
data[].interval_count | integer | Yes | — |
data[].interval_unit | string | Yes | — |
data[].invoice_lead_days | integer | Yes | — |
data[].is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
data[].is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
data[].merchant_id | integer | Yes | — |
data[].merchant_name | string | null | No | — |
data[].meta_data | object | null | Yes | — |
data[].next_billing_date | string | Yes | — |
data[].plan | SubscriptionPlanResponse | null | No | — |
data[].plan.amount | number | When parent is present | — |
data[].plan.billing_type | string | When parent is present | — |
data[].plan.cancel_immediately_on_failure | boolean | When parent is present | — |
data[].plan.created_at | string | When parent is present | — |
data[].plan.currency | string | When parent is present | — |
data[].plan.id | integer | When parent is present | — |
data[].plan.interval_count | integer | When parent is present | — |
data[].plan.interval_unit | string | When parent is present | — |
data[].plan.invoice_lead_days | integer | When parent is present | — |
data[].plan.is_active | boolean | When parent is present | — |
data[].plan.merchant_id | integer | When parent is present | — |
data[].plan.merchant_name | string | null | No | — |
data[].plan.meta_data | object | null | When parent is present | — |
data[].plan.past_due_grace_days | integer | When parent is present | — |
data[].plan.past_due_warnings_enabled | boolean | When parent is present | — |
data[].plan.plan_description | string | null | When parent is present | — |
data[].plan.plan_name | string | When parent is present | — |
data[].plan.trial_amount | number | null | When parent is present | — |
data[].plan.trial_notifications_enabled | boolean | When parent is present | — |
data[].plan.trial_period_days | integer | null | When parent is present | — |
data[].plan.uuid | string | When parent is present | — |
data[].simulation_clock_id | integer | null | No | — |
data[].simulation_clock_uuid | string | null | No | — |
data[].status | string | Yes | — |
data[].subscription_plan_id | integer | null | Yes | — |
data[].trial_end_date | string | 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 | — |
Read and update one subscription
All item and lifecycle paths use the uuid returned as the subscription's
public identifier. The artifact requires UUID syntax for each
subscription_id path parameter.
/api/v2/payments/subscriptions/{subscription_id}Get Subscription
Get subscription details by UUID. Args: subscription_id: UUID of the subscription merchant_key: Merchant API key info Returns: SubscriptionResponse: Subscription details
- Operation ID
get_subscription_api_v2_payments_subscriptions__subscription_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
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/subscriptions/${SUBSCRIPTION_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: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
/api/v2/payments/subscriptions/{subscription_id}Update Subscription
Update subscription details. Args: subscription_id: UUID of the subscription payload: Update data merchant_key: Merchant API key info Returns: SubscriptionResponse: Updated subscription
- Operation ID
update_subscription_api_v2_payments_subscriptions__subscription_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
Request body
Required application/json body using SubscriptionUpdate.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | string | null | No | greater than 0; maximum 999999.9999; pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ Update amount for next billing (max 999,999) |
interval_count | integer | null | No | minimum 1; maximum 365 |
interval_unit | SubscriptionIntervalUnit | null | No | one of DAY, WEEK, MONTH, YEAR |
meta_data | object | null | No | — |
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/subscriptions/${SUBSCRIPTION_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: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
Lifecycle actions
These actions return the contract's complete SubscriptionResponse. Do not
infer undocumented transition rules, retry timing, or customer-notification
behavior from the existence of an action.
/api/v2/payments/subscriptions/{subscription_id}/pausePause Subscription
Pause a subscription. Args: subscription_id: UUID of the subscription merchant_key: Merchant API key info Returns: SubscriptionResponse: Paused subscription
- Operation ID
pause_subscription_api_v2_payments_subscriptions__subscription_id__pause_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
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/subscriptions/${SUBSCRIPTION_ID}/pause" \
--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: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
/api/v2/payments/subscriptions/{subscription_id}/resumeResume Subscription
Resume a paused subscription. Args: subscription_id: UUID of the subscription merchant_key: Merchant API key info Returns: SubscriptionResponse: Resumed subscription
- Operation ID
resume_subscription_api_v2_payments_subscriptions__subscription_id__resume_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
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/subscriptions/${SUBSCRIPTION_ID}/resume" \
--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: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
/api/v2/payments/subscriptions/{subscription_id}/cancelCancel Subscription
Cancel a subscription. Args: subscription_id: UUID of the subscription payload: Cancellation data (reason, cancel_at_period_end) merchant_key: Merchant API key info Returns: SubscriptionResponse: Cancelled subscription
- Operation ID
cancel_subscription_api_v2_payments_subscriptions__subscription_id__cancel_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
Request body
Required application/json body using SubscriptionCancelRequest.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
cancel_at_period_end | boolean | No | default false Cancel at end of current period |
cancellation_reason | string | null | No | — Reason for cancellation |
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/subscriptions/${SUBSCRIPTION_ID}/cancel" \
--header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
--header "Content-Type: application/json" \
--data '{
"cancel_at_period_end": false
}'Run this reviewed operation in the API Lab →
Responses
200 Successful Response
Content type: application/json. Schema: SubscriptionResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
amount | number | Yes | — |
billing_cycle_count | integer | Yes | — |
billing_type | string | Yes | — |
cancellation_reason | string | null | Yes | — |
cancelled_at | string | null | Yes | — |
created_at | string | Yes | — |
currency | string | Yes | — |
current_period_end | string | Yes | — |
current_period_start | string | Yes | — |
customer | CustomerBasicInfo | null | No | — |
customer.email | string | null | When parent is present | — |
customer.id | integer | When parent is present | — |
customer.name | string | When parent is present | — |
customer.phone | string | When parent is present | — |
customer.uuid | string | null | No | — |
customer_id | integer | Yes | — |
days_until_trial_end | integer | null | Yes | — Calculate days remaining in trial period |
failed_payment_count | integer | Yes | — |
id | integer | Yes | — |
interval_count | integer | Yes | — |
interval_unit | string | Yes | — |
invoice_lead_days | integer | Yes | — |
is_in_trial | boolean | Yes | read only Check if subscription is currently in trial period |
is_simulation | boolean | Yes | read only True when this subscription belongs to a simulation (test) clock. |
merchant_id | integer | Yes | — |
merchant_name | string | null | No | — |
meta_data | object | null | Yes | — |
next_billing_date | string | Yes | — |
plan | SubscriptionPlanResponse | null | No | — |
plan.amount | number | When parent is present | — |
plan.billing_type | string | When parent is present | — |
plan.cancel_immediately_on_failure | boolean | When parent is present | — |
plan.created_at | string | When parent is present | — |
plan.currency | string | When parent is present | — |
plan.id | integer | When parent is present | — |
plan.interval_count | integer | When parent is present | — |
plan.interval_unit | string | When parent is present | — |
plan.invoice_lead_days | integer | When parent is present | — |
plan.is_active | boolean | When parent is present | — |
plan.merchant_id | integer | When parent is present | — |
plan.merchant_name | string | null | No | — |
plan.meta_data | object | null | When parent is present | — |
plan.past_due_grace_days | integer | When parent is present | — |
plan.past_due_warnings_enabled | boolean | When parent is present | — |
plan.plan_description | string | null | When parent is present | — |
plan.plan_name | string | When parent is present | — |
plan.trial_amount | number | null | When parent is present | — |
plan.trial_notifications_enabled | boolean | When parent is present | — |
plan.trial_period_days | integer | null | When parent is present | — |
plan.uuid | string | When parent is present | — |
simulation_clock_id | integer | null | No | — |
simulation_clock_uuid | string | null | No | — |
status | string | Yes | — |
subscription_plan_id | integer | null | Yes | — |
trial_end_date | string | 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 | — |
Billing and checkout
Billing history is paginated. Invoice generation returns the reviewed invoice detail schema, while subscription checkout returns the same public payment response envelope used by hosted checkout.
/api/v2/payments/subscriptions/{subscription_id}/billing-historyGet Subscription Billing History
Get billing history for a subscription. Args: subscription_id: UUID of the subscription merchant_key: Merchant API key info page: Page number per_page: Results per page Returns: dict: Paginated billing history
- Operation ID
get_subscription_billing_history_api_v2_payments_subscriptions__subscription_id__billing_history_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
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/subscriptions/${SUBSCRIPTION_ID}/billing-history?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: PublicBillingHistoryListResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
data | BillingHistoryResponse[] | Yes | — |
data[].amount | number | Yes | — |
data[].billing_date | string | Yes | — |
data[].created_at | string | Yes | — |
data[].currency | string | Yes | — |
data[].failure_reason | string | null | Yes | — |
data[].invoice | InvoiceBasicInfo | null | No | — |
data[].invoice.created_at | string | When parent is present | — |
data[].invoice.due_date | string | null | When parent is present | — |
data[].invoice.invoice_id | string | When parent is present | — |
data[].invoice.invoice_status | string | When parent is present | — |
data[].invoice.payable_amount | number | When parent is present | — |
data[].invoice.uuid | string | When parent is present | — |
data[].next_retry_at | string | null | Yes | — |
data[].payment_session_id | string | null | Yes | — |
data[].retry_count | integer | Yes | — |
data[].status | string | Yes | — |
data[].subscription_uuid | string | Yes | — |
data[].transaction_id | string | 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 | — |
/api/v2/payments/subscriptions/{subscription_id}/generate-invoiceGenerate Subscription Invoice
Manually generate an invoice for a subscription. This endpoint allows merchants to manually trigger invoice generation for a subscription. Useful when payment fails and you want to send a new invoice immediately instead of waiting for automatic retry. The invoice will be created with the current subscription amount and billing period, and an email will be automatically sent to the customer with payment link. Args: subscription_id: UUID of the subscription merchant_key: Merchant API key info Returns: InvoiceDetailsResponse: Created invoice details Raises: 400: If subscription is not in a valid state for billing 404: If subscription not found
- Operation ID
generate_subscription_invoice_api_v2_payments_subscriptions__subscription_id__generate_invoice_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
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/subscriptions/${SUBSCRIPTION_ID}/generate-invoice" \
--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: InvoiceDetailsResponse.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
all_total | number | Yes | — |
business_name | string | Yes | — |
customer | object | null | Yes | — |
due_date | string | null | Yes | — |
gross_discount | number | Yes | — |
invoice_id | string | Yes | — |
invoice_items | object[] | Yes | — |
invoice_status | string | Yes | — |
invoice_type | string | null | No | — |
merchant_logo | string | null | No | — |
payable_amount | number | 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 | — |
/api/v2/payments/subscriptions/{subscription_id}/checkoutCreate Subscription Checkout
Create a checkout session for a subscription payment. This endpoint creates a direct payment checkout session for a subscription, allowing customers to pay for the subscription amount immediately. This is useful for: - Collecting payment when trial period ends - Resuming paused subscriptions with payment - Retrying failed payments with new checkout - Manual billing with direct customer payment The subscription must be in a valid state (ACTIVE, PAST_DUE, PAUSED, or TRIALING ending soon). A payment session will be created and the customer can complete payment via the checkout URL. Args: subscription_id: UUID of the subscription payload: Checkout configuration (redirect URLs, etc.) merchant_key: Merchant API key info Returns: CheckoutResponse: Checkout URL and session details Raises: 400: If subscription is not in a valid state for checkout 404: If subscription not found
- Operation ID
create_subscription_checkout_api_v2_payments_subscriptions__subscription_id__checkout_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.subscription_id | string | Yes | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
Request body
Required application/json body using SubscriptionCheckoutRequest.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
cancel_url | string | null | No | maximum length 500 Callback URL if user cancels (uses merchant config default if not provided) |
fail_url | string | null | No | maximum length 500 Callback URL if payment fails (uses merchant config default if not provided) |
ipn_url | string | null | No | maximum length 500 Instant Payment Notification URL (uses merchant config default if not provided) |
metadata | object | null | No | — Additional checkout metadata |
success_url | string | null | No | maximum length 500 Callback URL after successful payment (uses merchant config default if not provided) |
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/subscriptions/${SUBSCRIPTION_ID}/checkout" \
--header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
--header "Content-Type: application/json" \
--data '{}'Run this reviewed operation in the API Lab →
Responses
200 Successful Response
Content type: application/json. Schema: PaymentResponses.
| Field | Type | Required | Constraints and meaning |
|---|---|---|---|
data | CheckoutResponse | SessionResponse | ProcessResponse | VerificationResponse | InvoiceDetailsResponse | CancelResponse | CheckoutResponse | SessionResponse | ProcessResponse | VerificationResponse | InvoiceDetailsResponse | CancelResponse[] | null | No | — |
data<CheckoutResponse>.checkout_url | string | When parent is present | — |
data<CheckoutResponse>.expires_at | string | When parent is present | — |
data<CheckoutResponse>.session_id | string | When parent is present | — |
data<SessionResponse>.bleeding | boolean | No | default false Whether merchant pays service charges (bleeding) |
data<SessionResponse>.business_name | string | null | No | — |
data<SessionResponse>.can_return_to_merchant | boolean | No | default false Whether the checkout may offer a 'return to merchant' action — true when the merchant's stored return URL passes moneybag.utils.redirect_guard. Deliberately a BOOLEAN, not the URL: this response is fetched by the hosted checkout from the browser, so any URL here would be readable by page scripts, devtools, error reporters and anyone holding the checkout link, and merchant cancel URLs routinely carry order tokens in their query string. The destination itself is never serialised — the checkout links to GET /payments/sessions/{session_id}/return, which resolves and validates it server-side at click time. |
data<SessionResponse>.currency | string | When parent is present | — |
data<SessionResponse>.customer | object | null | No | — |
data<SessionResponse>.emi_checkout_id | string | null | No | — Selected EMI configuration UUID if pre-selected |
data<SessionResponse>.emi_fee_bleeding | boolean | No | default false Whether merchant pays EMI fees (emi_fee_bleeding) |
data<SessionResponse>.emi_payment_options | object[] | null | No | — EMI payment options with calculations |
data<SessionResponse>.expires_at | string | When parent is present | — |
data<SessionResponse>.merchant_logo | string | null | No | — |
data<SessionResponse>.order_amount | string | When parent is present | pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ |
data<SessionResponse>.order_description | string | null | No | — |
data<SessionResponse>.order_id | string | When parent is present | — |
data<SessionResponse>.payment_options | object[] | When parent is present | — |
data<SessionResponse>.requires_emi | boolean | No | default false Whether EMI payment options are available |
data<SessionResponse>.selected_emi_configuration | SelectedEMIConfiguration | null | No | — Selected EMI configuration with emi_configuration_id and service_id |
data<SessionResponse>.selected_emi_configuration.emi_configuration_id | string | When parent is present | — Selected EMI configuration ID |
data<SessionResponse>.selected_emi_configuration.service_id | string | null | No | — Public merchant payment service UUID, matches payment_options[].service_id |
data<SessionResponse>.session_id | string | When parent is present | — |
data<SessionResponse>.status | string | When parent is present | — |
data<ProcessResponse>.meta | object | null | No | — |
data<ProcessResponse>.redirect_url | string | null | No | format uri; minimum length 1 |
data<ProcessResponse>.transaction_id | string | When parent is present | — |
data<VerificationResponse>.amount | string | When parent is present | pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ |
data<VerificationResponse>.charge_amount | string | When parent is present | pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ |
data<VerificationResponse>.currency | string | When parent is present | — |
data<VerificationResponse>.customer | Customer | When parent is present | — |
data<VerificationResponse>.customer.address | string | null | No | maximum length 200 Customer's address |
data<VerificationResponse>.customer.city | string | null | No | maximum length 50 Customer's city |
data<VerificationResponse>.customer.country | string | null | No | maximum length 50 Customer's country |
data<VerificationResponse>.customer.email | string | When parent is present | format email; maximum length 100 Customer's email address |
data<VerificationResponse>.customer.metadata | object | null | No | — Additional customer-specific data |
data<VerificationResponse>.customer.name | string | When parent is present | maximum length 255 Customer's full name |
data<VerificationResponse>.customer.phone | string | When parent is present | — Customer's phone number |
data<VerificationResponse>.customer.postcode | string | null | No | maximum length 20 Customer's postal code |
data<VerificationResponse>.customer.state | string | null | No | — Customer's state/division/province (e.g. 'Dhaka', 'Chattogram'). Optional. Forwarded to processors that require a billing division; supplying a real value improves AVS accuracy and therefore risk and chargeback outcomes. |
data<VerificationResponse>.order_id | string | When parent is present | — |
data<VerificationResponse>.payment_method | string | When parent is present | — |
data<VerificationResponse>.payment_reference_id | string | When parent is present | — |
data<VerificationResponse>.status | string | When parent is present | — |
data<VerificationResponse>.transaction_id | string | When parent is present | — |
data<VerificationResponse>.verified | boolean | When parent is present | — |
data<InvoiceDetailsResponse>.all_total | number | When parent is present | — |
data<InvoiceDetailsResponse>.business_name | string | When parent is present | — |
data<InvoiceDetailsResponse>.customer | object | null | When parent is present | — |
data<InvoiceDetailsResponse>.due_date | string | null | When parent is present | — |
data<InvoiceDetailsResponse>.gross_discount | number | When parent is present | — |
data<InvoiceDetailsResponse>.invoice_id | string | When parent is present | — |
data<InvoiceDetailsResponse>.invoice_items | object[] | When parent is present | — |
data<InvoiceDetailsResponse>.invoice_status | string | When parent is present | — |
data<InvoiceDetailsResponse>.invoice_type | string | null | No | — |
data<InvoiceDetailsResponse>.merchant_logo | string | null | No | — |
data<InvoiceDetailsResponse>.payable_amount | number | When parent is present | — |
data<InvoiceDetailsResponse>.uuid | string | When parent is present | — |
data<CancelResponse>.order_id | string | When parent is present | — |
data<CancelResponse>.redirect_url | string | When parent is present | — |
data<CancelResponse>.session_id | string | When parent is present | — |
data<CancelResponse>.status | string | No | default "CANCELLED" |
message | string | null | No | — |
meta | object | null | No | — |
success | boolean | 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 | — |