> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zafapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payment

> Create a new payment



## OpenAPI

````yaml /api-reference/openapi.en.json post /v1/payments
openapi: 3.1.0
info:
  title: ZAFA PAY API
  description: Payment API platform integrating multiple PSPs
  version: 1.0.0
servers:
  - url: https://api.sandbox.zafapay.com
    description: Sandbox environment
  - url: https://api.zafapay.com
    description: Production environment
security:
  - bearerAuth: []
paths:
  /v1/payments:
    post:
      tags:
        - Payments
      summary: Create Payment
      description: Create a new payment
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: >-
            Request validation error OR payment failed. Validation errors return
            `ErrorResponse` format. Payment failures (card declined,
            insufficient funds, etc.) return `PaymentFailedResponse` with a
            unified `PaymentError` object.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PaymentFailedResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Merchant not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Flow or configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreatePaymentRequest:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          description: Payment amount (positive number, supports up to 2 decimal places)
          example: 17.62
        currency:
          type: string
          description: 3-letter currency code (e.g., usd, sgd, jpy)
          example: usd
        capture_method:
          type: string
          enum:
            - automatic
            - manual
          description: Capture method (uses flow configuration if omitted)
        external_id:
          type: string
          description: Merchant's order ID
          example: order_12345
        flow_id:
          type: string
          description: Flow ID to use (defaults to default flow if omitted)
          example: flow_abc123
        payment_method:
          oneOf:
            - type: string
              description: Payment method (depot, card, etc.)
              example: card
            - type: object
              description: Payment method object
              properties:
                type:
                  type: string
                  description: Payment type
                  example: card
                token:
                  type: string
                  description: Payment provider's PaymentMethod token
                  example: pmi_xxx
          description: Payment method (string or object format)
        metadata:
          type: object
          description: Additional data to store with the transaction
          additionalProperties: true
        save_card:
          type: boolean
          description: If true, save card for future recurring payments
          example: true
        payment_method_id:
          type: string
          description: >-
            Use a saved payment method for recurring payment (get from
            /v1/customers/{id}/payment-methods)
          example: pmi_abc123
        name:
          type: string
          description: Cardholder name (required for some payment methods)
          example: John Doe
        customer_id:
          type: string
          description: Customer ID (used for saving and retrieving payment methods)
          example: cust_abc123
        email:
          type: string
          description: Customer email address
          example: customer@example.com
        tel:
          type: string
          description: Customer phone number
          example: +81-90-1234-5678
        token:
          type: string
          description: >-
            Token ID from the JavaScript SDK (`tok_` prefix). Used for
            server-to-server payments. The token is single-use and expires after
            30 minutes.
          example: tok_xxxxxxxxxxxxxxxxxxxxxx
        return_url:
          type: string
          description: >-
            URL to redirect the customer after 3D Secure authentication.
            Strongly recommended when using `token` parameter — without it, the
            customer has no redirect destination after 3DS.
          example: https://your-site.com/payment-complete
        success_url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            URL to redirect the customer to after a successful payment. Set per
            payment, it overrides the payment link URL and the merchant default
            configured in the dashboard. Must be an http(s) URL.
          example: https://your-site.com/orders/12345/thanks
        failure_url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            URL to redirect the customer to after a failed payment. Overrides
            the payment link URL and the merchant default. Must be an http(s)
            URL.
          example: https://your-site.com/orders/12345/failed
        cancel_url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            URL to redirect the customer to when the payment is cancelled.
            Overrides the payment link URL and the merchant default. Must be an
            http(s) URL.
          example: https://your-site.com/orders/12345/cancelled
    PaymentResponse:
      type: object
      properties:
        id:
          type: string
          description: Payment request ID
          example: req_abc123
        status:
          type: string
          description: Status
          example: pending
        amount:
          type: number
          description: Payment amount
          example: 17.62
        currency:
          type: string
          description: Currency code
          example: usd
        external_id:
          type: string
          nullable: true
          description: Merchant's order ID
          example: order_12345
        metadata:
          type: object
          description: Additional data (empty object if not specified)
          additionalProperties: true
          example: {}
        flow_id:
          type: string
          description: Payment flow ID used
          example: flow_default
        payment_type:
          type: string
          enum:
            - single
            - initial
            - recurring
            - token
          description: >-
            Payment type. `single`: Regular one-time payment, `initial`: Initial
            payment with card saving, `recurring`: Recurring payment using saved
            card, `token`: Server-to-server payment using token
          example: single
        payment_url:
          type: string
          description: >-
            Hosted checkout page URL (with signature). Returned for hosted
            checkout payments.
          example: https://pay.sandbox.zafapay.com/checkout/req_abc123?token=xxxxxxxx
        redirect_url:
          type: string
          description: >-
            3D Secure authentication URL. Returned when `status` is
            `requires_action` (token payments only).
          example: https://pay.sandbox.zafapay.com/3ds/req_abc123?token=xxxxxxxx
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601 format)
          example: '2025-01-01T00:00:00.000Z'
    PaymentFailedResponse:
      type: object
      description: >-
        Response body for a failed payment (HTTP 400). Contains a unified
        PaymentError object describing why the payment failed.
      required:
        - status
        - error
      properties:
        id:
          type: string
          description: Payment request ID
          example: req_abc123
        transaction_id:
          type: string
          description: Transaction ID
          example: tx_xyz789
        status:
          type: string
          enum:
            - failed
          example: failed
        payment_type:
          type: string
          enum:
            - token
            - recurring
            - hosted
          example: token
        error:
          $ref: '#/components/schemas/PaymentError'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type
              enum:
                - authentication_error
                - authorization_error
                - invalid_request_error
                - payment_error
                - rate_limit_error
                - api_error
              example: invalid_request_error
            code:
              type: string
              description: Error code
              example: validation_error
            message:
              type: string
              description: Error message
              example: Invalid request parameters
            param:
              type: string
              description: Parameter that caused the error
              example: amount
            details:
              type: array
              description: Validation error details
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
            request_id:
              type: string
              description: Request ID
              example: req_abc123xyz789
    PaymentError:
      type: object
      description: >-
        Unified payment error structure. Returned in failed payment API
        responses and payment.failed merchant webhooks.
      required:
        - code
        - category
        - message
        - recommended_action
      properties:
        code:
          type: string
          description: >-
            Unified error code (e.g., card_declined, insufficient_funds,
            expired_card). See Error Codes reference for the full list.
          example: card_declined
        category:
          type: string
          description: >-
            Error category for processing decisions. `validation` errors do not
            trigger merchant webhooks (visible only in 400 API response).
          enum:
            - authentication
            - soft_decline
            - hard_decline
            - gateway_error
            - validation
          example: soft_decline
        message:
          type: string
          description: Human-readable error message (suitable for display to end-users)
          example: Your card was declined
        recommended_action:
          type: string
          description: >-
            Recommended action the merchant should take in response to this
            error
          enum:
            - retry
            - contact_customer
            - use_different_card
            - none
          example: use_different_card
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication using access token

````