Charge a NachoPay buyer

Charge a Buyer on a NachoPay subscription. Send the amount you want to bill and NachoNacho charges the Buyer's saved payment source off-session, then reports what was actually taken.

Where this fits in the NachoPay flow

1. The Buyer subscribes to your product in NachoNacho and completes a checkout that only saves a payment source — no money moves and no plan is created.
2. The Buyer is redirected to your app through your Token exchange URL with a single-use NN_token.
3. You call POST /tokens/resolve server-side to turn that token into a NachoNacho subscriptionId, and store it against your own customer record.
4. From then on, you decide when to bill. Every time you want money — at the end of a usage period, when a metered threshold is crossed, when a job completes — you call this endpoint with that subscriptionId.

There is no Stripe subscription behind a NachoPay subscription, so nothing is ever billed automatically. If you never call this endpoint, the Buyer is never charged.

How the amounts work

Two percentages are configured on your Seller account (NachoPay Settings in your NachoNacho dashboard):

• buyerDiscountPercentage: the discount NachoNacho applies to your requested amount to get the amount actually charged to the Buyer.
• revsharePercentage: the revshare fee you pay NachoNacho, taken off your requested amount. What is left is paid out to you.

For example, with a 20% buyer discount and a 30% revshare, requesting amount: 100 charges the Buyer $80 and pays you $70, with $30 kept by NachoNacho as the revshare fee. Send the price you would normally charge the customer — never apply the discount yourself, or it is taken twice. Payouts are handled outside of this endpoint.

The percentages in force at the moment of the call are recorded on the payment, so later changes to your account never rewrite past charges.

Prerequisites

• The subscription must be a NachoPay subscription and belong to a product you own.
• The Buyer must have completed the NachoPay checkout so a payment source is on file. Check can_be_charged on GET /subscriptions/{subscriptionId} if you want to verify this before billing.
• The Buyer must not have canceled the subscription. Cancellation is final and irreversible: once canceled, every charge is refused. GET /subscriptions/{subscriptionId} reports it as canceled, and can_be_charged turns false.

Things to know

• amount is in US dollars, must be greater than 0 and no more than 1000.
• The charge is off-session, so a card that needs authentication is declined rather than prompting the Buyer. A decline returns 402 with the Stripe reason and the paymentId so you can reconcile it.
• This endpoint is not idempotent: calling it twice bills the Buyer twice. Retry only when you did not receive a response, and use externalReference to recognise your own charges afterwards.
• Every charge appears to the Seller under NachoPay > Transactions and to the Buyer on their subscription page, whether it succeeded or failed.

{
  "subscriptionId": "cmmcoxge20001cnsppobu1anr",
  "description": "Usage for July 2026",
  "externalReference": "invoice_8842"
}

{
  "paymentId": "pi_3QabcDEfGhIjKlMn0PqRsTuV",
  "status": "succeeded",
  "subscriptionId": "cmmcoxge20001cnsppobu1anr",
  "currency": "USD",
  "amountRequested": 100,
  "amountChargedToBuyer": 80,
  "buyerDiscountPercentage": 20,
  "revsharePercentage": 30,
  "revshareAmount": 30,
  "sellerPayoutAmount": 70
}