Skip to content

Align SDK docs with OpenAPI spec #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
sandervanhooft wants to merge 1 commit into from
Closed

Align SDK docs with OpenAPI spec #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 10 additions & 37 deletions docs/Chargebacks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,14 @@ Below you'll find all properties for the Vatly Chargeback resource.
| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique identifier for the chargeback (`chb_...`). |
| `status` | `string` | The status: `open`, `won`, or `lost`. |
| `orderId` | `string` | The disputed order ID. |
| `amount` | `integer` | Chargeback amount in cents. |
| `currency` | `string` | Three-letter ISO currency code. |
| `reason` | `string|null` | Reason provided by the bank. |
| `resource` | `string` | Always `chargeback`. |
| `merchantId` | `string` | The merchant ID. |
| `testmode` | `bool` | Whether this is a test chargeback. |
| `amount` | `object` | Chargeback amount (`value` and `currency`). |
| `settlementAmount` | `object` | Amount deducted from settlement (may differ from `amount`). |
| `reason` | `string` | Reason code for the dispute (e.g. `fraud`, `product_not_received`, `duplicate`). |
| `originalOrderId` | `string` | The ID of the original order that was disputed. |
| `orderId` | `string\|null` | The credit note order ID (after processing). |
| `createdAt` | `string` | Creation timestamp (ISO 8601). |

---
Expand All @@ -35,9 +37,9 @@ Retrieve a chargeback by its ID.
```php
$chargeback = $vatly->chargebacks->get('chb_abc123');

echo $chargeback->status;
echo $chargeback->amount / 100 . ' ' . $chargeback->currency;
echo $chargeback->reason;
echo $chargeback->amount->value . ' ' . $chargeback->amount->currency;
echo $chargeback->originalOrderId;
```


Expand Down Expand Up @@ -66,35 +68,6 @@ Retrieve a paginated list of all chargebacks.
$chargebacks = $vatly->chargebacks->list();

foreach ($chargebacks as $chargeback) {
echo $chargeback->id . ': ' . $chargeback->status;
echo $chargeback->id . ': ' . $chargeback->reason;
}
```



---

## Chargeback statuses

| Status | Description |
|--------|-------------|
| `open` | Dispute is ongoing |
| `won` | You won the dispute |
| `lost` | You lost the dispute |

---

## Helper methods



The Chargeback object provides convenient helper methods.




```php
$chargeback->isOpen(); // true if status is 'open'
$chargeback->isWon(); // true if status is 'won'
$chargeback->isLost(); // true if status is 'lost'
```
2 changes: 1 addition & 1 deletion docs/OneOffProducts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Below you'll find all properties for the Vatly One-Off Product resource.
| `amount` | `integer` | Price in cents. |
| `currency` | `string` | Three-letter ISO currency code. |
| `testmode` | `bool` | Whether this is a test product. |
| `active` | `bool` | Whether the product is active. |
| `status` | `string` | The status: `approved`, `draft`, or `archived`. |
| `createdAt` | `string` | Creation timestamp (ISO 8601). |

---
Expand Down
4 changes: 1 addition & 3 deletions docs/Orders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Order resource.
| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique identifier for the order (`ord_...`). |
| `status` | `string` | The status: `pending`, `paid`, `failed`, or `refunded`. |
| `status` | `string` | The status: `pending`, `paid`, or `failed`. |
| `customerId` | `string` | The customer ID. |
| `checkoutId` | `string|null` | The checkout ID (for initial orders). |
| `subscriptionId` | `string|null` | The subscription ID (for recurring orders). |
Expand Down Expand Up @@ -94,7 +94,6 @@ $orders = $vatly->orders->list([
| `pending` | Order is awaiting payment |
| `paid` | Payment successful |
| `failed` | Payment failed |
| `refunded` | Order has been refunded |

---

Expand All @@ -111,5 +110,4 @@ The Order object provides convenient helper methods.
$order->isPaid(); // true if status is 'paid'
$order->isPending(); // true if status is 'pending'
$order->isFailed(); // true if status is 'failed'
$order->isRefunded(); // true if status is 'refunded'
```
12 changes: 7 additions & 5 deletions docs/Refunds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Refund resource.
| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique identifier for the refund (`ref_...`). |
| `status` | `string` | The status: `pending`, `succeeded`, or `failed`. |
| `status` | `string` | The status: `pending`, `completed`, `failed`, or `canceled`. |
| `orderId` | `string` | The order ID being refunded. |
| `amount` | `integer` | Refund amount in cents. |
| `currency` | `string` | Three-letter ISO currency code. |
Expand Down Expand Up @@ -124,8 +124,9 @@ foreach ($refunds as $refund) {
| Status | Description |
|--------|-------------|
| `pending` | Refund is being processed |
| `succeeded` | Refund completed successfully |
| `completed` | Refund completed successfully |
| `failed` | Refund failed |
| `canceled` | Refund was canceled |

---

Expand All @@ -139,7 +140,8 @@ The Refund object provides convenient helper methods.


```php
$refund->isPending(); // true if status is 'pending'
$refund->isSucceeded(); // true if status is 'succeeded'
$refund->isFailed(); // true if status is 'failed'
$refund->isPending(); // true if status is 'pending'
$refund->isCompleted(); // true if status is 'completed'
$refund->isFailed(); // true if status is 'failed'
$refund->isCanceled(); // true if status is 'canceled'
```
2 changes: 1 addition & 1 deletion docs/SubscriptionPlans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Below you'll find all properties for the Vatly Subscription Plan resource.
| `intervalCount` | `integer` | Number of intervals between billings. |
| `trialDays` | `integer|null` | Default trial period in days. |
| `testmode` | `bool` | Whether this is a test plan. |
| `active` | `bool` | Whether the plan is active. |
| `status` | `string` | The status: `approved`, `draft`, or `archived`. |
| `createdAt` | `string` | Creation timestamp (ISO 8601). |

---
Expand Down
25 changes: 11 additions & 14 deletions docs/Subscriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Below you'll find all properties for the Vatly Subscription resource.
| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique identifier for the subscription (`sub_...`). |
| `status` | `string` | The status: `active`, `canceled`, `past_due`, `trialing`, `paused`, or `ended`. |
| `status` | `string` | The status: `active`, `created`, `trial`, `on_grace_period`, or `paused`. |
| `customerId` | `string` | The customer ID. |
| `planId` | `string` | The subscription plan ID. |
| `testmode` | `bool` | Whether this is a test subscription. |
Expand Down Expand Up @@ -102,8 +102,8 @@ Cancel a subscription. The subscription will remain active until the end of the
```php
$subscription = $vatly->subscriptions->cancel('sub_abc123');

// Subscription is now 'canceled' but active until period end
echo $subscription->status; // 'canceled'
// Subscription is now on grace period until current period ends
echo $subscription->status; // 'on_grace_period'
echo $subscription->currentPeriodEnd; // When it ends
```

Expand All @@ -116,11 +116,10 @@ echo $subscription->currentPeriodEnd; // When it ends
| Status | Description |
|--------|-------------|
| `active` | Subscription is active and billing |
| `canceled` | Subscription is canceled, active until period end |
| `past_due` | Payment failed, in grace period |
| `trialing` | In trial period |
| `created` | Subscription created, not yet active |
| `trial` | In trial period |
| `on_grace_period` | Canceled but still active until current period ends |
| `paused` | Subscription is paused |
| `ended` | Subscription has ended |

---

Expand All @@ -134,11 +133,9 @@ The Subscription object provides convenient helper methods.


```php
$subscription->isActive(); // true if status is 'active'
$subscription->isCanceled(); // true if status is 'canceled'
$subscription->isTrialing(); // true if status is 'trialing'
$subscription->isPastDue(); // true if status is 'past_due'
$subscription->hasEnded(); // true if status is 'ended'
$subscription->onTrial(); // true if currently in trial
$subscription->onGracePeriod(); // true if canceled but still active
$subscription->isActive(); // true if status is 'active'
$subscription->isCreated(); // true if status is 'created'
$subscription->onTrial(); // true if status is 'trial'
$subscription->onGracePeriod(); // true if status is 'on_grace_period'
$subscription->isPaused(); // true if status is 'paused'
```
2 changes: 1 addition & 1 deletion docs/Webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Vatly sends webhooks to notify your application when events happen, like success
| `subscription.ended` | Subscription ended |
| `order.paid` | Order payment received |
| `refund.created` | Refund initiated |
| `refund.succeeded` | Refund completed |
| `refund.completed` | Refund completed |
| `chargeback.created` | Chargeback received |
| `chargeback.won` | Chargeback dispute won |
| `chargeback.lost` | Chargeback dispute lost |
Expand Down