Plans and billing

curl -X GET 'https://api.yativo.com/api/v1/business/subscription' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "subscription": {
      "id": 4182,
      "status": "active",
      "plan": { "id": 2, "name": "Pro", "price": 30, "currency": "USD", "period_days": 30, "is_free": false, "is_custom": false },
      "billing_method": "card",
      "auto_renew": true,
      "cancel_at_period_end": false,
      "started_at": "2026-10-01T09:12:00+00:00",
      "current_period_end": "2026-10-31T09:12:00+00:00",
      "days_remaining": 18,
      "grace_ends_at": null,
      "last_payment_at": "2026-10-01T09:12:00+00:00",
      "payment_issue": null,
      "scheduled_change": null,
      "manage_card_url": "https://api.yativo.com/subscriptions/4182/card?expires=...&signature=...",
      "actions": { "can_renew": true, "can_cancel": true, "can_resume": false }
    },
    "payment_methods": ["wallet", "card"],
    "payment_options": [
      {
        "method": "wallet",
        "label": "Yativo USD balance",
        "description": "Pay from your USD wallet balance. The plan price is debited from the wallet; nothing is charged to a card.",
        "available": true,
        "unavailable_reason": null
      },
      {
        "method": "card",
        "label": "Card Payment",
        "description": "Pay the plan directly by card. This is a subscription charge only — it does not add funds to your USD wallet.",
        "available": true,
        "unavailable_reason": null
      }
    ]
  }
}

curl -X GET 'https://api.yativo.com/api/v1/business/subscription' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "subscription": {
      "id": 4182,
      "status": "active",
      "plan": { "id": 2, "name": "Pro", "price": 30, "currency": "USD", "period_days": 30, "is_free": false, "is_custom": false },
      "billing_method": "card",
      "auto_renew": true,
      "cancel_at_period_end": false,
      "started_at": "2026-10-01T09:12:00+00:00",
      "current_period_end": "2026-10-31T09:12:00+00:00",
      "days_remaining": 18,
      "grace_ends_at": null,
      "last_payment_at": "2026-10-01T09:12:00+00:00",
      "payment_issue": null,
      "scheduled_change": null,
      "manage_card_url": "https://api.yativo.com/subscriptions/4182/card?expires=...&signature=...",
      "actions": { "can_renew": true, "can_cancel": true, "can_resume": false }
    },
    "payment_methods": ["wallet", "card"],
    "payment_options": [
      {
        "method": "wallet",
        "label": "Yativo USD balance",
        "description": "Pay from your USD wallet balance. The plan price is debited from the wallet; nothing is charged to a card.",
        "available": true,
        "unavailable_reason": null
      },
      {
        "method": "card",
        "label": "Card Payment",
        "description": "Pay the plan directly by card. This is a subscription charge only — it does not add funds to your USD wallet.",
        "available": true,
        "unavailable_reason": null
      }
    ]
  }
}

Your account is always on a plan. The plan sets your default fees, your limits and the features listed on it. These endpoints show the plans you can choose, change or renew your plan, and pay the service fees billed to your account. Every endpoint acts on your business account, whoever on your team calls it. Team members need the Plans → view permission to read and Plans → upgrade for everything else.

How you pay for a plan

Pass payment_method on quote, subscribe and renew. It defaults to wallet.

Method	`payment_method`	What happens
USD balance	`wallet`	The plan price is debited from your USD wallet. With `auto_renew` on, each renewal is debited too
Card	`card`	You get a `checkout_url` for a secure card payment page. The plan activates once the payment is confirmed, and renewals charge the saved card each period. Paying by card doesn’t add money to your USD wallet

To pay for a single period by card, subscribe by card and then turn off auto-renew. The card isn’t charged again, and the plan ends at the end of the period unless you renew it. GET /business/subscription returns payment_options: each method with a label, a description to show your users, available and unavailable_reason. Plans with custom negotiated pricing can only be paid from the USD balance. When a renewal isn’t paid, the plan stays active for a grace period. Pay before grace_ends_at (by wallet or card) to keep it. Otherwise the account moves to its fallback plan, usually the free plan.

Endpoints

Method	Path	What it does
`GET`	`/business/subscription`	Current plan and billing state
`GET`	`/business/subscription/plans`	Plans you can choose
`GET`	`/business/subscription/quote`	Cost and effect of choosing a plan
`POST`	`/business/subscription/subscribe`	Subscribe, upgrade or downgrade
`POST`	`/business/subscription/renew`	Pay for the current plan now
`POST`	`/business/subscription/cancel`	Stop renewing at the end of the period
`POST`	`/business/subscription/resume`	Undo a cancellation or a scheduled downgrade
`PUT`	`/business/subscription/auto-renew`	Turn automatic renewal on or off
`GET`	`/business/subscription/payments`	Plan payments
`GET`	`/business/subscription/history`	Plan changes and renewals

Get your current plan

GET /business/subscription

curl -X GET 'https://api.yativo.com/api/v1/business/subscription' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "subscription": {
      "id": 4182,
      "status": "active",
      "plan": { "id": 2, "name": "Pro", "price": 30, "currency": "USD", "period_days": 30, "is_free": false, "is_custom": false },
      "billing_method": "card",
      "auto_renew": true,
      "cancel_at_period_end": false,
      "started_at": "2026-10-01T09:12:00+00:00",
      "current_period_end": "2026-10-31T09:12:00+00:00",
      "days_remaining": 18,
      "grace_ends_at": null,
      "last_payment_at": "2026-10-01T09:12:00+00:00",
      "payment_issue": null,
      "scheduled_change": null,
      "manage_card_url": "https://api.yativo.com/subscriptions/4182/card?expires=...&signature=...",
      "actions": { "can_renew": true, "can_cancel": true, "can_resume": false }
    },
    "payment_methods": ["wallet", "card"],
    "payment_options": [
      {
        "method": "wallet",
        "label": "Yativo USD balance",
        "description": "Pay from your USD wallet balance. The plan price is debited from the wallet; nothing is charged to a card.",
        "available": true,
        "unavailable_reason": null
      },
      {
        "method": "card",
        "label": "Card Payment",
        "description": "Pay the plan directly by card. This is a subscription charge only — it does not add funds to your USD wallet.",
        "available": true,
        "unavailable_reason": null
      }
    ]
  }
}

Field	Meaning
`status`	`active`, `past_due` (a renewal failed; the plan is kept until `grace_ends_at`) or `overdue` (the grace period ended)
`billing_method`	`wallet`, `card`, `invoice`, `manual` (complimentary) or `free`
`current_period_end`	The date the plan is paid until
`payment_issue`	Why the last renewal failed, when `status` is `past_due` or `overdue`
`scheduled_change`	A downgrade waiting for the end of the period: `plan_id`, `plan_name` and `effective_at`
`manage_card_url`	Card billing only. Opens a page to update the card or download card receipts. Valid for 30 minutes; read the subscription again for a fresh link
`actions`	Whether you can renew, cancel or resume right now
`payment_methods`	The methods you can pass to subscribe and renew
`payment_options`	The same methods with display text and availability

An account with no plan is put on the free plan the first time it calls this endpoint.

List plans

GET /business/subscription/plans

Response

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "plans": [
      {
        "id": 2,
        "name": "Pro",
        "description": "For growing businesses",
        "price": 30,
        "currency": "USD",
        "period_days": 30,
        "is_free": false,
        "is_custom": false,
        "contact_sales": false,
        "is_current": true,
        "change_type": "renew",
        "features": [
          { "code": "payouts", "name": "Payouts per month", "description": null, "type": "limit", "limit": 500 }
        ],
        "metadata": null
      }
    ],
    "payment_methods": ["wallet", "card"]
  }
}

change_type says what choosing the plan would do: new, renew, upgrade (takes effect now) or downgrade (takes effect at the end of the paid period).
is_custom: true marks a plan built for your account with negotiated pricing. Only you see it.
contact_sales: true plans have price: null and can’t be bought through the API. Contact your account manager.
A feature limit of -1 means unlimited.

Get a quote

See what a plan change costs before you make it.

GET /business/subscription/quote?plan_id=3&payment_method=wallet

Response

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "action": "upgrade",
    "effective": "now",
    "price": 90,
    "credit": 15,
    "amount_due": 75,
    "currency": "USD",
    "period_end": "2026-11-12T10:00:00+00:00",
    "message": "Unused time on your current plan (15.00 USD) is credited against Scale."
  }
}

When you upgrade and pay from the USD balance, the unused part of your current paid period is credited (credit) and you pay amount_due. Card upgrades charge the full price, so credit is 0. A downgrade returns effective: "period_end" and amount_due: 0.

POST /business/subscription/subscribe

Field	Required	Description
`plan_id`	Yes	From `GET /business/subscription/plans`
`payment_method`	No	`wallet` (default) or `card`. Ignored for free plans
`auto_renew`	No	USD balance only. Defaults to `true`

curl -X POST 'https://api.yativo.com/api/v1/business/subscription/subscribe' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 5d1e8f2a-3b4c-4d6e-9f7a-1b2c3d4e5f60' \
  -H 'Content-Type: application/json' \
  -d '{ "plan_id": 3, "payment_method": "wallet", "auto_renew": true }'

curl -X POST 'https://api.yativo.com/api/v1/business/subscription/subscribe' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 8a2c4e6f-1b3d-4f5a-8c7e-9d0b1a2c3e4f' \
  -H 'Content-Type: application/json' \
  -d '{ "plan_id": 3, "payment_method": "card" }'

{
  "status": "success",
  "status_code": 200,
  "message": "Complete the payment to activate your plan.",
  "data": {
    "action": "checkout",
    "checkout_url": "https://api.yativo.com/subscriptions/checkout/6f0d3c4e-...",
    "quote": { "action": "upgrade", "price": 90, "credit": 0, "amount_due": 90, "currency": "USD" },
    "subscription": { "id": 4182, "status": "active", "billing_method": "wallet" }
  }
}

data.action says what happened:

`action`	Meaning	What to do
`activated`	The new plan is active now and the USD balance was debited	Show the new `subscription`
`renewed`	You chose your current plan, so it was renewed for another period	Nothing
`scheduled`	A downgrade. You keep the current plan until it ends	Show `subscription.scheduled_change`
`checkout`	A card payment is needed. The subscription is unchanged until it’s paid	Send the user to `checkout_url`

Pay a plan by card

Start the checkout

Call subscribe (or renew for the current plan) with payment_method: "card" and send the user to data.checkout_url. The link opens the secure card payment page.

The user pays

After paying, the user is sent back to Settings → Billing in the dashboard.

Confirm the plan

Read GET /business/subscription until billing_method is card and plan.id is the plan you chose. This usually takes a few seconds. Plan payments show as pending in GET /business/subscription/payments until then.

Checkout links expire after 60 minutes. Calling subscribe with card again for the same plan returns the open link while it’s still valid. When a card renewal fails, status becomes past_due: renew with card for a new checkout, or with wallet.

Renew now

Pay for the current plan straight away: renew early (the new period starts when the current one ends) or settle a past_due or overdue plan.

curl -X POST 'https://api.yativo.com/api/v1/business/subscription/renew' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 2e4f6a8c-0b1d-4e3f-a5c7-9e1b3d5f7a90' \
  -H 'Content-Type: application/json' \
  -d '{ "payment_method": "wallet" }'

Returns action: "renewed" for wallet, or action: "checkout" with a checkout_url for card. Free plans renew by themselves, so renewing one returns an error.

Cancel, resume and auto-renew

curl -X POST 'https://api.yativo.com/api/v1/business/subscription/cancel' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 6c8e0a2b-4d5f-4a7c-9e1b-3d5f7a9c1e20' \
  -H 'Content-Type: application/json' \
  -d '{ "reason": "Switching provider" }'

Cancel: reason is optional. The plan stays active until current_period_end, then the account moves to the free plan. Nothing more is charged, and cancel_at_period_end becomes true.
Resume: POST /business/subscription/resume turns renewal back on and drops a scheduled downgrade. It only works before the period ends.
Auto-renew: PUT /business/subscription/auto-renew with { "auto_renew": false }. For USD balance billing, the plan then isn’t renewed automatically; renew it yourself before it ends. For card billing it’s the same as cancel and resume.

Payment and plan history

GET /business/subscription/payments?per_page=20
GET /business/subscription/history?per_page=20

Both are paginated, newest first: the rows are in data and the page is in pagination (current_page, last_page, per_page, total). Each payment has id, status (succeeded, failed, pending or refunded), method, amount, currency, plan, invoice_number, period_start, period_end, failure_reason, paid_at and created_at. Each history entry has a type, from_plan, to_plan, by (You, Yativo or Automatic) and created_at. type is one of started, subscribed, upgraded, renewed, assigned, change_scheduled, cancel_scheduled, resumed, past_due, recovered, overdue, downgraded, ended, fallback, invoice_paid, extended, auto_renew_on or auto_renew_off. The account owner is emailed when a plan activates or renews, a few days before a renewal, when a renewal fails, when a plan becomes overdue or is downgraded, and when a cancellation or downgrade is scheduled.

Service fees

Some services are billed separately from your plan: account maintenance and the annual verification (KYC/KYB) review. Each charge is a bill. Bills aren’t transactions and never appear in your transaction history. Yativo collects outstanding bills from your USD balance when it covers them. You can also pay them by card.

Method	Path	What it does
`GET`	`/business/billing/pending`	Everything still owed, oldest due first
`GET`	`/business/billing/partially-paid`	Bills that are partly paid
`GET`	`/business/billing/history`	Every bill, newest first
`GET`	`/business/billing/{id}`	One bill with its line items and payments
`GET`	`/business/billing/{id}/line-items`	What the bill is for, per account or service
`GET`	`/business/billing/{id}/collections`	Every payment made against the bill
`POST`	`/business/billing/card-payments`	Pay outstanding bills by card
`GET`	`/business/billing/card-payments/{reference}`	Status of a card payment

Outstanding bills

GET /business/billing/pending

Response

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "total_outstanding": 25,
    "currency": "USD",
    "bills": [
      {
        "id": "9a4f2c1e-6b3d-4e8a-b7c5-1d2e3f4a5b6c",
        "reference": "BILL-9a4f2c1e-6b3d-4e8a-b7c5-1d2e3f4a5b6c",
        "type": "maintenance",
        "title": "Account maintenance",
        "billing_period": "2026-10",
        "period_start": "2026-10-01",
        "period_end": "2026-10-31",
        "due_date": "2026-11-01",
        "currency": "USD",
        "original_amount": 25,
        "amount_paid": 0,
        "outstanding_amount": 25,
        "status": "pending",
        "payment_method": null,
        "payment_reference": null,
        "paid_at": null,
        "last_collection_attempt_at": "2026-11-01T00:05:00+00:00",
        "created_at": "2026-11-01T00:00:00+00:00"
      }
    ]
  }
}

type is maintenance or kyc_annual.
status is pending, partially_paid, processing, paid, failed (a collection attempt failed) or cancelled. Outstanding bills are the ones in pending, partially_paid, processing or failed with an outstanding_amount above 0.
GET /business/billing/history takes optional status, type and per_page (up to 100) filters and returns bills with a pagination object.
line_items show each charged account or service with its description, service_type, account_number, customer_id and amounts. payments show each collection with its payment_method (wallet or card), amount, status, collected_at and failure_reason.

Pay bills by card

Start a card payment

Send the IDs of the bills to pay (1 to 50). The payment covers their full outstanding balance.

curl -X POST 'https://api.yativo.com/api/v1/business/billing/card-payments' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Idempotency-Key: 4b6d8f0a-2c3e-4a5b-8d7f-1a3c5e7b9d20' \
  -H 'Content-Type: application/json' \
  -d '{ "bill_ids": ["9a4f2c1e-6b3d-4e8a-b7c5-1d2e3f4a5b6c"] }'

Response

{
  "status": "success",
  "status_code": 201,
  "message": "Request successful",
  "data": {
    "reference": "bcp_01jbx7q2k9x0m3c8v1b5n6z4l2",
    "status": "initiated",
    "amount": 25,
    "currency": "USD",
    "checkout_url": "https://...",
    "bills": [{ "billing_record_id": "9a4f2c1e-6b3d-4e8a-b7c5-1d2e3f4a5b6c", "amount": 25 }],
    "failure_reason": null,
    "paid_at": null,
    "expires_at": "2026-11-05T15:00:00+00:00",
    "created_at": "2026-11-05T14:00:00+00:00"
  }
}

Send the user to checkout_url

The user pays on the secure card payment page and is sent back to Settings → Billing in the dashboard. Keep the reference: the return doesn’t include it.

Confirm the payment

Read GET /business/billing/card-payments/{reference} until status is succeeded. A bill only counts as paid once its card payment has succeeded.

Card payment `status`	Meaning
`initiated`	Waiting for the user to pay. `checkout_url` is set
`processing`	Payment submitted and waiting for confirmation. `checkout_url` is set
`succeeded`	Paid. The bills are settled
`failed`	The payment didn’t go through. `failure_reason` says why
`expired`	The link expired before payment. Start a new card payment

The link expires after expires_at, 60 minutes by default. Starting a card payment again for the same bills while one is open returns the open one.

Errors

Plan and billing errors return 422 with a message you can show the user. See Error response format for the full response.

Message	Cause
`Insufficient USD wallet balance: ...`	Add USD to your wallet, or pay with `payment_method: "card"`
`Please contact sales to move to the Enterprise plan.`	The plan has `contact_sales: true`
`This plan is not available.`	The plan is inactive or belongs to another account
`Card payments are not available right now. Pay from your wallet instead.`	Card payment is temporarily unavailable
`Free plans renew automatically.`	You called `renew` on a free plan
`Select at least one bill to pay.`	`bill_ids` is empty
`One or more selected bills are not outstanding.`	A bill in `bill_ids` is already paid, cancelled or not yours
`Card checkout could not be started. Please try again.`	The card payment page couldn’t be opened. Retry

Older plan endpoints

GET /business/plans/current, GET /business/plans/all, POST /business/plans/subscribe/{plan_id} and PUT /business/plans/upgrade/{plan_id} still work and follow the same rules: USD balance by default, or pass payment_method: "card" to get a checkout_url. Use the /business/subscription endpoints for new work.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Platform guides

Plans and billing

How you pay for a plan

Endpoints

Get your current plan

List plans

Get a quote

Pay a plan by card

Renew now

Cancel, resume and auto-renew

Payment and plan history

Service fees

Outstanding bills

Pay bills by card

Errors

Older plan endpoints

​How you pay for a plan

​Endpoints

​Get your current plan

​List plans

​Get a quote

​Subscribe, upgrade or downgrade

​Pay a plan by card

​Renew now

​Cancel, resume and auto-renew

​Payment and plan history

​Service fees

​Outstanding bills

​Pay bills by card

​Errors

​Older plan endpoints

How you pay for a plan

Endpoints

Get your current plan

List plans

Get a quote

Subscribe, upgrade or downgrade

Pay a plan by card

Renew now

Cancel, resume and auto-renew

Payment and plan history

Service fees

Outstanding bills

Pay bills by card

Errors

Older plan endpoints