Actions

The ballerinax/stripe package exposes the following clients:

Client	Purpose
`Client`	Provides access to all Stripe REST API V1 resources including customers, payments, invoices, subscriptions, products, and more.

Client

Provides access to all Stripe REST API V1 resources including customers, payments, invoices, subscriptions, products, and more.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig`	Required	Bearer token configuration. Provide your Stripe secret key as the `token` field.
`serviceUrl`	`string`	`https://api.stripe.com`	The base URL of the Stripe API.
`httpVersion`	`HttpVersion`	`HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`60`	Request timeout in seconds.
`retryConfig`	`RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`ProxyConfig`	`()`	Proxy server configuration.

Initializing the client

import ballerinax/stripe;

configurable string secretKey = ?;

stripe:Client stripe = check new ({
    auth: {
        token: secretKey
    }
});

Operations

Customer management

List all customers

Returns a list of customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Parameters:

Name	Type	Required	Description
`email`	`string?`	No	Filter by customer email address.
`limit`	`int?`	No	Maximum number of customers to return (1–100). Default is 10.
`starting_after`	`string?`	No	Cursor for pagination. Provide a customer ID to list customers created after this customer.

Returns: stripe:CustomerResourceCustomerList|error

Sample code:

stripe:CustomerResourceCustomerList customers = check stripe->/customers;

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "cus_PxN1234abcdef",
      "object": "customer",
      "name": "John Doe",
      "email": "[email protected]",
      "created": 1700000000
    }
  ],
  "has_more": false,
  "url": "/v1/customers"
}

Create a customer

Creates a new customer object with the provided details.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:customers_body`	Yes	Customer creation payload containing name, email, address, and other details.

Returns: stripe:Customer|error

Sample code:

stripe:Customer customer = check stripe->/customers.post({
    name: "John Doe",
    email: "[email protected]",
    address: {
        city: "Colombo",
        country: "LK"
    }
});

Sample response:

{
  "id": "cus_PxN1234abcdef",
  "object": "customer",
  "name": "John Doe",
  "email": "[email protected]",
  "address": {
    "city": "Colombo",
    "country": "LK"
  },
  "created": 1700000000,
  "livemode": false
}

Retrieve a customer

Retrieves the details of an existing customer by their ID.

Parameters:

Name	Type	Required	Description
`customer`	`string`	Yes	The ID of the customer to retrieve.

Returns: stripe:Customer|error

Sample code:

stripe:Customer customer = check stripe->/customers/["cus_PxN1234abcdef"];

Sample response:

{
  "id": "cus_PxN1234abcdef",
  "object": "customer",
  "name": "John Doe",
  "email": "[email protected]",
  "created": 1700000000
}

Update a customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters:

Name	Type	Required	Description
`customer`	`string`	Yes	The ID of the customer to update.
`payload`	`stripe:customers_customer_body`	Yes	Customer update payload.

Returns: stripe:Customer|error

Sample code:

stripe:Customer updated = check stripe->/customers/["cus_PxN1234abcdef"].post({
    name: "Jane Doe",
    email: "[email protected]"
});

Sample response:

{
  "id": "cus_PxN1234abcdef",
  "object": "customer",
  "name": "Jane Doe",
  "email": "[email protected]",
  "created": 1700000000
}

Delete a customer

Permanently deletes a customer. It cannot be undone. Any active subscriptions on the customer will also be cancelled.

Parameters:

Name	Type	Required	Description
`customer`	`string`	Yes	The ID of the customer to delete.

Returns: stripe:Deleted_customer|error

Sample code:

stripe:Deleted_customer deleted = check stripe->/customers/["cus_PxN1234abcdef"].delete();

Sample response:

{
  "id": "cus_PxN1234abcdef",
  "object": "customer",
  "deleted": true
}

Payment intents

Create a payment intent

Creates a PaymentIntent object. After creation, attach a payment method and confirm to continue the payment.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:payment_intents_body`	Yes	Payment intent creation payload including amount, currency, and optional parameters.

Returns: stripe:Payment_intent|error

Sample code:

stripe:Payment_intent paymentIntent = check stripe->/payment_intents.post({
    amount: 2000,
    currency: "usd",
    payment_method_types: ["card"]
});

Sample response:

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "requires_payment_method",
  "client_secret": "pi_3MtwBwLkdIwHu7ix28a3tqPa_secret_YrKJUKribcBjcG8HVhfZluoGH"
}

Retrieve a payment intent

Retrieves the details of a PaymentIntent that was previously created.

Parameters:

Name	Type	Required	Description
`intent`	`string`	Yes	The ID of the PaymentIntent to retrieve.

Returns: stripe:Payment_intent|error

Sample code:

stripe:Payment_intent intent = check stripe->/payment_intents/["pi_3MtwBwLkdIwHu7ix28a3tqPa"];

Sample response:

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "requires_payment_method"
}

List all payment intents

Returns a list of PaymentIntents.

Parameters:

Name	Type	Required	Description
`customer`	`string?`	No	Filter by customer ID.
`limit`	`int?`	No	Maximum number of results to return (1–100).

Returns: stripe:PaymentFlowsPaymentIntentResourcePaymentIntentList|error

Sample code:

stripe:PaymentFlowsPaymentIntentResourcePaymentIntentList intents = check stripe->/payment_intents;

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
      "object": "payment_intent",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  ],
  "has_more": false
}

Confirm a payment intent

Confirms a PaymentIntent, transitioning it to a state where it can process a payment.

Parameters:

Name	Type	Required	Description
`intent`	`string`	Yes	The ID of the PaymentIntent to confirm.
`payload`	`stripe:intent_confirm_body`	No	Confirmation payload with optional payment method and return URL.

Returns: stripe:Payment_intent|error

Sample code:

stripe:Payment_intent confirmed = check stripe->/payment_intents/["pi_3MtwBwLkdIwHu7ix28a3tqPa"]/confirm.post({
    payment_method: "pm_card_visa"
});

Sample response:

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded"
}

Cancel a payment intent

Cancels a PaymentIntent. After cancellation, no additional charges are made.

Parameters:

Name	Type	Required	Description
`intent`	`string`	Yes	The ID of the PaymentIntent to cancel.

Returns: stripe:Payment_intent|error

Sample code:

stripe:Payment_intent cancelled = check stripe->/payment_intents/["pi_3MtwBwLkdIwHu7ix28a3tqPa"]/cancel.post();

Sample response:

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "canceled"
}

Charges

Create a charge

Creates a new charge. Use the Payment Intents API for new integrations; this endpoint is for legacy compatibility.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:charges_body`	Yes	Charge creation payload including amount, currency, and source or customer.

Returns: stripe:Charge|error

Sample code:

stripe:Charge charge = check stripe->/charges.post({
    amount: 1500,
    currency: "usd",
    source: "tok_visa"
});

Sample response:

{
  "id": "ch_3MmlLrLkdIwHu7ix0snN0B15",
  "object": "charge",
  "amount": 1500,
  "currency": "usd",
  "status": "succeeded",
  "paid": true
}

Retrieve a charge

Retrieves the details of a charge that has previously been created.

Parameters:

Name	Type	Required	Description
`charge`	`string`	Yes	The ID of the charge to retrieve.

Returns: stripe:Charge|error

Sample code:

stripe:Charge charge = check stripe->/charges/["ch_3MmlLrLkdIwHu7ix0snN0B15"];

Sample response:

{
  "id": "ch_3MmlLrLkdIwHu7ix0snN0B15",
  "object": "charge",
  "amount": 1500,
  "currency": "usd",
  "status": "succeeded"
}

List all charges

Returns a list of charges you have previously created.

Parameters:

Name	Type	Required	Description
`customer`	`string?`	No	Filter by customer ID.
`limit`	`int?`	No	Maximum number of results to return.

Returns: stripe:ChargeList|error

Sample code:

stripe:ChargeList charges = check stripe->/charges;

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "ch_3MmlLrLkdIwHu7ix0snN0B15",
      "amount": 1500,
      "currency": "usd",
      "status": "succeeded"
    }
  ],
  "has_more": false
}

Products & prices

Create a product

Creates a new product object.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:products_body`	Yes	Product creation payload with name and optional details.

Returns: stripe:Product|error

Sample code:

stripe:Product product = check stripe->/products.post({
    name: "Premium Plan",
    description: "Access to all premium features"
});

Sample response:

{
  "id": "prod_OkIaGzRTh1gQqH",
  "object": "product",
  "name": "Premium Plan",
  "description": "Access to all premium features",
  "active": true,
  "created": 1700000000
}

List all products

Returns a list of your products.

Parameters:

Name	Type	Required	Description
`active`	`boolean?`	No	Filter by active status.
`limit`	`int?`	No	Maximum number of results to return.

Returns: stripe:ProductList|error

Sample code:

stripe:ProductList products = check stripe->/products;

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "prod_OkIaGzRTh1gQqH",
      "object": "product",
      "name": "Premium Plan",
      "active": true
    }
  ],
  "has_more": false
}

Create a price

Creates a new price for an existing product.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:prices_body`	Yes	Price creation payload with currency, unit_amount, and product reference.

Returns: stripe:Price|error

Sample code:

stripe:Price price = check stripe->/prices.post({
    unit_amount: 1999,
    currency: "usd",
    recurring: {
        interval: "month"
    },
    product: "prod_OkIaGzRTh1gQqH"
});

Sample response:

{
  "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
  "object": "price",
  "unit_amount": 1999,
  "currency": "usd",
  "recurring": {
    "interval": "month"
  },
  "product": "prod_OkIaGzRTh1gQqH",
  "active": true
}

List all prices

Returns a list of your prices.

Parameters:

Name	Type	Required	Description
`product`	`string?`	No	Filter by product ID.
`active`	`boolean?`	No	Filter by active status.

Returns: stripe:PriceList|error

Sample code:

stripe:PriceList prices = check stripe->/prices(product = "prod_OkIaGzRTh1gQqH");

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
      "unit_amount": 1999,
      "currency": "usd",
      "product": "prod_OkIaGzRTh1gQqH"
    }
  ],
  "has_more": false
}

Invoices

Create an invoice

Creates a draft invoice for a given customer. The draft invoice pulls in all pending invoice items on that customer.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:invoices_body`	Yes	Invoice creation payload with customer and optional details.

Returns: stripe:Invoice|error

Sample code:

stripe:Invoice invoice = check stripe->/invoices.post({
    customer: "cus_PxN1234abcdef",
    collection_method: "send_invoice",
    days_until_due: 30
});

Sample response:

{
  "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "customer": "cus_PxN1234abcdef",
  "status": "draft",
  "collection_method": "send_invoice",
  "days_until_due": 30,
  "amount_due": 0
}

Retrieve an invoice

Retrieves the invoice with the given ID.

Parameters:

Name	Type	Required	Description
`invoice`	`string`	Yes	The ID of the invoice to retrieve.

Returns: stripe:Invoice|error

Sample code:

stripe:Invoice invoice = check stripe->/invoices/["in_1MtHbELkdIwHu7ixl4OzzPMv"];

Sample response:

{
  "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "customer": "cus_PxN1234abcdef",
  "status": "draft",
  "amount_due": 0
}

Finalize an invoice

Finalizes a draft invoice, transitioning its status from draft to open. A finalized invoice can no longer be deleted or have its monetary values changed.

Parameters:

Name	Type	Required	Description
`invoice`	`string`	Yes	The ID of the invoice to finalize.

Returns: stripe:Invoice|error

Sample code:

stripe:Invoice finalized = check stripe->/invoices/["in_1MtHbELkdIwHu7ixl4OzzPMv"]/finalize.post();

Sample response:

{
  "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "status": "open",
  "amount_due": 2000,
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1M2JTk/test_xxxxx"
}

List all invoices

Returns a list of invoices. The invoices are returned sorted by creation date, with the most recent ones appearing first.

Parameters:

Name	Type	Required	Description
`customer`	`string?`	No	Filter by customer ID.
`status`	`string?`	No	Filter by invoice status: `draft`, `open`, `paid`, `uncollectible`, or `void`.

Returns: stripe:InvoicesList|error

Sample code:

stripe:InvoicesList invoices = check stripe->/invoices(customer = "cus_PxN1234abcdef");

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
      "status": "open",
      "amount_due": 2000,
      "customer": "cus_PxN1234abcdef"
    }
  ],
  "has_more": false
}

Subscriptions

Create a subscription

Creates a new subscription on an existing customer.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:subscriptions_body`	Yes	Subscription creation payload with customer, items, and optional parameters.

Returns: stripe:Subscription|error

Sample code:

stripe:Subscription subscription = check stripe->/subscriptions.post({
    customer: "cus_PxN1234abcdef",
    items: [
        { price: "price_1MoBy5LkdIwHu7ixZhnattbh" }
    ]
});

Sample response:

{
  "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
  "object": "subscription",
  "customer": "cus_PxN1234abcdef",
  "status": "active",
  "items": {
    "data": [
      {
        "price": {
          "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
          "unit_amount": 1999
        }
      }
    ]
  }
}

Retrieve a subscription

Retrieves the subscription with the given ID.

Parameters:

Name	Type	Required	Description
`subscription_exposed_id`	`string`	Yes	The ID of the subscription to retrieve.

Returns: stripe:Subscription|error

Sample code:

stripe:Subscription sub = check stripe->/subscriptions/["sub_1MowQVLkdIwHu7ixeRlqHVzs"];

Sample response:

{
  "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
  "object": "subscription",
  "customer": "cus_PxN1234abcdef",
  "status": "active",
  "current_period_end": 1700604800
}

Cancel a subscription

Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.

Parameters:

Name	Type	Required	Description
`subscription_exposed_id`	`string`	Yes	The ID of the subscription to cancel.

Returns: stripe:Subscription|error

Sample code:

stripe:Subscription cancelled = check stripe->/subscriptions/["sub_1MowQVLkdIwHu7ixeRlqHVzs"].delete();

Sample response:

{
  "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
  "object": "subscription",
  "status": "canceled",
  "canceled_at": 1700100000
}

List all subscriptions

Returns a list of your active subscriptions.

Parameters:

Name	Type	Required	Description
`customer`	`string?`	No	Filter by customer ID.
`status`	`string?`	No	Filter by status: `active`, `past_due`, `canceled`, etc.

Returns: stripe:SubscriptionList|error

Sample code:

stripe:SubscriptionList subs = check stripe->/subscriptions(customer = "cus_PxN1234abcdef");

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
      "status": "active",
      "customer": "cus_PxN1234abcdef"
    }
  ],
  "has_more": false
}

Refunds

Create a refund

Creates a refund for a charge or a payment intent.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:refunds_body`	Yes	Refund creation payload with charge or payment_intent and optional amount.

Returns: stripe:Refund|error

Sample code:

stripe:Refund refund = check stripe->/refunds.post({
    payment_intent: "pi_3MtwBwLkdIwHu7ix28a3tqPa",
    amount: 500
});

Sample response:

{
  "id": "re_3MtwBwLkdIwHu7ix0snN0B15",
  "object": "refund",
  "amount": 500,
  "currency": "usd",
  "status": "succeeded",
  "payment_intent": "pi_3MtwBwLkdIwHu7ix28a3tqPa"
}

Retrieve a refund

Retrieves the details of an existing refund.

Parameters:

Name	Type	Required	Description
`refund`	`string`	Yes	The ID of the refund to retrieve.

Returns: stripe:Refund|error

Sample code:

stripe:Refund refund = check stripe->/refunds/["re_3MtwBwLkdIwHu7ix0snN0B15"];

Sample response:

{
  "id": "re_3MtwBwLkdIwHu7ix0snN0B15",
  "object": "refund",
  "amount": 500,
  "currency": "usd",
  "status": "succeeded"
}

Balance

Retrieve balance

Retrieves the current account balance, based on the authentication that was used to make the request.

Returns: stripe:Balance|error

Sample code:

stripe:Balance balance = check stripe->/balance;

Sample response:

{
  "object": "balance",
  "available": [
    {
      "amount": 125000,
      "currency": "usd",
      "source_types": {
        "card": 125000
      }
    }
  ],
  "pending": [
    {
      "amount": 5000,
      "currency": "usd"
    }
  ],
  "livemode": false
}

List balance transactions

Returns a list of transactions that have contributed to the Stripe account balance.

Parameters:

Name	Type	Required	Description
`limit`	`int?`	No	Maximum number of results to return.
`type`	`string?`	No	Filter by transaction type (e.g., `charge`, `refund`, `payout`).

Returns: stripe:BalanceTransactionsList|error

Sample code:

stripe:BalanceTransactionsList txns = check stripe->/balance_transactions(limit = 5);

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "txn_1MiN3gLkdIwHu7ixT6lFMOHd",
      "object": "balance_transaction",
      "amount": 1500,
      "currency": "usd",
      "type": "charge",
      "net": 1420,
      "fee": 80
    }
  ],
  "has_more": true
}

Payouts

Create a payout

Sends funds to your own bank account. The Stripe account balance must cover the payout amount.

Parameters:

Name	Type	Required	Description
`payload`	`stripe:payouts_body`	Yes	Payout creation payload with amount and currency.

Returns: stripe:Payout|error

Sample code:

stripe:Payout payout = check stripe->/payouts.post({
    amount: 10000,
    currency: "usd"
});

Sample response:

{
  "id": "po_1MtRbE2eZvKYlo2CRzQp6dYG",
  "object": "payout",
  "amount": 10000,
  "currency": "usd",
  "status": "in_transit",
  "arrival_date": 1700604800
}

List all payouts

Returns a list of existing payouts.

Parameters:

Name	Type	Required	Description
`status`	`string?`	No	Filter by payout status.
`limit`	`int?`	No	Maximum number of results to return.

Returns: stripe:PayoutList|error

Sample code:

stripe:PayoutList payouts = check stripe->/payouts;

Sample response:

{
  "object": "list",
  "data": [
    {
      "id": "po_1MtRbE2eZvKYlo2CRzQp6dYG",
      "amount": 10000,
      "currency": "usd",
      "status": "paid"
    }
  ],
  "has_more": false
}

Client​

Configuration​

Initializing the client​

Operations​

Customer management​

Payment intents​

Charges​

Products & prices​

Invoices​

Subscriptions​

Refunds​

Balance​

Payouts​

Client

Configuration

Initializing the client

Operations

Customer management

Payment intents

Charges

Products & prices

Invoices

Subscriptions

Refunds

Balance

Payouts