Payments

Create and manage payment intents, refunds, payouts, checkout sessions, and payment links. All amounts are in the smallest currency unit (cents for USD).

Authentication

All payment endpoints require a valid JWT or API key in the Authorization header. See Authentication.

Endpoints

POST/payments/intentsCreate a payment intent

POST/payments/intents/:id/confirmConfirm and capture a payment

GET/payments/:idRetrieve a transaction

GET/merchants/:merchantId/paymentsList all transactions for a merchant

POST/payments/:id/refundRefund a payment (full or partial)

POST/merchants/:merchantId/payoutsCreate a payout to a merchant bank account

GET/merchants/:merchantId/payoutsList payout history

POST/checkout/hosted/:storeIdCreate a hosted checkout session for a store (API key, dashboard session or checkout token)

GET/checkout/:sessionIdRetrieve a checkout session

POST/merchants/:merchantId/payment-linksCreate a reusable payment link

GET/merchants/:merchantId/payment-linksList payment links

Create a Payment Intent

POST/payments/intentsCreate a payment intent

Request Body

{
"amount": 2499,
"currency": "USD",
"storeId": "store_abc123",
"merchantId": "merch_xyz789",
"customerEmail": "[email protected]",
"idempotencyKey": "order_12345"
}

Field	Type	Required	Description
`amount`	number	Yes	Amount in smallest currency unit (min: 1)
`currency`	string	Yes	Three-letter ISO currency code (max 3 chars)
`storeId`	string	Yes	Target store ID
`merchantId`	string	Yes	Merchant ID
`customerEmail`	string	No	Customer email for receipts
`idempotencyKey`	string	No	Unique key to prevent duplicate charges

The intent is created in a pending state. Capture it with the confirm endpoint.

Confirm a Payment

POST/payments/intents/:id/confirmConfirm and capture a payment

Confirms the payment intent identified by :id through the configured payment provider (mock or real Stripe via env flag) and transitions the transaction to succeeded or failed.

Retrieve a Transaction

GET/payments/:idRetrieve a transaction

Returns the transaction record including status, amount, currency, and provider metadata.

List Transactions

GET/merchants/:merchantId/paymentsList all transactions for a merchant

Returns all transactions belonging to the given merchant, most recent first.

Refund a Payment

POST/payments/:id/refundRefund a payment (full or partial)

Request Body

{
"amount": 1000,
"reason": "Customer requested refund"
}

Field	Type	Required	Description
`amount`	number	No	Partial refund amount in cents (min: 1). Omit for a full refund.
`reason`	string	No	Reason recorded with the refund

Idempotency

Refunds are not automatically idempotent. Track refund state on your side or pass an idempotencyKey on the original intent to avoid duplicate refunds.

Payouts

POST/merchants/:merchantId/payoutsCreate a payout

GET/merchants/:merchantId/payoutsList payout history

Request Body

{
"amount": 50000,
"currency": "USD",
"destination": "ba_ext_bank_account_id"
}

Field	Type	Required	Description
`amount`	number	Yes	Payout amount in cents (min: 1)
`currency`	string	Yes	Three-letter ISO currency code
`destination`	string	No	External bank account ID. Defaults to the merchant's primary account.

Checkout Sessions

These payment-module session endpoints create a server-side checkout session tied to a store and merchant. For the hosted checkout flow (authentication, checkout tokens, the payment page URL and the checkout.session.* webhooks), see the dedicated Checkout page.

POST/checkout/hosted/:storeIdCreate a hosted checkout session for a store (API key, dashboard session or checkout token)

GET/checkout/:sessionIdRetrieve a checkout session

Request Body

{
"amount": 4999,
"currency": "USD",
"storeId": "store_abc123",
"merchantId": "merch_xyz789",
"successUrl": "https://yoursite.com/success",
"cancelUrl": "https://yoursite.com/cancel"
}

Field	Type	Required	Description
`amount`	number	Yes	Amount in cents (min: 1)
`currency`	string	Yes	Three-letter ISO currency code
`storeId`	string	Yes	Target store ID
`merchantId`	string	Yes	Merchant ID
`successUrl`	string	No	Redirect URL on success
`cancelUrl`	string	No	Redirect URL on cancel

Payment Links

POST/merchants/:merchantId/payment-linksCreate a reusable payment link

GET/merchants/:merchantId/payment-linksList payment links

Request Body

{
"amount": 1999,
"currency": "USD",
"storeId": "store_abc123",
"description": "Premium Plan - Monthly"
}

Field	Type	Required	Description
`amount`	number	Yes	Amount in cents (min: 1)
`currency`	string	Yes	Three-letter ISO currency code
`storeId`	string	Yes	Target store ID
`description`	string	No	Description shown on the payment page