zai_payment 2.3.2 → 2.4.0

data/lib/zai_payment/resources/item.rb

@@ -25,6 +25,22 @@ module ZaiPayment
         tax_invoice: :tax_invoice
       }.freeze
 
+      ITEM_PAYMENT_ATTRIBUTES = {
+        account_id: :account_id,
+        device_id: :device_id,
+        ip_address: :ip_address,
+        cvv: :cvv,
+        merchant_phone: :merchant_phone
+      }.freeze
+
+      ITEM_ASYNC_PAYMENT_ATTRIBUTES = {
+        account_id: :account_id,
+        request_three_d_secure: :request_three_d_secure
+      }.freeze
+
+      # Valid values for request_three_d_secure parameter
+      REQUEST_THREE_D_SECURE_VALUES = %w[automatic challenge any].freeze
+
       def initialize(client: nil)
         @client = client || Client.new
       end
@@ -299,6 +315,197 @@ module ZaiPayment
         client.get("/items/#{item_id}/status")
       end
 
+      # Make a payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :account_id Required account ID
+      # @option attributes [String] :device_id Optional device ID
+      # @option attributes [String] :ip_address Optional IP address
+      # @option attributes [String] :cvv Optional CVV
+      # @option attributes [String] :merchant_phone Optional merchant phone number
+      # @return [Response] the API response containing payment details
+      #
+      # @example Make a payment with required parameters
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.make_payment("item_id", account_id: "account_id")
+      #   response.data # => {"items" => {"id" => "...", "amount" => "...", ...}}
+      #
+      # @example Make a payment with optional parameters
+      #   response = items.make_payment(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     device_id: "device_789",
+      #     ip_address: "192.168.1.1",
+      #     cvv: "123",
+      #     merchant_phone: "+1234567890"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/makepayment
+      def make_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = build_item_payment_body(attributes)
+
+        client.patch("/items/#{item_id}/make_payment", body: body)
+      end
+
+      # Cancel an item
+
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing cancellation details
+      #
+      # @example Cancel a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.cancel("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/cancelitem
+      def cancel(item_id)
+        validate_id!(item_id, 'item_id')
+        client.patch("/items/#{item_id}/cancel")
+      end
+
+      # Refund an item
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :refund_amount Optional refund amount
+      # @option attributes [String] :refund_message Optional refund message
+      # @option attributes [String] :account_id Optional account ID
+      # @return [Response] the API response containing refund details
+      #
+      # @example Refund an item
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.refund("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Refund an item with optional parameters
+      #   response = items.refund(
+      #     "item_id",
+      #     refund_amount: 10000,
+      #     refund_message: "Refund for product XYZ",
+      #     account_id: "account_789"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/refund
+      def refund(item_id, refund_amount: nil, refund_message: nil, account_id: nil)
+        validate_id!(item_id, 'item_id')
+
+        body = build_refund_body(
+          refund_amount: refund_amount,
+          refund_message: refund_message,
+          account_id: account_id
+        )
+
+        client.patch("/items/#{item_id}/refund", body: body)
+      end
+
+      # Authorize Payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :account_id Required account ID
+      # @option attributes [String] :cvv Optional CVV
+      # @option attributes [String] :merchant_phone Optional merchant phone number
+      # @return [Response] the API response containing authorization details
+      #
+      # @example Authorize a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.authorize_payment("item_id", account_id: "account_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Authorize a payment with optional parameters
+      #   response = items.authorize_payment(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     cvv: "123",
+      #     merchant_phone: "+1234567890"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/authorizepayment
+      def authorize_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        client.patch("/items/#{item_id}/authorize_payment", body: build_item_payment_body(attributes))
+      end
+
+      # Capture Payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :amount Optional amount to capture
+      # @return [Response] the API response containing capture details
+      #
+      # @example Capture a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.capture_payment("item_id", amount: 10000)
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Capture a payment with optional parameters
+      #   response = items.capture_payment(
+      #     "item_id",
+      #     amount: 10000
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/capturepayment
+      def capture_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = {}
+        body[:amount] = attributes[:amount] if attributes[:amount]
+
+        client.patch("/items/#{item_id}/capture_payment", body: body)
+      end
+
+      # Void Payment
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing void details
+      #
+      # @example Void a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.void_payment("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/voidpayment
+      def void_payment(item_id)
+        validate_id!(item_id, 'item_id')
+        client.patch("/items/#{item_id}/void_payment")
+      end
+
+      # Make an async Payment
+      #
+      # Initiate a card payment with 3D Secure 2.0 authentication support. This endpoint
+      # initiates the payment process and returns a payment_token required for 3DS2
+      # component initialisation.
+      #
+      # @param item_id [String] the item ID
+      # @param account_id [String] Account id of the bank account/credit card, etc making payment (not user id)
+      # @option attributes [String] :request_three_d_secure Customise the 3DS (3D Secure) preference for this payment.
+      #   Allowed values: 'automatic', 'challenge', 'any'. Defaults to 'automatic'.
+      #   - 'automatic': 3DS preference is determined automatically by the system
+      #   - 'challenge': Request a 3DS challenge is presented to the user
+      #   - 'any': Request a 3DS challenge regardless of the challenge flow
+      # @return [Response] the API response containing payment details with payment_token
+      #
+      # @example Make an async payment with required parameters
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.make_payment_async("item_id", account_id: "account_id")
+      #   response.data # => {"payment_id" => "...", "payment_token" => "...", "items" => {...}}
+      #
+      # @example Make an async payment with 3DS challenge
+      #   response = items.make_payment_async(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     request_three_d_secure: "challenge"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/makepaymentasync
+      def make_payment_async(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = build_async_payment_body(attributes)
+
+        client.patch("/items/#{item_id}/make_payment_async", body: body)
+      end
+
       private
 
       def validate_id!(value, field_name)
@@ -346,6 +553,28 @@ module ZaiPayment
         raise Errors::ValidationError, 'payment_type must be between 1 and 7'
       end
 
+      def validate_request_three_d_secure!(value)
+        return if REQUEST_THREE_D_SECURE_VALUES.include?(value.to_s)
+
+        raise Errors::ValidationError,
+              "request_three_d_secure must be one of: #{REQUEST_THREE_D_SECURE_VALUES.join(', ')}"
+      end
+
+      def build_item_payment_body(attributes)
+        validate_presence!(attributes[:account_id], 'account_id')
+
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = ITEM_PAYMENT_ATTRIBUTES[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+
       def build_item_body(attributes)
         body = {}
 
@@ -358,6 +587,34 @@ module ZaiPayment
 
         body
       end
+
+      def build_refund_body(refund_amount: nil, refund_message: nil, account_id: nil)
+        body = {}
+
+        body[:refund_amount] = refund_amount if refund_amount
+        body[:refund_message] = refund_message if refund_message
+        body[:account_id] = account_id if account_id
+
+        body
+      end
+
+      def build_async_payment_body(attributes)
+        validate_presence!(attributes[:account_id], 'account_id')
+
+        # Validate request_three_d_secure if provided
+        validate_request_three_d_secure!(attributes[:request_three_d_secure]) if attributes[:request_three_d_secure]
+
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = ITEM_ASYNC_PAYMENT_ATTRIBUTES[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
     end
   end
 end

data/lib/zai_payment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZaiPayment
-  VERSION = '2.3.2'
+  VERSION = '2.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 2.3.2
+  version: 2.4.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -99,7 +99,6 @@ files:
 - lib/zai_payment/version.rb
 - readme.md
 - sig/zai_payment.rbs
-- token_auth_implementation_summary.md
 homepage: https://github.com/Sentia/zai-payment
 licenses:
 - MIT

data/token_auth_implementation_summary.md

@@ -1,249 +0,0 @@
-# Token Auth API Implementation Summary
-
-## Overview
-
-Successfully implemented the **Generate Token** endpoint from the Zai API (https://developer.hellozai.com/reference/generatetoken) to enable secure bank and card account data collection.
-
-## What Was Implemented
-
-### 1. Core Resource Implementation
-
-**File:** `lib/zai_payment/resources/token_auth.rb`
-
-- Created `TokenAuth` resource class following the project's resource pattern
-- Implemented `generate(user_id:, token_type:)` method
-- Added token type validation (bank or card)
-- Added user ID validation
-- Support for case-insensitive token types
-- Default token type: 'bank'
-
-**Key Features:**
-```ruby
-# Generate a bank token (default)
-ZaiPayment.token_auths.generate(user_id: "seller-123")
-
-# Generate a card token
-ZaiPayment.token_auths.generate(user_id: "buyer-123", token_type: "card")
-```
-
-### 2. Module Integration
-
-**File:** `lib/zai_payment.rb`
-
-- Added `require_relative` for token_auth resource
-- Added `token_auths` accessor method
-- Configured to use `core_base` endpoint (https://test.api.promisepay.com)
-
-### 3. Test Suite
-
-**File:** `spec/zai_payment/resources/token_auth_spec.rb`
-
-- 15 comprehensive test cases covering:
-  - Bank token generation
-  - Card token generation
-  - Default token type behavior
-  - Validation errors (nil, empty, whitespace, invalid types)
-  - Case-insensitive token types
-  - Client initialization
-  - Constants verification
-- All tests passing with 95.22% line coverage
-- Follows project's testing pattern using Faraday test stubs
-- RuboCop compliant
-
-### 4. Documentation
-
-**File:** `examples/token_auths.md` (600+ lines)
-
-Comprehensive examples including:
-- Basic usage patterns
-- Bank token collection workflows
-- Card token collection workflows
-- Rails controller integration
-- Service object pattern
-- Frontend integration with PromisePay.js
-- Complete payment flow examples
-- Error handling strategies
-- Retry logic with exponential backoff
-- Security best practices:
-  - Token expiry management
-  - Audit logging
-  - Rate limiting protection
-
-**File:** `docs/token_auths.md` (500+ lines)
-
-Complete technical guide covering:
-- When to use Token Auth
-- How it works (flow diagram)
-- API methods reference
-- Token types (bank vs card) with use cases
-- Security considerations (PCI compliance, token lifecycle)
-- Integration guide (backend + frontend)
-- Error handling patterns
-- Best practices with code examples
-- Related resources and API references
-
-### 5. Version Updates
-
-**File:** `lib/zai_payment/version.rb`
-
-- Updated version from `2.0.2` to `2.1.0`
-- Follows semantic versioning (minor version bump for new feature)
-
-### 6. Changelog
-
-**File:** `changelog.md`
-
-Added comprehensive release notes for version 2.1.0:
-- Feature description
-- API methods
-- Documentation additions
-- Testing coverage
-- Link to full changelog
-
-### 7. README Updates
-
-**File:** `readme.md`
-
-- Added Token Auth to features list (🎫 emoji)
-- Added Token Auth section with quick examples
-- Updated roadmap (marked Token Auth as Done ✅)
-- Added documentation links in Examples & Patterns section
-
-### 8. Documentation Index
-
-**File:** `docs/readme.md`
-
-- Added token_auths.md to Architecture & Design section
-- Added Token Auth Examples to Examples section
-- Added Token Auth to Quick Links with guide, examples, and API reference
-- Updated documentation structure tree
-- Added tips for collecting payment data
-
-## API Endpoint
-
-**POST** `https://test.api.promisepay.com/token_auths`
-
-**Request Body:**
-```json
-{
-  "token_type": "bank",  // or "card"
-  "user_id": "seller-68611249"
-}
-```
-
-**Response:**
-```json
-{
-  "token_auth": {
-    "token": "tok_bank_abc123...",
-    "user_id": "seller-68611249",
-    "token_type": "bank",
-    "created_at": "2025-10-24T12:00:00Z",
-    "expires_at": "2025-10-24T13:00:00Z"
-  }
-}
-```
-
-## Usage Example
-
-```ruby
-# Configure the gem
-ZaiPayment.configure do |c|
-  c.environment   = :prelive
-  c.client_id     = ENV['ZAI_CLIENT_ID']
-  c.client_secret = ENV['ZAI_CLIENT_SECRET']
-  c.scope         = ENV['ZAI_OAUTH_SCOPE']
-end
-
-# Generate a card token for buyer
-response = ZaiPayment.token_auths.generate(
-  user_id: "buyer-12345",
-  token_type: "card"
-)
-
-token = response.data['token_auth']['token']
-# Send token to frontend for use with PromisePay.js
-```
-
-## Integration with PromisePay.js
-
-```javascript
-// Frontend (JavaScript)
-PromisePay.setToken(token_from_backend);
-
-PromisePay.createCardAccount({
-  card_number: '4111111111111111',
-  expiry_month: '12',
-  expiry_year: '2025',
-  cvv: '123'
-}, function(response) {
-  if (response.error) {
-    console.error('Error:', response.error);
-  } else {
-    const cardAccountId = response.card_accounts.id;
-    // Send cardAccountId back to backend
-  }
-});
-```
-
-## Test Results
-
-- **Total Tests:** 272 examples
-- **Failures:** 0
-- **Line Coverage:** 95.22% (518 / 544)
-- **Branch Coverage:** 80.79% (143 / 177)
-- **RuboCop:** No offenses detected
-
-## Files Created
-
-1. `lib/zai_payment/resources/token_auth.rb` - Core resource implementation
-2. `spec/zai_payment/resources/token_auth_spec.rb` - Test suite
-3. `examples/token_auths.md` - Comprehensive usage examples
-4. `docs/token_auths.md` - Technical documentation
-
-## Files Modified
-
-1. `lib/zai_payment.rb` - Added token_auths accessor
-2. `lib/zai_payment/version.rb` - Version bump to 2.1.0
-3. `changelog.md` - Added 2.1.0 release notes
-4. `readme.md` - Added Token Auth documentation
-5. `docs/readme.md` - Updated documentation index
-
-## Security Considerations
-
-- **PCI Compliance:** Tokens enable PCI-compliant card data collection without sensitive data touching your server
-- **Token Expiration:** Tokens have limited lifespan (typically 1 hour)
-- **Single-use:** Tokens should be generated fresh for each session
-- **User-specific:** Each token is tied to a specific user ID
-- **Type-specific:** Bank tokens only for bank accounts, card tokens only for cards
-- **HTTPS Required:** All communication over secure HTTPS
-
-## Next Steps
-
-The Token Auth implementation is complete and ready for use. Developers can now:
-
-1. Generate tokens for buyers to collect credit card information
-2. Generate tokens for sellers to collect bank account details
-3. Integrate with PromisePay.js for secure frontend data collection
-4. Process payments without handling sensitive payment data directly
-
-## Related APIs
-
-This implementation complements existing resources:
-- **Users API** - Create users before generating tokens
-- **Items API** - Use payment accounts to create transactions
-- **Webhooks API** - Receive notifications about payment events
-
-## Documentation Links
-
-- **API Reference:** https://developer.hellozai.com/reference/generatetoken
-- **Examples:** [examples/token_auths.md](examples/token_auths.md)
-- **Guide:** [docs/token_auths.md](docs/token_auths.md)
-- **PromisePay.js:** https://developer.hellozai.com/docs/promisepay-js
-
----
-
-**Implementation Date:** October 24, 2025  
-**Version:** 2.1.0  
-**Status:** ✅ Complete and tested
-