Accept One-Time Payments

A payment is a standalone one-time charge with no subscription or plan attached. Commet calculates tax, generates an invoice, and sends a receipt on every payment automatically.

For lifetime deals and one-off purchases billed as a plan (add-ons, consumption models), use One-Time Plans instead.

Link vs. charge

There are two ways to take a one-time payment.

Link (payments.create): builds a hosted payment link. The customer opens the url and pays with any card. Vaults the payment method on confirmation.
Charge (payments.charge): bills a customer’s already-vaulted payment method off-session. No customer interaction, no url.

Create a payment link

Returns a Payment with a url. Redirect the customer to it to collect payment.

const payment = await commet.payments.create({
  amount: 25000,
  currency: 'usd',
  description: 'Annual report',
  customerId: 'user_123',
  successUrl: 'https://yourapp.com/thanks',
})

redirect(payment.url)

payment = commet.payments.create(
    amount=25000,
    currency='usd',
    description='Annual report',
    customer_id='user_123',
    success_url='https://yourapp.com/thanks',
)

redirect(payment.url)

payment, err := client.Payments.Create(ctx, &commet.CreatePaymentParams{
    Amount:      25000,
    Currency:    "usd",
    Description: "Annual report",
    CustomerID:  "user_123",
    SuccessURL:  "https://yourapp.com/thanks",
})

// redirect(payment.URL)

CreatePaymentParams params = CreatePaymentParams.builder()
    .amount(25000)
    .currency("usd")
    .description("Annual report")
    .customerId("user_123")
    .successUrl("https://yourapp.com/thanks")
    .build();
var payment = commet.payments().create(params);

// redirect(payment.url())

$result = $commet->payments->create(
    amount: 25000,
    currency: 'usd',
    description: 'Annual report',
    customerId: 'user_123',
    successUrl: 'https://yourapp.com/thanks',
);

redirect($result->url);

curl -X POST https://commet.co/api/v1/payments \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "usd",
    "description": "Annual report",
    "customerId": "user_123",
    "successUrl": "https://yourapp.com/thanks"
  }'

commet payments create \
  --amount 25000 \
  --currency usd \
  --description "Annual report" \
  --customer-id user_123 \
  --success-url https://yourapp.com/thanks

amount is in cents. 25000 is $250.00.

Parameters

Parameter	Type	Required	Description
`amount`	`number`	Yes	Charge amount in cents
`currency`	`string`	Yes	ISO 4217 currency code (`usd`, `eur`, `brl`)
`description`	`string`	Yes	Shown on the payment link, invoice, and receipt
`customerId`	`string`	No	Commet customer ID (`cus_xxx`) or your external ID
`successUrl`	`string`	No	Where the customer lands after paying
`metadata`	`object`	No	Key-value pairs. Shape: `{ [key: string]: string }`

Charge a saved payment method

Bills a customer’s vaulted payment method off-session. The customer must have a payment method on file.

const payment = await commet.payments.charge({
  customerId: 'user_123',
  amount: 25000,
  currency: 'usd',
  description: 'Annual report',
})

response = commet.payments.charge(
    customer_id='user_123',
    amount=25000,
    currency='usd',
    description='Annual report',
)

result, err := client.Payments.Charge(ctx, &commet.ChargePaymentParams{
    CustomerID:  "user_123",
    Amount:      25000,
    Currency:    "usd",
    Description: "Annual report",
})

ChargePaymentParams params = ChargePaymentParams.builder()
    .customerId("user_123")
    .amount(25000)
    .currency("usd")
    .description("Annual report")
    .build();
var payment = commet.payments().charge(params);

$result = $commet->payments->charge(
    customerId: 'user_123',
    amount: 25000,
    currency: 'usd',
    description: 'Annual report',
);

curl -X POST https://commet.co/api/v1/payments/charge \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "user_123",
    "amount": 25000,
    "currency": "usd",
    "description": "Annual report"
  }'

commet payments charge \
  --customer-id user_123 \
  --amount 25000 \
  --currency usd \
  --description "Annual report"

Parameters

Parameter	Type	Required	Description
`customerId`	`string`	Yes	Commet customer ID (`cus_xxx`) or your external ID
`amount`	`number`	Yes	Charge amount in cents
`currency`	`string`	Yes	ISO 4217 currency code (`usd`, `eur`, `brl`)
`description`	`string`	Yes	Shown on the invoice and receipt
`metadata`	`object`	No	Key-value pairs. Shape: `{ [key: string]: string }`

Retrieve a payment

const payment = await commet.payments.get({ id: 'pay_123' })

List payments

const { data } = await commet.payments.list({
  customerId: 'user_123',
  limit: 20,
})

Parameter	Type	Required	Description
`customerId`	`string`	No	Filter to one customer
`limit`	`number`	No	Page size
`cursor`	`string`	No	Pagination cursor from the previous page

Cancel a payment link

Cancels a pending link so it can no longer be paid.

await commet.payments.cancel({ id: 'pay_123' })

Only a link that has not been paid or started processing can be canceled. Charges cannot be canceled.

The Payment object

Field	Type	Description
`id`	`string`	Payment ID (`pay_xxx`)
`customerId`	`string \| null`	Customer the payment belongs to
`kind`	`"link" \| "charge"`	How the payment was taken
`status`	`string`	Current state (see below)
`provider`	`"stripe" \| "commet" \| "dlocal"`	Payment provider that processed it
`amountSubtotal`	`number`	Pre-tax amount in cents
`taxAmount`	`number`	Tax in cents
`amountTotal`	`number`	Subtotal + tax in cents
`currency`	`string`	ISO 4217 currency code
`description`	`string`	Description set at creation
`metadata`	`object \| null`	Key-value pairs set at creation
`url`	`string \| null`	Hosted payment link. `null` for charges
`expiresAt`	`string \| null`	When the link expires
`createdAt`	`string`	ISO 8601 datetime
`updatedAt`	`string`	ISO 8601 datetime
`object`	`"payment"`	Object type
`livemode`	`boolean`	`false` for sandbox payments

Statuses

pending: The link was created and is waiting for the customer to pay.
processing: The payment is being confirmed with the provider.
succeeded: The payment completed and an invoice was generated.
requires_action: The customer must complete an extra step such as 3D Secure.
failed: The payment did not go through.
canceled: The link was canceled before payment.

failed and requires_action are not terminal for links: the customer can reopen the same payment link and pay with another card, as long as the link hasn’t expired.

View in the dashboard

Navigate to Payments. Each payment shows its status, amount, tax, customer, and the generated invoice.

Limitations

amount is in cents — minor units of the currency
Tax is calculated automatically and added on top of amount
payments.charge requires a vaulted payment method on the customer
Charges cannot be canceled
A link can only be canceled while pending

Quickstart

Learn

Resources

Plugins

Accept One-Time Payments

Link vs. charge

Create a payment link

Parameters

Charge a saved payment method

Parameters

Retrieve a payment

List payments

Cancel a payment link

The Payment object

Statuses

View in the dashboard

Limitations

​Link vs. charge

​Create a payment link

​Parameters

​Charge a saved payment method

​Parameters

​Retrieve a payment

​List payments

​Cancel a payment link

​The Payment object

​Statuses

​View in the dashboard

​Limitations

Link vs. charge

Create a payment link

Parameters

Charge a saved payment method

Parameters

Retrieve a payment

List payments

Cancel a payment link

The Payment object

Statuses

View in the dashboard

Limitations