Guides
Testing
Use test helper endpoints to simulate billing events like subscription renewals and payment failures in sandbox mode.
Overview
Vatly provides test helper endpoints that let you simulate billing events without waiting for real billing cycles. These endpoints are only available in test mode and require a test_ prefixed API token.
Fast-forward subscription renewal
Simulates a subscription renewal cycle, allowing you to test renewal billing flows, lifecycle events, and webhooks without waiting for the actual billing interval.
Request
POST /v1/test-helpers/subscriptions/{subscriptionId}/fast-forward-renewal
| Parameter | Type | Description |
|---|---|---|
subscriptionId | string | ID of the subscription to renew (starts with subscription_) |
No request body is required.
Example
curl -X POST https://api.vatly.com/v1/test-helpers/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE/fast-forward-renewal \
-H "Authorization: Bearer test_your_api_key_here"
$vatly->testHelpers->fastForwardRenewal('subscription_Lp3mNvBxKw7RjTgYcZaE');
Response
Returns the updated subscription with new renewal dates:
{
"id": "subscription_Lp3mNvBxKw7RjTgYcZaE",
"resource": "subscription",
"customerId": "customer_Lp3mNvBxKw7RjTgYcZaE",
"testmode": true,
"name": "Pro Monthly",
"description": "Full access to all Pro features",
"billingAddress": {
"fullName": "John Doe",
"companyName": "Acme Corp",
"streetAndNumber": "123 Main Street",
"city": "Berlin",
"postalCode": "10115",
"country": "DE"
},
"basePrice": {
"value": "29.00",
"currency": "EUR"
},
"quantity": 1,
"interval": "month",
"intervalCount": 1,
"status": "active",
"startedAt": "2024-01-15T10:30:00Z",
"endedAt": null,
"cancelledAt": null,
"renewedAt": "2024-03-15T10:30:00Z",
"renewedUntil": "2024-04-15T10:30:00Z",
"nextRenewalAt": "2024-04-15T10:30:00Z",
"trialUntil": null,
"links": {
"self": {
"href": "https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE",
"type": "application/json"
},
"customer": {
"href": "https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE",
"type": "application/json"
}
}
}
Simulate payment failure
Simulates a failed mandated payment, allowing you to test payment failure handling, retry logic, dunning flows, and webhook notifications.
Request
POST /v1/test-helpers/mandated-payments/{transactionId}/simulate-failure
| Parameter | Type | In | Description |
|---|---|---|---|
transactionId | string | path | ID of the mandated payment transaction to fail |
reason | string | body | Failure reason (optional, defaults to general_failure) |
Failure reasons
| Reason | Description |
|---|---|
insufficient_funds | Customer's account has insufficient funds |
invalid_mandate | The payment mandate is invalid |
mandate_canceled | The mandate has been canceled |
account_closed | The customer's account is closed |
card_expired | The customer's card has expired |
authentication_failed | Payment authentication failed |
general_failure | General payment failure (default) |
Example
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->testHelpers->simulatePaymentFailure(
'mollie_mandated_payment_Xk9pQrSvWm4NjLhYbUcP',
['reason' => 'insufficient_funds']
);
Response
{
"id": "mollie_mandated_payment_Xk9pQrSvWm4NjLhYbUcP",
"status": "failed",
"failureReason": "insufficient_funds"
}