Payment Methods API

Every project configures one or more payment providers so subscribers can buy plans.

Every project configures one or more payment providers so subscribers can buy plans. These endpoints let you read which providers a project has connected and in what mode, switch each one on or off, push the plan catalogue to its gateway again, and remove one. Entering or rotating credentials remains dashboard-only, because each provider needs its own OAuth or secret-entry flow that a generic REST layer cannot safely reproduce.

Endpoints

GET/v1/projects/{project}/payment-methodsList a project's payment methods GET/v1/projects/{project}/payment-methods/{method}Get a payment method DELETE/v1/projects/{project}/payment-methods/{method}Delete a payment method POST/v1/projects/{project}/payment-methods/{method}/activateActivate a payment method POST/v1/projects/{project}/payment-methods/{method}/deactivateDeactivate a payment method POST/v1/projects/{project}/payment-methods/{method}/syncSync a payment method's plans

List a project's payment methods

GET

curl https://api.subscriby.net/v1/projects/$PROJECT_ID/payment-methods \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

Every payment method attached to the project, newest first.

Requires ability

project-payment-method:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_payment_methods

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Query Parameters

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.

Range1 <= value <= 100

Default25

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

Responses

200OKapplication/json

The page, newest first.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods"

{  "data": [    {      "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "provider": "stripe",      "connector": null,      "mode": "live",      "linked": true,      "active": true,      "created_at": "2026-05-18T10:05:00Z",      "updated_at": "2026-05-18T10:05:00Z"    }  ],  "links": {    "first": "string",    "last": "string",    "prev": "string",    "next": "string"  },  "meta": {    "current_page": 1,    "from": 1,    "last_page": 1,    "links": [      {        "url": "string",        "label": "string",        "active": true      }    ],    "path": "string",    "per_page": 0,    "to": 1,    "total": 0  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: PaymentMethodResource[];  links: Links;  meta: Meta;}export interface PaymentMethodResource {  id: string;  project_id: string;  provider: string | null;  connector: string;  mode: string;  linked: boolean;  active: boolean;  created_at: string | null;  updated_at: string | null;}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

Get a payment method

GET

The method without its credentials. A method is resolved within the project: a method id that does not belong to the project, or a project outside the caller's tenant, is 404 RESOURCE_NOT_FOUND, so foreign rows never leak.

provider is the stored provider key: a gateway slug (stripe, paypal, razorpay, paystack, ceypay, skrill, coinpayments, accesscode) or a connector:provider key for a currency a connector brings (telegram:stars for Telegram Stars). A project carries one method per provider key and mode, so two connectors can each bring their own currency to the same project. Rows created before provider keys existed carried platformcurrency; the connector's data migration rewrites them, and until it has run that word still reads as the native method of the project's connector.
connector is the connector behind a native payment method (telegram for a telegram:stars row), null for every gateway and for access codes. A connector declares its native providers through its manifest's native_payments capability, and the dashboard offers one option per provider of every connector that is connected on the project.
mode is test or live. Drives which set of provider credentials is used.
linked is true once the provider handshake (OAuth callback, API-key verify, etc.) has completed successfully.
active is the creator's toggle. A linked-but-inactive method cannot be used to charge subscribers.

Credentials never leave. Provider credentials (API keys, webhook secrets, connected account ids, Stripe Connect onboarding state) live in the encrypted configuration and are never serialised through REST or MCP, even for tokens with view ability. The dashboard is the only surface that reveals them, and only to the creator.

Requires ability

project-payment-method:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_payment_method

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

method*string

The method, resolved within the project by the route binder.

Formatuuid

Responses

200OKapplication/json

The method without its credentials.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "provider": "stripe",    "connector": null,    "mode": "live",    "linked": true,    "active": true,    "created_at": "2026-05-18T10:05:00Z",    "updated_at": "2026-05-18T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: PaymentMethodResource;}export interface PaymentMethodResource {  id: string;  project_id: string;  provider: string | null;  connector: string;  mode: string;  linked: boolean;  active: boolean;  created_at: string | null;  updated_at: string | null;}

Delete a payment method

DELETE

curl -X DELETE https://api.subscriby.net/v1/projects/$PROJECT_ID/payment-methods/$METHOD_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Returns 204 No Content. The row is soft-deleted: subscriptions sold through it keep their gateway for refunds and history, and configuring the same provider and mode again later revives the row instead of creating a duplicate. Buyers lose that way to pay at once. Emits project.payment_method.deleted with a credential-free snapshot; an already-deleted id is a 404.

Requires ability

project-payment-method:delete

The token must hold this ability, or the call is refused with 403.

Fires one event

project.payment_method.deleted

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

delete_payment_method

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

method*string

The method, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Activate a payment method

POST

curl -X POST https://api.subscriby.net/v1/projects/$PROJECT_ID/payment-methods/$METHOD_ID/activate \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Offers the method at checkout again and re-queues the plan sync for that gateway. Answers 200 with the method. Idempotent: switching a method to the state it is already in writes nothing and emits nothing; when the switch flips, project.payment_method.updated fires once with changes.active.

Stripe needs its Connect handshake first. A Stripe method whose Connect onboarding never finished is refused: the row exists only so the creator can resume onboarding, and switching it on would offer buyers a gateway that fails at checkout. Finish onboarding from the dashboard, the only place the Connect handshake can complete.

Requires ability

project-payment-method:update

The token must hold this ability, or the call is refused with 403.

Fires one event

project.payment_method.updated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

activate_payment_method

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

method*string

The method, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

The method, switched on.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

For a Stripe method awaiting Connect onboarding.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08/activate" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "provider": "stripe",    "connector": null,    "mode": "live",    "linked": true,    "active": true,    "created_at": "2026-05-18T10:05:00Z",    "updated_at": "2026-05-18T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: PaymentMethodResource;}export interface PaymentMethodResource {  id: string;  project_id: string;  provider: string | null;  connector: string;  mode: string;  linked: boolean;  active: boolean;  created_at: string | null;  updated_at: string | null;}

Deactivate a payment method

POST

curl -X POST https://api.subscriby.net/v1/projects/$PROJECT_ID/payment-methods/$METHOD_ID/deactivate \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

The creator's switch. A deactivated method is no longer offered at checkout; the subscriptions already sold through it keep renewing with their gateway. Re-queues the plan sync like activating does. Answers 200 with the method; idempotent, and project.payment_method.updated fires once with changes.active when the switch flips.

Requires ability

project-payment-method:update

The token must hold this ability, or the call is refused with 403.

Fires one event

project.payment_method.updated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

deactivate_payment_method

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

method*string

The method, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

The method, switched off.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08/deactivate" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "provider": "stripe",    "connector": null,    "mode": "live",    "linked": true,    "active": true,    "created_at": "2026-05-18T10:05:00Z",    "updated_at": "2026-05-18T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: PaymentMethodResource;}export interface PaymentMethodResource {  id: string;  project_id: string;  provider: string | null;  connector: string;  mode: string;  linked: boolean;  active: boolean;  created_at: string | null;  updated_at: string | null;}

Sync a payment method's plans

POST

curl -X POST https://api.subscriby.net/v1/projects/$PROJECT_ID/payment-methods/$METHOD_ID/sync \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Queues a push of the project owner's plans into the gateway's catalogue (Stripe products and prices, PayPal, Razorpay or CoinPayments plans) and answers 202 Accepted. The work runs in the background; each plan reports through plan.sync_completed as it lands. Queuing twice pushes the same catalogue twice, which is harmless.

Requires ability

project-payment-method:update

The token must hold this ability, or the call is refused with 403.

MCP tool

sync_payment_method_plans

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

method*string

The method, resolved within the project by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

202Acceptedapplication/json

The method id and sync_queued.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

For a gateway that keeps no catalogue (a connector's native currency, access codes, the redirect gateways).

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08/sync" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "payment_method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",    "status": "sync_queued"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: Data;}export interface Data {  payment_method_id: string;  status: string;}

OverviewCompare the nine payment providers Subscriby supports — regions, currencies, recurring, crypto, and more.project.* eventsConnecting a gateway raises no event, so the first thing an endpoint hears about a new method is its first update or its deletion; credentials never appear in a payload, and when keys are rotated from the dashboard changes.config.keys names which keys changed and nothing else.

Payment Methods API

EndpointsCopy Anchor Link

List a project's payment methodsCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Get a payment methodCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Delete a payment methodCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Activate a payment methodCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Deactivate a payment methodCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Sync a payment method's plansCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List a project's payment methods

Authorization

Path Parameters

Query Parameters

Responses

Get a payment method

Authorization

Path Parameters

Responses

Delete a payment method

Authorization

Path Parameters

Header Parameters

Responses

Activate a payment method

Authorization

Path Parameters

Header Parameters

Responses

Deactivate a payment method

Authorization

Path Parameters

Header Parameters

Responses

Sync a payment method's plans

Authorization

Path Parameters

Header Parameters

Responses