BiasDocs

Payments

A payment charges a customer’s card or bank account once, and can save it for later payments. The authorize and capture guide covers holding funds on a card, and bank payments covers settlement and returns.

The Payment object

Name
object
Type
"payment",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
ach_return
Type
object or null,
Description
Present when the customer's bank returned the debit. A debit returned after it succeeded keeps its status and gets a lost dispute.
Properties
Name
amount
Type
integer,
Description
The amount of the payment, in cents.
Name
amount_capturable
Type
integer,
Description
The amount that can still be captured.
Name
amount_received
Type
integer,
Description
The amount collected.
Name
amount_refunded
Type
integer,
Description
The amount refunded.
Name
capture_method
Type
enum,
Description
When to capture the payment.
Properties
Name
customer
Type
string or Customer or null,
Description
Expandable. The payment's customer.
Name
description
Type
string or null,
Description
What the payment is for.
Name
dispute
Type
string or Dispute or null,
Description
Expandable. The latest dispute received for this payment.
Name
fees
Type
object,
Description
The fees on the payment, in cents. Each is null until it's known.
Properties
Name
invoice
Type
string or Invoice or null,
Description
Expandable. The invoice this payment was created from.
Name
mandate
Type
string or null,
Description
The mandate a bank account debit was made under.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
off_session
Type
boolean or null,
Description
Whether the payment was merchant-initiated, without the customer present.
Name
payment_error
Type
object or null,
Description
Why a failed payment failed.
Properties
Name
payment_method
Type
string or PaymentMethod,
Description
Expandable. The payment method used for the payment.
Name
recurring
Type
boolean or null,
Description
Whether the merchant-initiated payment is one in a series charged on a fixed schedule, such as a subscription renewal.
Name
session
Type
string or CheckoutSession or null,
Description
Expandable. The checkout session this payment was created from.
Name
statement_descriptor
Type
string or null,
Description
The statement descriptor for the payment.
Name
status
Type
enum,
Description
The status of the payment.
Properties

The Payment object

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}

Get a payment

Retrieve a payment by its ID.

Required parameters

Name
id
Type
string,
Description
The ID of the payment to retrieve.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties

Returns

Returns the payment object.

Retrieve a payment

const payment = await bias.payments.get("id");

Response example

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}

List all payments

Retrieve a paginated list of payments.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
ending_before
Type
string,
Description
The ID of the object to list before, for pagination.
Name
starting_after
Type
string,
Description
The ID of the object to list after, for pagination.
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Description
Filters for the list, combined with and and or.
Properties

Returns

Returns a list of payment objects.

List all payments

const payment = await bias.payments.list();

Response example

{
  "object": "list",
  "items": [
    {
      "object": "payment",
      "live": true,
      "id": "pay_lUY2g0TuPzN9qi4couahd3",
      "created_at": 1750000000000,
      "amount": 1000,
      "amount_capturable": 0,
      "amount_received": 1000,
      "amount_refunded": 0,
      "fees": {
        "interchange": 28,
        "chargeback": 0,
        "platform": 13,
        "total": 41
      },
      "capture_method": "automatic",
      "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
      "description": "Payment for order 123",
      "dispute": null,
      "invoice": null,
      "mandate": null,
      "off_session": false,
      "recurring": false,
      "ach_return": null,
      "metadata": {},
      "payment_error": null,
      "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
      "session": null,
      "statement_descriptor": null,
      "status": "succeeded"
    }
  ],
  "has_more": true
}

Create a payment

A new payment charges the payment method right away. With capture_method: manual, a card is only authorized, and the funds are collected when you capture the payment.

A decline returns a payment error with a decline_code.

Required parameters

Name
payment_method
Type
string or object, object, or object,
Description
The payment method to charge: a saved payment method's ID, or new payment method details.
Properties

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
amount
Type
integer, at least 0,
Description
The amount to charge, in cents. With invoice, it's the invoice's remaining balance and can be omitted.
Name
capture_method
Type
enum, default is automatic
Description
When to capture the payment.
Properties
Name
customer
Type
string or null,
Description
The payment's customer.
Name
description
Type
string or null,
Description
What the payment is for.
Name
invoice
Type
string or null,
Description
The invoice the payment pays.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.
Name
mandate_data
Type
object,
Description
The customer's authorization for future debits, recorded as a mandate. Required when saving a bank account with setup_future_usage, and accepted only then.
Properties
Name
off_session
Type
boolean,
Description
Whether the customer is absent, such as for a renewal or a delayed charge. Requires a saved payment method, and true requires one saved with setup_future_usage: off_session. Defaults to true for a saved payment method, unless it was saved with on_session.
Name
recurring
Type
boolean, default is false
Description
Whether the payment is one in a series charged on a fixed schedule, such as your own subscription renewals. Charges made as needed aren't recurring. Requires off_session: true.
Name
statement_descriptor
Type
string or null,
Description
Overrides your default statement descriptor. It should start with your business name or domain, in printable ASCII without <, >, \, ', " or *.

Returns

Returns the payment object.

Create a payment

const payment = await bias.payments.create({
  amount: 1000,
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  description: "Snowboard bindings",
  payment_method: {
    billing_details: {
      name: "John Doe",
      address: {
        postal_code: "94111"
      }
    },
    card: {
      number: "4242424242424242",
      exp_month: 1,
      exp_year: 2030,
      cvc: "123"
    }
  }
});

Response example

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}

Capture a payment

Capturing collects the full amount a requires_capture payment authorized, and the payment becomes succeeded.

Required parameters

Name
id
Type
string,
Description
The ID of the payment to capture.

Returns

Returns the payment object.

Capture a payment

const payment = await bias.payments.capture("id");

Response example

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}

Cancel a payment

Canceling releases a card payment’s authorization while it’s requires_capture, or stops a bank account debit while it’s processing. The payment becomes canceled.

Required parameters

Name
id
Type
string,
Description
The ID of the payment to cancel.

Returns

Returns the payment object.

Cancel a payment

const payment = await bias.payments.cancel("id");

Response example

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}

Update a payment

Only a payment’s metadata can be updated.

Required parameters

Name
id
Type
string,
Description
The ID of the payment to update.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the payment object.

Update a payment

const payment = await bias.payments.update("id");

Response example

{
  "object": "payment",
  "live": true,
  "id": "pay_lUY2g0TuPzN9qi4couahd3",
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_capturable": 0,
  "amount_received": 1000,
  "amount_refunded": 0,
  "fees": {
    "interchange": 28,
    "chargeback": 0,
    "platform": 13,
    "total": 41
  },
  "capture_method": "automatic",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "description": "Payment for order 123",
  "dispute": null,
  "invoice": null,
  "mandate": null,
  "off_session": false,
  "recurring": false,
  "ach_return": null,
  "metadata": {},
  "payment_error": null,
  "payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "session": null,
  "statement_descriptor": null,
  "status": "succeeded"
}