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

# Process Transaction

> Process both payments and withdrawals through a single API call. This unified endpoint 
handles all transaction types based on the `operation_type` field.


<Warning>
  The Authorization needs to be in the following format:

  `Authorization: Token <YOUR_API_KEY>`
</Warning>

Process both payments and withdrawals through a single API call. This unified endpoint handles all transaction types based on the `operation_type` field.

## Additional Information

This endpoint supports multiple payment methods including:

* **Card Payments**: Credit and debit cards with optional 3D Secure
* **SPEI**: Mexican bank transfers (24/7 availability)
* **OXXO Pay**: Cash payments at OXXO convenience stores
* **Mercado Pago**: Digital wallet payments
* **SafetyPay**: Cash payments at participating locations

For detailed information about each payment method, see the [Payment Methods Overview](/direct-integration/payment-methods/payment-methods-overview).


## OpenAPI

````yaml POST /process/
openapi: 3.0.3
info:
  title: Tonder
  description: Tonder API
  termsOfService: https://www.google.com/policies/terms/
  contact:
    email: hello@tonder.io
  version: v1
servers:
  - url: https://api-stage.tonder.io/api/v1
    description: Staging
  - url: https://api.tonder.io/api/v1
    description: Production
security: []
paths:
  /process/:
    post:
      tags:
        - Direct Integration
      summary: Process Transaction
      description: >
        Process both payments and withdrawals through a single API call. This
        unified endpoint 

        handles all transaction types based on the `operation_type` field.
      operationId: processTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectTransactionRequest'
            examples:
              card_payment:
                summary: Card Payment
                value:
                  operation_type: payment
                  amount: 150
                  currency: MXN
                  customer:
                    name: Ana María Rodríguez
                    email: ana.rodriguez@email.com
                  payment_method:
                    type: CARD
                    card_number: 9230-0892-4469-1474
                    cardholder_name: c05d89b2-299c-4f93-b49a-42be00d3b64b
                    cvv: d31f0da3-0ed3-4ad8-8b68-14c2669a99a7
                    expiration_month: e401a32e-4174-424f-9688-727005f6a80e
                    expiration_year: bd9ccc23-3d00-4109-9626-fc6581389063
                  client_reference: order-789
                  return_url: https://mystore.com/payment/return
              spei_payment:
                summary: SPEI Payment
                value:
                  operation_type: payment
                  amount: 500
                  currency: MXN
                  customer:
                    name: Carlos Eduardo López
                    email: carlos.lopez@empresa.mx
                  payment_method:
                    type: SPEI
                  client_reference: invoice-456
              withdrawal:
                summary: SPEI Withdrawal
                value:
                  operation_type: withdrawal
                  amount: 750
                  currency: MXN
                  reference: payout-001
                  transfer_method: SPEI
                  description: Commission payment
                  beneficiary:
                    account: '012345678901234567'
                    name: Roberto Martínez García
                    rfc: MAGR850920XY1
                    institution: '40012'
                    email: roberto.martinez@email.com
      responses:
        '200':
          description: Transaction processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectTransactionResponse'
        '201':
          description: Transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectTransactionResponse'
        '202':
          description: Transaction accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectTransactionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
        '429':
          description: Rate Limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectErrorResponse'
components:
  schemas:
    DirectTransactionRequest:
      type: object
      required:
        - operation_type
        - amount
        - customer
      properties:
        operation_type:
          type: string
          enum:
            - payment
            - withdrawal
          description: Type of transaction to process
        amount:
          type: number
          format: decimal
          minimum: 0.01
          maximum: 15000000
          multipleOf: 0.01
          description: Transaction amount
        currency:
          type: string
          default: MXN
          enum:
            - MXN
            - USD
          description: Currency code
        customer:
          $ref: '#/components/schemas/DirectCustomer'
        client_reference:
          type: string
          maxLength: 255
          description: Your reference identifier
        metadata:
          type: object
          additionalProperties: true
          description: Additional data for your records
        return_url:
          type: string
          format: uri
          description: URL for redirection after 3DS processing
        payment_method:
          $ref: '#/components/schemas/DirectPaymentMethod'
        transfer_method:
          type: string
          enum:
            - SPEI
            - DEBIT_CARD
          description: Transfer method for withdrawals
        reference:
          type: string
          description: Your withdrawal reference
        description:
          type: string
          maxLength: 500
          description: Withdrawal description
        beneficiary:
          $ref: '#/components/schemas/DirectBeneficiary'
    DirectTransactionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique transaction identifier
        operation_type:
          type: string
          enum:
            - payment
            - withdrawal
          description: Type of transaction
        status:
          type: string
          enum:
            - pending
            - on_hold
            - processing
            - sent_to_provider
            - success
            - paid_full
            - in_transit
            - authorized
            - canceled
            - declined
            - rejected
            - failed
            - Unknown
            - expired
          description: Current transaction status
        amount:
          type: number
          format: decimal
          description: Transaction amount
        currency:
          type: string
          description: Currency code
        client_reference:
          type: string
          description: Your reference identifier
        payment_id:
          type: integer
          description: Payment ID (for payments)
        transaction_id:
          type: string
          description: Provider transaction ID
        provider:
          type: string
          description: Payment provider used
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of creation
        status_code:
          type: integer
          description: HTTP status code
        next_action:
          $ref: '#/components/schemas/DirectNextAction'
        payment_instructions:
          $ref: '#/components/schemas/DirectPaymentInstructions'
    DirectErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - type
          properties:
            code:
              type: string
              description: A specific, machine-readable code for the error
            message:
              type: string
              description: A human-readable message explaining the error
            type:
              type: string
              enum:
                - request_error
                - auth_error
                - validation_error
                - server_error
              description: The category of the error
            details:
              type: object
              additionalProperties: true
              description: Additional context about the error
        request_id:
          type: string
          description: A unique identifier for the request
    DirectCustomer:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          maxLength: 255
          description: Customer full name
        email:
          type: string
          format: email
          maxLength: 320
          description: Customer email address
    DirectPaymentMethod:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - CARD
            - SPEI
            - OXXO
            - mercadopago
            - SAFETYPAY
          description: Payment method type
        token:
          type: string
          description: Tokenized card ID (for card payments)
        card_number:
          type: string
          description: Card number (if not using token)
        cardholder_name:
          type: string
          description: Cardholder name (for raw card data)
        cvv:
          type: string
          description: Security code (for raw card data)
        expiration_month:
          type: string
          description: Expiration month (for raw card data)
        expiration_year:
          type: string
          description: Expiration year (for raw card data)
    DirectBeneficiary:
      type: object
      required:
        - account
        - name
        - rfc
        - institution
        - email
      properties:
        account:
          type: string
          pattern: ^[0-9]{18}$
          description: Account number or CLABE (18 digits)
        name:
          type: string
          description: Beneficiary full name
        rfc:
          type: string
          pattern: ^[A-Z&Ñ]{3,4}\\d{6}[A-Z\\d]{3}$
          description: Mexican tax ID (RFC)
        institution:
          type: string
          description: Bank institution code
        email:
          type: string
          format: email
          description: Beneficiary email
    DirectNextAction:
      type: object
      properties:
        redirect_to_url:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: URL to redirect customer for 3DS authentication
            return_url:
              type: string
              format: uri
              description: URL to return after 3DS completion
            verify_transaction_status_url:
              type: string
              description: URL to check transaction status after 3DS
    DirectPaymentInstructions:
      type: object
      properties:
        reference:
          type: string
          description: Payment reference code
        account_number:
          type: string
          description: Account number for transfer
        bank_name:
          type: string
          description: Bank name
        amount:
          type: number
          format: decimal
          description: Amount to pay
        expires_at:
          type: string
          format: date-time
          description: Payment expiration time
        reference_code:
          type: string
          description: Reference code for cash payments
        barcode:
          type: string
          description: Barcode for cash payments
        store_name:
          type: string
          description: Store name for cash payments
        expiration_date:
          type: string
          format: date-time
          description: Payment expiration date
        instructions:
          type: array
          items:
            type: string
          description: Payment instructions
        voucher_pdf:
          type: string
          format: uri
          description: URL to payment voucher PDF

````