Api Reference
Test helpers
Simulate renewals and payment failures in test mode so you can verify recurring billing flows end to end.
Test helper endpoints
Vatly provides a small set of test helper endpoints for recurring billing scenarios. These endpoints are only available in test mode.
Use a
test_ API token for every endpoint on this page. Test helper endpoints are not available with live credentials.Fast-forward subscription renewal
POST /v1/test-helpers/subscriptions/{subscriptionId}/fast-forward-renewal
Simulate a renewal cycle for an existing subscription.
Useful for:
- testing renewal billing flows without waiting for the real billing interval
- verifying subscription lifecycle events and webhook delivery
- validating dunning or invoice follow-up automation in your sandbox flow
curl -X POST https://api.vatly.com/v1/test-helpers/subscriptions/sub_abc123def456/fast-forward-renewal \
-H "Authorization: Bearer test_your_api_key_here"
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('test_your_api_key_here');
$subscription = $vatly->testHelpers->fastForwardSubscriptionRenewal('sub_abc123def456');
{
"id": "sub_abc123def456",
"resource": "subscription",
"customerId": "cus_xyz789",
"subscriptionPlanId": "subscription_plan_premium",
"testmode": true,
"name": "Premium Plan",
"description": "Access to all premium features",
"billingAddress": {
"fullName": "John Doe",
"companyName": null,
"vatNumber": null,
"streetAndNumber": "123 Main St",
"streetAdditional": null,
"city": "Amsterdam",
"region": null,
"postalCode": "1011AB",
"country": "NL"
},
"basePrice": {
"value": "99.99",
"currency": "EUR"
},
"quantity": 1,
"interval": "month",
"intervalCount": 1,
"status": "active",
"startedAt": "2026-01-15T10:30:00Z",
"endedAt": null,
"cancelledAt": null,
"renewedAt": "2026-02-15T10:30:00Z",
"renewedUntil": "2026-03-15T10:30:00Z",
"nextRenewalAt": "2026-03-15T10:30:00Z",
"trialUntil": null,
"links": {
"self": {
"href": "https://api.vatly.com/v1/subscriptions/sub_abc123def456",
"type": "application/json"
},
"customer": {
"href": "https://api.vatly.com/v1/customers/cus_xyz789",
"type": "application/json"
}
}
}
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Endpoint not available for this token or resource |
404 | Subscription not found |
Simulate a payment failure
POST /v1/test-helpers/mandated-payments/{transactionId}/simulate-failure
Force a mandated payment into a failed state for testing.
Useful for:
- testing payment failure handling and retry logic
- verifying dunning behavior
- validating webhook notifications for failed renewal attempts
Request body
| Name | Type | Description |
|---|---|---|
reason | string | Optional failure reason. One of insufficient_funds, invalid_mandate, mandate_canceled, account_closed, card_expired, authentication_failed, or general_failure. Defaults to general_failure. |
curl -X POST https://api.vatly.com/v1/test-helpers/mandated-payments/mollie_mandated_payment_Xk9pQrSvWm4NjLhYbUcP/simulate-failure \
-H "Authorization: Bearer test_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"reason": "insufficient_funds"
}'
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('test_your_api_key_here');
$result = $vatly->testHelpers->simulateMandatedPaymentFailure(
'mollie_mandated_payment_Xk9pQrSvWm4NjLhYbUcP',
['reason' => 'insufficient_funds']
);
{
"id": "mollie_mandated_payment_Xk9pQrSvWm4NjLhYbUcP",
"status": "failed",
"failureReason": "insufficient_funds"
}
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Endpoint not available for this token or resource |
404 | Transaction not found |