---
title: "Charge a NachoPay buyer"
method: POST
path: "/payments"
tags: ["NachoPay"]
---

# Charge a NachoPay buyer

`POST /payments`

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.

## Request body

- object
  - `subscriptionId` string, required — NachoNacho subscription ID (from POST /tokens/resolve response)
  - `description` string — Optional description shown on the Buyer's Stripe receipt. Truncated to 350 characters.
  - `externalReference` string — Optional identifier of your own, stored on the payment metadata. Truncated to 200 characters.

## Response `200`

Payment created and confirmed

- object
  - `paymentId` string — Stripe PaymentIntent ID
  - `status` string — Stripe PaymentIntent status. See the [Stripe API documentation](https://stripe.com/docs/api/payment_intents/object).
  - `subscriptionId` string
  - `currency` string
  - `amountRequested` number, float — The amount you asked to bill
  - `amountChargedToBuyer` number, float — The amount actually charged to the Buyer, after the buyer discount
  - `buyerDiscountPercentage` number, float
  - `revsharePercentage` number, float — The revshare fee percentage you pay NachoNacho.
  - `revshareAmount` number, float — The revshare fee kept by NachoNacho for this payment.
  - `sellerPayoutAmount` number, float — The amount paid out to you for this payment: your requested amount minus the revshare fee.

## Other responses

- `400` — Missing or invalid `subscriptionId`, `amount` missing / not positive / above the $1000 maximum, subscription is not a NachoPay subscription, the Buyer canceled the subscription, Buyer has no saved payment source, or the Buyer company has no Stripe customer
- `401` — Missing or invalid JWT
- `402` — The Buyer's payment source was declined
- `403` — Seller is not the owner of this product
- `404` — Subscription not found or Seller company not found
- `500` — Internal server error

---

[API](https://skmtc.dev/nachonacho/apis/nachonacho-public-api.md) · [All operations](https://skmtc.dev/nachonacho/apis/nachonacho-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nachonacho/nachonacho-public-api/revisions/0c3733b7fab0/schema)