Billing Platform API

curl https://pay.marthaia.com/v1/customers \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.customers.create({});

GET /customers scope customers:read · SDK billing.customers.list()

List customers

Parameters

`external_id`	string · query	Filter by your user id.
`email`	string · query	Filter by email.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Customer objects (data, has_more).

curl https://pay.marthaia.com/v1/customers \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.customers.list();

GET /customers/{id} scope customers:read · SDK billing.customers.retrieve()

Retrieve a customer

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/customers/cus_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.customers.retrieve("cus_01a15d…");

PATCH /customers/{id} scope customers:write · SDK billing.customers.update()

Update a customer

Parameters

id required string · path Object id.

Body · CustomerInput

`billing_address`	Address
`country`	string	ISO alpha-2.
`currency`	string	ISO 4217.
`email`	string
`external_id`	string	Your user id.
`locale`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.
`name`	string
`phone`	string

Returns

curl https://pay.marthaia.com/v1/customers/cus_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.customers.update("cus_01a15d…", {});

DELETE /customers/{id} scope customers:write · SDK billing.customers.del()

Anonymise a customer

Erases personal data; invoices and payments are kept.

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/customers/cus_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X DELETE

const result = await billing.customers.del("cus_01a15d…");

GET /customers/{id}/entitlements scope customers:read · SDK billing.customers.entitlements()

List a customer’s entitlements

The single place access is decided, from subscription status and the grace policy.

Parameters

id required string · path Object id.

Returns

A list of Entitlement objects (data, has_more).

curl https://pay.marthaia.com/v1/customers/cus_01a15d…/entitlements \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.customers.entitlements("cus_01a15d…");

GET /customers/{id}/payment_methods scope payment_methods:read · SDK billing.customers.paymentMethods()

List a customer’s saved payment methods

Parameters

id required string · path Object id.

Returns

A list of PaymentMethod objects (data, has_more).

curl https://pay.marthaia.com/v1/customers/cus_01a15d…/payment_methods \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.customers.paymentMethods("cus_01a15d…");

Products

POST /products scope products:write · SDK billing.products.create()

Create a product

Body · ProductInput

`active`	boolean
`description`	string
`features`	map
`group_key`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.
`name`	string

Returns

Product

curl https://pay.marthaia.com/v1/products \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.products.create({});

GET /products scope products:read · SDK billing.products.list()

List products

Parameters

`active`	boolean · query	Filter on active.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Product objects (data, has_more).

curl https://pay.marthaia.com/v1/products \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.products.list();

GET /products/{id} scope products:read · SDK billing.products.retrieve()

Retrieve a product

Parameters

id required string · path Object id.

Returns

Product

curl https://pay.marthaia.com/v1/products/prod_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.products.retrieve("prod_01a15d…");

PATCH /products/{id} scope products:write · SDK billing.products.update()

Update a product

Parameters

id required string · path Object id.

Body · ProductInput

`active`	boolean
`description`	string
`features`	map
`group_key`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.
`name`	string

Returns

Product

curl https://pay.marthaia.com/v1/products/prod_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.products.update("prod_01a15d…", {});

Prices

POST /prices scope products:write · SDK billing.prices.create()

Create a price

Give an amount for every currency you sell in: there is no exchange-rate conversion.

Body · PriceInput

`amounts` required	map	Minor units per currency, e.g. {"XAF": 5000, "USD": 900}.
`product` required	string	prod_…
`type` required	string	One of: one_time, recurring.
`external_checkout_url`	string
`interval`	string	Recurring only. One of: day, week, month, year.
`interval_count`	integer	Recurring only, default 1.
`lookup_key`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.
`nickname`	string
`tax_behavior`	string	One of: project, inclusive, exclusive.

Returns

Price

curl https://pay.marthaia.com/v1/prices \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amounts": {}, "product": "prod_01a15d…", "type": "one_time"}'

const result = await billing.prices.create({"amounts": {}, "product": "prod_01a15d…", "type": "one_time"});

GET /prices scope products:read · SDK billing.prices.list()

List prices

Parameters

`product`	string · query	Filter by prod_….
`active`	boolean · query	Filter on active.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Price objects (data, has_more).

curl https://pay.marthaia.com/v1/prices \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.prices.list();

GET /prices/{id} scope products:read · SDK billing.prices.retrieve()

Retrieve a price

Parameters

id required string · path Object id.

Returns

Price

curl https://pay.marthaia.com/v1/prices/price_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.prices.retrieve("price_01a15d…");

PATCH /prices/{id} scope products:write · SDK billing.prices.update()

Update a price

Parameters

id required string · path Object id.

Body · PriceUpdate

`active`	boolean
`amounts`	map	Only before the price is used.
`lookup_key`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.
`nickname`	string

Returns

Price

curl https://pay.marthaia.com/v1/prices/price_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.prices.update("price_01a15d…", {});

Checkout sessions

POST /checkout/sessions scope checkout:write · SDK billing.checkoutSessions.create()

Create a checkout session

Returns the hosted checkout url to redirect the customer to. Send an Idempotency-Key.

Body · CheckoutSessionInput

`mode` required	string	payment = one-off, subscription = recurring prices, setup = save a method without charging. One of: payment, subscription, setup.
`success_url` required	string	Absolute URL; {SESSION_ID} is replaced.
`allowed_methods`	string[]	Restrict the offer: kinds ("mobile_money"), connections (gwc_…) or one method (gwc_…:card). Pinned connections skip their own country rule.
`cancel_url`	string
`client_reference_id`	string
`currency`	string	Defaults to the customer’s, then the project’s.
`customer`	CheckoutCustomer
`customer_id`	string	Alternative to customer: an existing cus_….
`expires_in`	integer	Seconds, default from settings (24 h).
`items`	LineItem[]	Required unless mode is setup.
`locale`	string	fr or en.
`metadata`	map	Up to 50 string key/value pairs for your own use.

Returns

CheckoutSession

curl https://pay.marthaia.com/v1/checkout/sessions \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode": "payment", "success_url": "https://app.example.com/billing"}'

const result = await billing.checkoutSessions.create({"mode": "payment", "success_url": "https://app.example.com/billing"});

GET /checkout/sessions scope checkout:read · SDK billing.checkoutSessions.list()

List checkout sessions

Parameters

`status`	string · query	open, complete or expired.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of CheckoutSession objects (data, has_more).

curl https://pay.marthaia.com/v1/checkout/sessions \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.checkoutSessions.list();

GET /checkout/sessions/{id} scope checkout:read · SDK billing.checkoutSessions.retrieve()

Retrieve a checkout session

Call this on return instead of trusting the redirect.

Parameters

id required string · path Object id.

Returns

CheckoutSession

curl https://pay.marthaia.com/v1/checkout/sessions/cs_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.checkoutSessions.retrieve("cs_01a15d…");

POST /checkout/sessions/{id}/expire scope checkout:write · SDK billing.checkoutSessions.expire()

Expire a checkout session

Parameters

id required string · path Object id.

Returns

CheckoutSession

curl https://pay.marthaia.com/v1/checkout/sessions/cs_01a15d…/expire \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.checkoutSessions.expire("cs_01a15d…");

Subscriptions

POST /subscriptions scope subscriptions:write · SDK billing.subscriptions.create()

Create a subscription

For customers with a saved method; most integrations use a subscription checkout instead.

Body · SubscriptionInput

`customer` required	string	cus_…
`items` required	LineItem[]
`collection_method`	string	One of: automatic, send_invoice.
`currency`	string
`gateway_connection`	string	gwc_…
`mark_paid_reason`	string	Operator-assigned plan: first invoice settled manually with this reason.
`metadata`	map	Up to 50 string key/value pairs for your own use.
`payment_method`	string	pm_…

Returns

curl https://pay.marthaia.com/v1/subscriptions \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "cus_01a15d…", "items": []}'

const result = await billing.subscriptions.create({"customer": "cus_01a15d…", "items": []});

GET /subscriptions scope subscriptions:read · SDK billing.subscriptions.list()

List subscriptions

Parameters

`customer`	string · query	Filter by cus_….
`status`	string · query	Filter by status.
`collection_mode`	string · query	provider_managed or platform_managed.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Subscription objects (data, has_more).

curl https://pay.marthaia.com/v1/subscriptions \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.subscriptions.list();

GET /subscriptions/{id} scope subscriptions:read · SDK billing.subscriptions.retrieve()

Retrieve a subscription

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.subscriptions.retrieve("sub_01a15d…");

POST /subscriptions/{id}/change_plan scope subscriptions:write · SDK billing.subscriptions.changePlan()

Change plan

Platform-managed: creates an invoice for the new price, switched on payment. Provider-managed: gateway proration.

Parameters

id required string · path Object id.

Body · ChangePlanInput

`items` required	LineItem[]
`proration_behavior`	string	Provider-managed only. One of: create_prorations, none, always_invoice.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/change_plan \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items": []}'

const result = await billing.subscriptions.changePlan("sub_01a15d…", {"items": []});

POST /subscriptions/{id}/cancel scope subscriptions:write · SDK billing.subscriptions.cancel()

Cancel a subscription

Parameters

id required string · path Object id.

Body · CancelInput

`at_period_end`	boolean	Keep access until the period ends.
`reason`	string

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/cancel \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.subscriptions.cancel("sub_01a15d…", {});

POST /subscriptions/{id}/resume scope subscriptions:write · SDK billing.subscriptions.resume()

Remove a scheduled cancellation

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/resume \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.subscriptions.resume("sub_01a15d…");

POST /subscriptions/{id}/pause scope subscriptions:write · SDK billing.subscriptions.pause()

Pause collection

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/pause \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.subscriptions.pause("sub_01a15d…");

POST /subscriptions/{id}/unpause scope subscriptions:write · SDK billing.subscriptions.unpause()

Resume collection

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/unpause \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.subscriptions.unpause("sub_01a15d…");

POST /subscriptions/{id}/payment_method scope subscriptions:write · SDK billing.subscriptions.setPaymentMethod()

Change the payment method

Retries the open invoice immediately when past due.

Parameters

id required string · path Object id.

Body · PaymentMethodRef

payment_method string pm_…; default method when omitted.

Returns

curl https://pay.marthaia.com/v1/subscriptions/sub_01a15d…/payment_method \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.subscriptions.setPaymentMethod("sub_01a15d…", {});

Invoices

GET /invoices scope invoices:read · SDK billing.invoices.list()

List invoices

Parameters

`customer`	string · query	Filter by cus_….
`subscription`	string · query	Filter by sub_….
`status`	string · query	Filter by status.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Invoice objects (data, has_more).

curl https://pay.marthaia.com/v1/invoices \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.invoices.list();

POST /invoices scope invoices:write · SDK billing.invoices.create()

Create a manual invoice

Body · InvoiceInput

`customer` required	string	cus_…
`items` required	object[]
`auto_finalize`	boolean
`collection_method`	string	One of: automatic, send_invoice.
`currency`	string
`days_until_due`	integer
`description`	string
`metadata`	map	Up to 50 string key/value pairs for your own use.

Returns

curl https://pay.marthaia.com/v1/invoices \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "cus_01a15d…", "items": []}'

const result = await billing.invoices.create({"customer": "cus_01a15d…", "items": []});

GET /invoices/{id} scope invoices:read · SDK billing.invoices.retrieve()

Retrieve an invoice

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/invoices/inv_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.invoices.retrieve("inv_01a15d…");

GET /invoices/{id}/pdf scope invoices:read · SDK billing.invoices.pdf()

Download the invoice PDF

Parameters

id required string · path Object id.

Returns

The PDF file.

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/pdf \
  -H "Authorization: Bearer $BILLING_KEY"

const pdf = await billing.invoices.pdf("inv_01a15d…"); // ArrayBuffer

GET /invoices/{id}/link scope invoices:read · SDK billing.invoices.link()

Get the hosted pay link

Parameters

id required string · path Object id.

Returns

SessionLink

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/link \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.invoices.link("inv_01a15d…");

POST /invoices/{id}/finalize scope invoices:write · SDK billing.invoices.finalize()

Finalise a draft invoice

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/finalize \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.invoices.finalize("inv_01a15d…");

POST /invoices/{id}/pay scope invoices:write · SDK billing.invoices.pay()

Charge an open invoice

Parameters

id required string · path Object id.

Body · PaymentMethodRef

payment_method string pm_…; default method when omitted.

Returns

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/pay \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.invoices.pay("inv_01a15d…", {});

POST /invoices/{id}/void scope invoices:write · SDK billing.invoices.void()

Void an invoice

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/void \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.invoices.void("inv_01a15d…");

POST /invoices/{id}/mark_uncollectible scope invoices:write · SDK billing.invoices.markUncollectible()

Mark uncollectible

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/invoices/inv_01a15d…/mark_uncollectible \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)"

const result = await billing.invoices.markUncollectible("inv_01a15d…");

Payments

GET /payments scope payments:read · SDK billing.payments.list()

List payments

Parameters

`invoice`	string · query	Filter by inv_….
`customer`	string · query	Filter by cus_….
`status`	string · query	Filter by status.
`limit`	integer · query	1–100, default 20.
`starting_after`	string · query	Cursor: id of the last item of the previous page.
`ending_before`	string · query	Cursor: id of the first item of the next page.

Returns

A list of Payment objects (data, has_more).

curl https://pay.marthaia.com/v1/payments \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.payments.list();

GET /payments/{id} scope payments:read · SDK billing.payments.retrieve()

Retrieve a payment

Includes next_action for headless integrations.

Parameters

id required string · path Object id.

Returns

curl https://pay.marthaia.com/v1/payments/pay_01a15d… \
  -H "Authorization: Bearer $BILLING_KEY"

const result = await billing.payments.retrieve("pay_01a15d…");

POST /payments/{id}/refunds scope payments:write · SDK billing.payments.refund()

Refund a payment

Parameters

id required string · path Object id.

Body · RefundInput

`amount`	integer	Minor units; default the remaining refundable amount.
`manual`	boolean	Record a refund made outside the gateway.
`reason`	string

Returns

Refund

curl https://pay.marthaia.com/v1/payments/pay_01a15d…/refunds \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.payments.refund("pay_01a15d…", {});

POST /payments/{id}/authorize_otp scope payments:write · SDK billing.payments.authorizeOtp()

Submit a mobile money OTP

Parameters

id required string · path Object id.

Body · OTPInput

code required string Code typed by the customer; never stored.

Returns

curl https://pay.marthaia.com/v1/payments/pay_01a15d…/authorize_otp \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

const result = await billing.payments.authorizeOtp("pay_01a15d…", {"code": "123456"});

POST /payments/{id}/resend scope payments:write · SDK billing.payments.resend()

Send a new phone prompt

Creates a new attempt on the same invoice and cancels this one.

Parameters

id required string · path Object id.

Body · ResendInput

`operator`	string	New operator code.
`phone`	string	New number.

Returns

curl https://pay.marthaia.com/v1/payments/pay_01a15d…/resend \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const result = await billing.payments.resend("pay_01a15d…", {});

POST /payments/{id}/confirm scope payments:write · SDK billing.payments.confirm()

Confirm or reject manually

Secret keys only; audited.

Parameters

id required string · path Object id.

Body · ConfirmInput

`reason` required	string
`confirm`	boolean	false to reject; default true.

Returns

curl https://pay.marthaia.com/v1/payments/pay_01a15d…/confirm \
  -H "Authorization: Bearer $BILLING_KEY" \
  -X POST \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "…"}'

const result = await billing.payments.confirm("pay_01a15d…", {"reason": "…"});

POST /payments/{id}/poll scope payments:write · SDK billing.payments.poll()

Ask the gateway for the current status

Parameters

id required string · path Object id.

Returns