> ## Documentation Index > Fetch the complete documentation index at: https://docs.monxa.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a Charge > Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL). ## OpenAPI ````yaml api-reference/openapi.json post /v1/charges openapi: 3.0.1 info: title: Monxa API description: '' version: 1.0.0 servers: [] security: - Bearer: [] tags: - name: balances - name: customers - name: merchants - name: charges - name: payouts paths: /v1/charges: post: tags: - charges summary: Create a Charge description: >- Create a new charge. An idempotency key is required in the request header to ensure safe retries without creating duplicate charges. This endpoint initializes a payment attempt for the specified amount and channel, returning a charge object that represents the transaction status and payment instructions (e.g., QR string or redirect URL). parameters: - name: x-idempotency-key in: header description: '' required: false example: 0XGGG99RP0D90 schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCharge' example: amount: 5300 currency: IDR channel_code: qr_qris reference_id: merchant_26 description: >- Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer. metadata: qui6: culpa elit cillum9b: amet in dolore dolor74: deserunt reprehenderit magna do responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier of the charge code: type: string description: >- nique charge code generated by Monxa for tracking or reconciliation. (e.g. chg_2510BBFC2A3A6CE22F1B). reference_id: type: string description: >- Merchant-provided identifier such as invoice or order number. merchant_id: type: string description: Unique ID of the merchant who created the charge. amount: type: integer description: Charge amount in minor units (e.g., 3500 = IDR 35.00). currency: type: string description: ISO 4217 currency code (e.g., IDR, MYR, SGD). channel_code: type: string description: >- The selected payment channel (e.g., qr_qris, bank_redirect_fpx, wallet_dana). action_flow: type: string description: >- Defines how the charge is presented — e.g., payload, redirection, or embedded. status: type: string description: Current charge status (PENDING, SUCCEEDED, FAILED, etc.). description: type: string description: Merchant’s description of the charge or transaction. metadata: type: object properties: {} description: >- Custom key–value pairs provided in the request for additional context. action: type: object properties: qr_image_url: type: string description: URL to a hosted QR image to be displayed for payment. qr_payload: type: string description: >- The QR string payload used for QR-based payment apps (e.g., QRIS). simulation_url: type: string description: >- Sandbox/testing link to simulate the payment flow (only returned in sandbox environment). type: type: string description: >- Instruction type for client handling. For example, PRESENT_TO_CUSTOMER indicates the merchant should display or redirect the user to complete payment. required: - qr_image_url - qr_payload - simulation_url - type description: >- Contains payment instructions or URLs to be presented to the customer. embedded_url: type: string created_by: type: string description: Identifier of the user or API key that created the charge. created_on: type: string description: Timestamp when the charge was created. updated_by: type: string description: >- Identifier of the user or process that last updated the charge. updated_on: type: string description: Timestamp of the last update to this charge. required: - action - metadata - action_flow - amount - channel_code - code - currency - description - merchant_id - reference_id - status - created_by - created_on - updated_by - updated_on - id - embedded_url examples: '1': summary: Success value: action: embedded_url: >- https://checkout.monxa.dev/payments/019a058a-0a86-7c35-969e-f883a56f1e10 simulation_url: >- https://checkout.monxa.dev/payments/simulation/019a058a-0a86-7c35-969e-f883a56f1e10 type: PRESENT_TO_CUSTOMER meta_data: qui6: culpa elit cillum9b: amet in dolore dolor74: deserunt reprehenderit magna do action_flow: EMBEDDED amount: 4300 channel_code: QR_QRIS code: CHG_2510969EF883A56F1E10 currency: IDR description: >- Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer. merchant_id: 019a0423-2941-735f-9a93-819df469ad39 reference_id: merchant_26 status: PENDING created_by: drunk@sandbox.dev created_on: '2025-10-21T06:52:04.1021719+00:00' updated_by: drunk@sandbox.dev updated_on: '2025-10-21T06:52:04.365363+00:00' id: 019a058a-0a86-7c35-969e-f883a56f1e10 '3': summary: Success value: action: checkout_url: >- https://checkout.monxa.dev/payments/019a0625-3a69-7279-99a4-50ac66afa159 embedded_url: >- https://checkout.monxa.dev/payments/019a0625-3a69-7279-99a4-50ac66afa159 qr_image_url: >- https://checkout.monxa.dev/api/payments/qr/019a0625-3a69-7279-99a4-50ac66afa159 qr_payload: >- 000THIS IS A DUMMY QR00012345000GO TO SIMULATE PAGE ON DASHBOARD TO COMPLETE PAYMENT00012345000COM.PROVIDER.WWW00012345000ID.CO.QRIS.WWW000123000THIS IS A DUMMY QR00012345000GO TO SIMULATE PAGE ON DASHBOARD TO COMPLETE PAYMENT00012345.0001234ID1234Durianpay1234KOTA JAKARTA12345000 type: PRESENT_TO_CUSTOMER metadata: qui6: culpa elit cillum9b: amet in dolore dolor74: deserunt reprehenderit magna do amount: 5300 channel_code: QR_QRIS code: CHG_251099A450AC66AFA159 currency: IDR description: >- Viridis cogo aureus. Tollo eum antepono administratio cupressus dolore uredo. Amissio decet vir subvenio asperiores. Degusto vesper aer. merchant_id: 019a0423-2941-735f-9a93-819df469ad39 reference_id: merchant_26 status: PENDING created_by: drunk@sandbox.dev created_on: '2025-10-21T09:41:34.4412661+00:00' updated_by: drunk@sandbox.dev updated_on: '2025-10-21T09:41:35.1766779+00:00' id: 019a0625-3a69-7279-99a4-50ac66afa159 headers: {} '409': description: '' content: application/json: schema: type: object properties: type: type: string description: >- A URI reference that identifies the error type, following RFC 9110. Usually points to a documentation reference for this error class. title: type: string description: >- A short, human-readable summary of the error (e.g., "Bad Request"). status: type: integer description: >- The HTTP status code associated with this error (e.g., 400, 401, 404, 500). detail: type: string description: >- A detailed explanation of what caused the error, typically describing the missing or invalid field. instance: type: string description: >- The specific API endpoint or operation where the error occurred. traceId: type: string description: >- A unique identifier for the request trace, used for internal debugging and log correlation. trace-id: type: string description: >- An alternative field name used by some systems for backward compatibility with tracing tools. required: - type - title - status - detail - instance - traceId - trace-id example: type: https://tools.ietf.org/html/rfc9110#section-15.5.1 title: Bad Request status: 400 detail: x-idempotency-key header is required. instance: POST /v1/charges traceId: 00-4ea955e3444de0f268b5b8cb03d3a4f9-5e01236bea69f1b9-00 trace-id: 0HNGG99RP0D72:00000001 headers: {} deprecated: false security: - Bearer: [] components: schemas: CreateCharge: required: - amount - currency - channel_code - action_flow type: object properties: amount: type: number description: >- The amount to be charged, expressed in minor units (e.g., 10000 = 100.00). format: double currency: type: string description: The three-letter ISO 4217 currency code (e.g., IDR, MYR, SGD). channel_code: $ref: '#/components/schemas/ChannelCodes' description: >- The payment channel to be used, such as qr_qris, bank_redirect_fpx, wallet_dana, etc. action_flow: $ref: '#/components/schemas/ActionFlows' description: >- The type of payment flow, e.g.redirect, or show. Determines how Merchant presents the payment experience to the user. reference_id: type: string description: >- Merchant’s unique reference ID for this charge (e.g., order number or invoice ID). Used for reconciliation and idempotency tracking. nullable: true description: type: string description: >- Optional short text describing the purpose of the payment or charge. Useful for invoices or customer-facing receipts. nullable: true metadata: type: object additionalProperties: type: string description: Optional custom key–value pairs for additional information properties: {} nullable: true ChannelCodes: type: string enum: - qr_qris ActionFlows: type: string enum: - payload - redirection - embedded securitySchemes: Bearer: type: http scheme: bearer ````