README

A Magento 2 GraphQL extension that provides enhanced checkout functionality with token-based authorization for secure access to customer, order, and payment data.

Overview

The Tapbuy CheckoutGraphql module extends Magento 2's native GraphQL API with additional resolvers and functionality specifically designed for checkout processes. It includes robust token-based authorization to ensure secure access to sensitive data.

Features

GraphQL Queries

Customer Search: Search for customers by email address
Order Retrieval: Get order details by order number (including guest orders)
Enhanced Customer Data: Additional customer fields with custom resolvers

GraphQL Mutations

Order Assignment: Assign a previously guest order to an existing customer account
Cart Unlock: Reactivate a locked cart and reset its associated order status
Cart Deactivation: Disable an active cart to prevent further checkout actions

GraphQL Types

Customer Extensions: Additional customer fields like tapbuy_customer_id
Order Extensions: Enhanced order data including custom shipping assignments and state information
Payment Method Extensions: Detailed payment information including additional data
Address Extensions: Extended address information with entity IDs

Security

Token-based Authorization: Secure API access using OAuth tokens
Integration Permissions: Granular permission checking based on integration settings
Resource-based Access Control: Different permission levels for different operations

Installation

Copy the module to your Magento installation:

cp -r Tapbuy/CheckoutGraphql app/code/Tapbuy/

Enable the module:

php bin/magento module:enable Tapbuy_CheckoutGraphql

Run setup upgrade:
```
php bin/magento setup:upgrade
```
Compile DI:
```
php bin/magento setup:di:compile
```
Clear cache:
```
php bin/magento cache:flush
```

Configuration

Token Authorization Setup

Create Integration: Go to System → Extensions → Integrations in Magento Admin
Configure Permissions: Assign appropriate permissions:
- Magento_Customer::customer - For customer operations
- Magento_Sales::actions_view - For order operations
Generate Tokens: Activate the integration to generate access tokens

Required Permissions

The module requires the following ACL resources:

Magento_Customer::customer - Customer data access
Magento_Sales::actions_view - Order data access
Magento_Backend::admin or Magento_Backend::all - Full admin access (alternative)

Usage

Authentication

All GraphQL queries require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

GraphQL Queries

Search Customer by Email

query {
  tapbuyCustomerSearch(email: "customer@example.com") {
    id
    email
    firstname
    lastname
    tapbuy_customer_id
  }
}

Get Order by Number

query {
  tapbuyGetOrder(order_number: "000000123") {
    id
    number
    status
    tapbuy_state
    tapbuy_items {
      id
      product_name
      quantity_ordered
    }
    tapbuy_shipping_assignments {
      method
      items {
        item_id
        product_id
      }
      address {
        tapbuy_entity_id
      }
    }
    payment_methods {
      name
      type
      tapbuy_additional_information {
        guest_email
        cc_type
        method_title
        _3d_active
        result_code
        psp_reference
        additional_data {
          issuer_country
          card_bin
          card_holder_name
          card_summary
          payment_method
        }
      }
      tapbuy_amount_ordered
    }
  }
}

Takes order_number or order_id

GraphQL Mutations

Assign Guest Order to Customer

mutation {
  tapbuyOrderAssignCustomer(order_id: "000000123", customer_id: 42, order_identifier_type: "increment_id") {
    success
    order {
      id
      number
      customer_email
      tapbuy_state
    }
  }
}

order_id accepts either the order entity ID or its increment ID. Use order_identifier_type (auto, entity_id, or increment_id) to disambiguate when necessary. The order email must match the customer's email address before assignment.

Unlock Cart

mutation {
  tapbuyUnlockCart(cart_id: "ajed83Hs", unlock_reason: "cancel") {
    cart {
      id
      is_active
    }
  }
}

Supply either a masked or numeric cart ID; unlock_reason is optional and impacts the resulting order status.

Deactivate Cart

mutation {
  tapbuyDeactivateCart(cart_id: "ajed83Hs") {
    cart {
      id
      is_active
    }
  }
}

Payment Method Integration

The module includes a plugin for SetPaymentMethodOnCart that handles additional Tapbuy payment information:

mutation {
  setPaymentMethodOnCart(input: {
    cart_id: "CART_ID"
    payment_method: {
      code: "tapbuy_payment"
      tapbuy_additional_information: {
        accept_url: "https://example.com/success"
        pending_url: "https://example.com/pending"
        cancel_url: "https://example.com/cancel"
        exception_url: "https://example.com/error"
      }
    }
  }) {
    cart {
      selected_payment_method {
        code
      }
    }
  }
}

Architecture

Authorization Flow

Token Extraction: Extract Bearer token from Authorization header
Token Validation: Validate token against Magento's OAuth system
Integration Check: Verify integration status and permissions
Resource Authorization: Check specific ACL resource permissions
Data Access: Allow or deny access based on authorization results

File Structure

Tapbuy/CheckoutGraphql/
├── composer.json
├── registration.php
├── etc/
│   ├── di.xml                       # Dependency injection configuration
│   ├── module.xml                   # Module declaration
│   └── schema.graphqls              # GraphQL schema definitions
├── Model/
│   ├── Authorization/
│   │   └── TokenAuthorization.php   # Token-based authorization logic
│   ├── Resolver/
│   │   ├── Customer.php             # Customer field resolver
│   │   ├── CustomerSearch.php       # Customer search resolver
│   │   ├── GetOrder.php             # Order retrieval resolver
│   │   ├── GetOrderItems.php        # Order items resolver
│   │   ├── OrderAssignCustomer.php  # Guest order assignment resolver
│   │   ├── OrderAddress.php         # Order address resolver
│   │   └── OrderPaymentMethod.php   # Payment method resolver
│   ├── OrderDataFormatter.php       # Shared formatter for enhanced order payloads
│   └── OrderLocator.php             # Helper to locate orders by ID or increment ID
└── Plugin/
    └── SetPaymentMethodOnCartPlugin.php  # Payment method plugin

Error Handling

The module provides comprehensive error handling:

Authorization Errors: Clear messages for token and permission issues
Validation Errors: Input validation with descriptive error messages
Not Found Errors: Appropriate responses for missing entities
Logging: Error logging for debugging purposes

Security Considerations

Token Validation: All requests validate OAuth tokens
Permission Checking: Granular ACL resource checking
Input Sanitization: Proper validation of all input parameters
Error Disclosure: Minimal error information disclosure

Development

Adding New Resolvers

Create resolver class in Model/Resolver/
Implement ResolverInterface
Add authorization check using TokenAuthorization
Register in etc/di.xml
Define schema in etc/schema.graphqls

Extending Authorization

The TokenAuthorization class can be extended to support additional authorization mechanisms or custom permission logic.

Troubleshooting

Common Issues

"Token is required" Error
- Ensure Authorization header is present
- Verify Bearer token format
"Invalid token" Error
- Check token validity in Magento Admin
- Regenerate integration tokens if needed
"You do not have permission" Error
- Verify integration permissions
- Check ACL resource assignments
"Order not found" Error
- Verify order number exists

Development

Running Tests

Tests run inside a Docker container that replicates the CI environment (PHP 8.3, Magento 2.4.7-p5). Docker must be running.

Prerequisites: clone the following sibling repository next to this one:

# From the parent directory
git clone git@github.com:tapbuy/magento-redirect-plugin.git redirect-tracking

First-time setup:

cp auth.json.dist auth.json
# Fill in your repo.magento.com public/private keys in auth.json

Run all unit tests:

make test

On the first run, the Docker image is built and Magento is installed into a named volume (tapbuy-magento-2.4.7-p5-php83). Subsequent runs reuse the cached volume and are fast.

Do not use composer test — it runs PHPUnit without the Magento bootstrap and will fail or produce misleading results.

Linting

Linting runs PHPMD and PHPCS (Magento2 standard) inside the same Docker container as tests. Docker must be running.

Run both linters:

make lint

Run individually:

make phpmd   # PHP Mess Detector
make phpcs   # PHP CodeSniffer (Magento2 standard)

Both linters always run when using make lint; if either fails, the command exits with a non-zero code.

Check order visibility settings

tapbuy / checkout-graphql

Package info

Security

Statistics

README

Overview

Features

GraphQL Queries

GraphQL Mutations

GraphQL Types

Security

Installation

Configuration

Token Authorization Setup

Required Permissions

Usage

Authentication

GraphQL Queries

Search Customer by Email

Get Order by Number

GraphQL Mutations

Assign Guest Order to Customer

Unlock Cart

Deactivate Cart

Payment Method Integration

Architecture

Authorization Flow

File Structure

Error Handling

Security Considerations

Development

Adding New Resolvers

Extending Authorization

Troubleshooting

Common Issues

Development

Running Tests

Linting