> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesive.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a charge > Ask the merchant for a one-time payment. Requires the WRITE_CHARGES scope. Creates a charge and returns a `confirmationUrl`. Redirect the merchant there. Nothing is charged until the store owner approves it. See [Payments](https://docs.salesive.com/apps/payments.md) for the whole flow. ## OpenAPI ````yaml apps-api/specs/billing.json POST /app-billing/charges openapi: 3.1.0 info: title: 'Salesive Apps API: Billing' version: 1.0.0 description: >- Charge the merchant a store is installed for, once or on a schedule. Every endpoint authenticates with an installed-app access token (prefix `app_`). Creating a charge or subscription never moves money: the store owner approves it in the dashboard first. Salesive keeps 5% of every payment and credits the rest to your payout store's wallet. servers: - url: https://api.salesive.com/api/v1 description: Production security: - AppToken: [] paths: /app-billing/charges: post: tags: - Charges summary: Create a charge description: >- Asks the merchant for a one-time payment. Nothing is charged yet: send the merchant to `confirmationUrl`, where the store owner approves it and pays from a wallet or by card. You find out through the `charges/paid` webhook or by reading the charge. A request that is not approved within 48 hours expires. Requires `WRITE_CHARGES`. Authenticate with `Authorization: Bearer app_`. The store is bound to the token server-side, never send a shop id. operationId: createCharge requestBody: required: true content: application/json: schema: type: object required: - name - amount - currency properties: name: type: string maxLength: 120 description: What the merchant sees, for example `Pro plan`. description: type: string maxLength: 500 amount: type: number description: >- Price in `currency`, two decimals at most. USD 1 to 1000, NGN 500 to 1,500,000. currency: type: string enum: - USD - NGN returnUrl: type: string description: >- Where the merchant goes after approving or declining. Must be on your app URL's origin or one of your redirect URIs. idempotencyKey: type: string maxLength: 120 description: >- Send the same key on a retry and you get the same charge back with `200` instead of a duplicate. metadata: type: object description: Up to 20 keys and 2 KB. Returned on every read. example: name: Extra seats description: 5 additional seats amount: 15 currency: USD returnUrl: https://myapp.example.com/billing/done idempotencyKey: order-A-1042 metadata: orderRef: A-1042 responses: '200': description: >- A charge with this `idempotencyKey` already existed and is returned unchanged. content: application/json: schema: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object properties: data: $ref: '#/components/schemas/Charge' example: status: 200 success: true message: Charge already exists data: id: 66d1f0a3c2d4e5f6a7b8c9d0 reference: apc_3f9a1c52d7e84b60 status: pending name: Extra seats description: 5 additional seats amount: 15 currency: USD platformFee: 0.75 netAmount: 14.25 subscriptionId: null periodStart: null periodEnd: null test: false metadata: orderRef: A-1042 returnUrl: https://myapp.example.com/billing/done confirmationUrl: >- https://app.salesive.com/apps/billing/approve/apc_3f9a1c52d7e84b60 failureReason: null expiresAt: '2026-10-27T10:30:00.000Z' paidAt: null createdAt: '2026-10-25T10:30:00.000Z' '201': description: The charge was created. content: application/json: schema: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object properties: data: $ref: '#/components/schemas/Charge' example: status: 201 success: true message: Charge created data: id: 66d1f0a3c2d4e5f6a7b8c9d0 reference: apc_3f9a1c52d7e84b60 status: pending name: Extra seats description: 5 additional seats amount: 15 currency: USD platformFee: 0.75 netAmount: 14.25 subscriptionId: null periodStart: null periodEnd: null test: false metadata: orderRef: A-1042 returnUrl: https://myapp.example.com/billing/done confirmationUrl: >- https://app.salesive.com/apps/billing/approve/apc_3f9a1c52d7e84b60 failureReason: null expiresAt: '2026-10-27T10:30:00.000Z' paidAt: null createdAt: '2026-10-25T10:30:00.000Z' '400': description: >- Invalid body, amount out of range, unsupported currency, or a `returnUrl` on another origin. content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 400 success: false message: amount must be between 1 and 1000 USD data: null '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Missing scope, the app is not live, it has no payout store (`NO_PAYOUT_STORE`), or charging is not enabled for it yet (`BILLING_NOT_ENABLED`). content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 403 success: false message: >- This app has no payout store. The developer must choose one in the Developer console. data: code: NO_PAYOUT_STORE '429': description: >- Too many requests are waiting for the merchant (50 per installation). content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 429 success: false message: >- Too many requests are waiting for the merchant. Wait for them to be approved or expire. data: null components: schemas: EnvelopeBase: type: object description: >- Standard Salesive response envelope. The operation-specific payload is carried in `data`. required: - status - success - message properties: status: type: integer description: HTTP status code, echoed in the body. success: type: boolean description: Whether the request succeeded. message: type: string description: Human-readable result message. Charge: type: object description: >- A payment your app asked the merchant for. A subscription's payments are charges too, with `subscriptionId` set. properties: id: type: string reference: type: string description: Starts with `apc_`. status: type: string enum: - pending - processing - paid - declined - expired - failed description: >- `pending` waits for the merchant. `paid` is final and means your payout store was credited (or, for a test charge, that no money was needed). name: type: string description: type: - string - 'null' amount: type: number description: The price you set, in `currency`. currency: type: string enum: - USD - NGN platformFee: type: number description: Salesive's 5%, in `currency`. netAmount: type: number description: >- What your payout store receives, in `currency`, before conversion to its wallet currency. subscriptionId: type: - string - 'null' periodStart: type: - string - 'null' format: date-time periodEnd: type: - string - 'null' format: date-time test: type: boolean description: True on a development install. No money moves. metadata: type: - object - 'null' description: Whatever you sent, returned unchanged. returnUrl: type: - string - 'null' confirmationUrl: type: - string - 'null' description: Send the merchant here to approve. Present only while `pending`. failureReason: type: - string - 'null' expiresAt: type: - string - 'null' format: date-time paidAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time Envelope: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object properties: data: description: Operation-specific payload (object, array, or null). responses: Unauthorized: description: Missing or invalid app access token. content: application/json: schema: $ref: '#/components/schemas/Envelope' example: status: 401 success: false message: Authentication required data: null securitySchemes: AppToken: type: http scheme: bearer description: >- Installed-app access token (prefix app_), issued by the OAuth install flow. The store is bound to the token server-side, never send a shop id. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.