Cashier is FinteqHub's payment widget solution that provides a seamless, iframe-based payment interface for merchants. From the merchant's perspective, Cashier enables you to:

• Accept Multiple Payment Methods: Automatically display available payment methods to customers
• Secure Payment Processing: Handle sensitive payment data without PCI compliance burden
• Customer Account Management: Allow customers to save payment methods for future use
• Flexible Integration: Simple iframe embedding with minimal code changes

Integration Overview

1. Backend Setup: Create initTokens on your server using merchant credentials
2. Frontend Integration: Embed the Cashier widget iframe in your checkout page
3. Authorization Flow: Handle authentication tokens and callbacks

Key Benefits for Merchants

• Security: Payment data never touches merchant servers
• Compliance: PCI DSS scope reduction
• User Experience: Consistent, optimized payment interface
• Flexibility: Support for various payment methods and flows

Follow these steps to integrate Cashier into your payment flow:

1. Generate InitToken (Backend)

Create JWE-encrypted initToken on your server before displaying the payment form.

Complete Ruby and Python implementation examples are provided separately and available locally upon request.

# Simplified example
def create_init_token(project_token, project_id, project_token_id, merchant_id, business_data):
    # 1. Generate unique metadata (jti, iat, exp)
    jti = str(uuid.uuid4())
    iat = int(datetime.now(timezone.utc).timestamp())
    exp = iat + 3600  # 1 hour expiry
    
    # 2. Encrypt system identifiers using AES-GCM
    # 3. Create JWE token with business payload
    return jwe_token  # Returns JWE compact serialization

2. Embed Cashier Widget (Frontend)

Install and configure the Cashier widget using the CDN or types package.

Widget Repository:

CDN Installation:

<script src="https://cdn.finteqhub.com/finteqhub-cashier.js"></script>

Types Package (Optional - for TypeScript support):

npm install --save-dev @finteqhub/cashier-types

Widget Integration:

<script>
  const widget = new FinteqHubCashier({
    initToken: "your_generated_init_token",
    bonuses: [],
    lotteries: [],
    balance: 1000,
    locale: 'en',
    theme: 'dark',      // Optional: 'light' or 'dark'
    autoClose: true,    // Optional: auto-close on user close action
  });
  
  // Open the widget
  widget.open();
  
  // Handle widget events
  widget.onEvent((event) => {
    if (event.type === 'PAYMENT_SUCCESS') {
      console.log('Payment successful:', event.payload);
      widget.close();
    }
    
    if (event.type === 'WIDGET_TRIGGER_CLOSE') {
      // Widget closes automatically if autoClose is true
      console.log('Widget closed by user');
      widget.close();
    }
    
    if (event.type === 'BONUSES_PROMOCODE_SUBMITTED') {
      console.log('Promocode:', event.payload.promocode);
      widget.setOptions({
        bonuses: [
          {
            id: "welcome",
            name: "Welcome Bonus", 
            description: "100% up on your first deposit"
          }
        ]
      });
    }
  });
</script>

3. Handle Authorization Requests (Backend)

Implement authorization endpoint to approve/decline payments in real-time.

4. Process Callbacks (Backend)

Handle payment status notifications from FinteqHub.

sequenceDiagram
    participant M as Merchant Backend
    participant F as Merchant Frontend
    participant C as Cashier Widget
    participant FTH as FinteqHub
    participant PSP as Payment Provider
    
    M->>M: Generate initToken
    F->>C: Initialize widget(initToken)
    C->>FTH: Payment request
    FTH->>M: Authorization request
    
    alt Immediate Decision
        M-->>FTH: approve/decline (HTTP 201)
        FTH->>PSP: Process payment
    else Delayed Authorization (not implemented)
        M-->>FTH: waiting_authorization (HTTP 201)
        Note over M: Manual review process
        M->>FTH: Merchant Authorization Callback
        FTH->>PSP: Process payment
    end
    
    PSP-->>FTH: Payment result
    FTH->>M: Payment callback
    FTH->>C: Update status
    C->>F: Payment event

InitToken Creation Process

Business Payload Structure:

{
  "currencyCode": "USD",
  "customer": {
    "merchantCustomerId": "CUST-12345",
    "name": "John Doe",
    "email": "[email protected]",
    "countryCode": "US"
  },
  "session": {
    "ip": "192.168.1.100"
  }
}

Widget API Methods

Available Methods:

• widget.open(options?) - Opens the widget, optionally with new configuration
• widget.close() - Closes the widget
• widget.setOptions(newOptions) - Updates widget configuration dynamically
• widget.onEvent(callback) - Registers event handler for widget events

Key Event Types:

• PAYMENT_SUCCESS - Payment completed successfully
• PAYMENT_FAILED - Payment failed or was cancelled
• WIDGET_TRIGGER_CLOSE - User requested widget close
• BONUSES_PROMOCODE_SUBMITTED - User submitted a promocode
• WIDGET_READY - Widget fully loaded and ready
• METHOD_SELECTED - Payment method was selected

Event Structure: Each event object contains type (string) and payload (any) properties with relevant data.

This section lists all credential parameters that may appear in cashier credential forms across payment methods. For each parameter we show a practical example, expected length (min/max), and the validation format when applicable. Formats map to gateway validators: email, iso3166-alpha-2, iso3166-alpha-3, iso4217-currency-code, date, date-time, E.164, postal-code, uri, bcp47-language, rfc6557-time-zone, uuid, decimal, IPv4, IPv6, IP-dual-stack.

Note: Availability and required/optional status depend on the payment method and integration. Use Get Payment Methods to fetch actual fields and constraints per method. Fields marked “not implemented” are reserved and may be ignored by current integrations.

credentials:
  countryCode:
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Customer’s country
  integrationCustomerId:
    example: "CUST-123456"
    minLength: 0
    maxLength: 64
    format: string
    description: Unique identifier of Customer on Integration’s side
  firstName:
    example: "John"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s first name
  lastName:
    example: "Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s last name
  middleName:
    example: "A"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s middle name
  fullName:
    example: "John A Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s full name
  userName:
    example: "john_doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s username on merchant side
  identificationNumber:
    example: "A123456789"
    minLength: 0
    maxLength: 50
    format: string
    description: National identification number
  document:
    example: "AO1234567"
    minLength: 0
    maxLength: 50
    format: string
    description: Customer’s identifier (document) number
  documentType:
    example: "passport"
    minLength: 0
    maxLength: 255
    format: string
    description: Document type (passport, id-card, residence-permit)
  documentIssueDate:
    example: "2023-05-15"
    minLength: 10
    maxLength: 10
    format: date
    description: Document issue date (YYYY-MM-DD)
  birthDate:
    example: "1985-04-12"
    minLength: 10
    maxLength: 10
    format: date
    description: Date of birth (YYYY-MM-DD)
  yearOfBirth:
    example: "1985"
    minLength: 4
    maxLength: 4
    format: string
    description: Year of birth (YYYY)
  nationality:
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Customer nationality (prefer countryCode when possible)
  gender:
    enum: ["Male", "Female"]
    format: enum
    description: Customer’s gender
  email:
    example: "[email protected]"
    minLength: 4
    maxLength: 254
    format: email
    description: Customer’s email
  phoneNumber:
    example: "5551234567"
    minLength: 5
    maxLength: 15
    format: string
    description: Customer’s phone number without country code
  phoneCountryCode:
    example: "1"
    minLength: 0
    maxLength: 5
    format: E.164
    description: Country phone code (without "+")
  accountPhoneNumber:
    example: "5559876543"
    minLength: 5
    maxLength: 15
    format: string
    description: Customer’s account phone number (integration account)
  accountPhoneCountryCode:
    example: "1"
    minLength: 0
    maxLength: 5
    format: E.164
    description: Country phone code for integration account (without "+")
  cpf:
    example: "12345678901"
    minLength: 0
    maxLength: 11
    format: string
    description: Brazil CPF (taxpayer registry number)
  language:
    example: "en"
    minLength: 2
    maxLength: 2
    format: bcp47-language
    description: Customer’s language
  merchantCustomerAccountId:
    example: "ACCT-7890"
    minLength: 0
    maxLength: 255
    format: string
    description: Customer Account ID on merchant side

  account:
    example: "[email protected]"
    minLength: 0
    maxLength: 254
    format: string
    description: Unique account identifier on integration side (email for interac/interac-e-transfer)
  accountAddress:
    example: "0xAbC12345..."
    minLength: 0
    maxLength: 254
    format: string
    description: Cryptocurrency address
  accountTag:
    example: "123456"
    minLength: 0
    maxLength: 254
    format: string
    description: Cryptocurrency tag or memo
  wallet:
    example: "ewallet_abc123"
    minLength: 0
    maxLength: 254
    format: string
    description: Wallet identifier (integer for ecopayz)
  voucherPin:
    example: "9876543210"
    minLength: 0
    maxLength: 254
    format: string
    description: Voucher PIN code
  accountHolderName:
    example: "John Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Account holder’s name
  accountType:
    example: "savings"
    minLength: 0
    maxLength: 50
    format: string
    description: Account type
  password:
    example: "MySecret#2024"
    minLength: 0
    maxLength: 255
    format: string
    description: Account password
  upiNumber:
    example: "john@upi"
    minLength: 0
    maxLength: 100
    format: string
    description: UPI number
  skrillProjectCode:
    example: "AB123456"
    minLength: 8
    maxLength: 8
    format: string
    description: Skrill project code
  paymentOption:
    example: "bank-of-america"
    format: string
    description: Specific payment option (integration-defined)
  "steamData.steamId64":
    example: "76561198000000000"
    minLength: 0
    maxLength: 19
    format: string
    description: Steam ID 64
  tradeToken:
    example: "ABCDEFGH"
    minLength: 8
    maxLength: 8
    format: string
    description: Trade token
  partner:
    example: "steam"
    minLength: 0
    maxLength: 255
    format: string
    description: Partner identifier
  game:
    example: "csgo"
    minLength: 0
    maxLength: 255
    format: string
    description: Game identifier
  skinName:
    example: "AK-47 | Redline"
    minLength: 0
    maxLength: 255
    format: string
    description: Item/skin name

  "billingAddress.city":
    example: "New York"
    minLength: 0
    maxLength: 255
    format: string
    description: Billing city
  "billingAddress.state":
    example: "NY"
    minLength: 1
    maxLength: 6
    format: string
    description: Billing state/region code
  "billingAddress.countryCode":
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Billing country code
  "billingAddress.address":
    example: "350 5th Ave"
    minLength: 0
    maxLength: 255
    format: string
    description: Billing address line
  "billingAddress.postalCode":
    example: "10001"
    minLength: 2
    maxLength: 255
    format: postal-code
    description: Billing postal code

  "shippingAddress.city":
    example: "New York"
    minLength: 0
    maxLength: 255
    format: string
    description: Shipping city
  "shippingAddress.state":
    example: "NY"
    minLength: 1
    maxLength: 6
    format: string
    description: Shipping state/region code
  "shippingAddress.countryCode":
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Shipping country code
  "shippingAddress.address":
    example: "350 5th Ave"
    minLength: 0
    maxLength: 255
    format: string
    description: Shipping address line
  "shippingAddress.postalCode":
    example: "10001"
    minLength: 2
    maxLength: 255
    format: postal-code
    description: Shipping postal code

  "card.number":
    example: "4111111111111111"
    minLength: 0
    maxLength: 19
    format: string
    description: Primary Account Number (PAN)
  "card.holder":
    example: "JOHN DOE"
    minLength: 0
    maxLength: 50
    format: string
    description: Cardholder name
  "card.expiryMonth":
    example: "12"
    minLength: 1
    maxLength: 2
    format: string
    description: Expiry month
  "card.expiryYear":
    example: "2026"
    minLength: 4
    maxLength: 4
    format: string
    description: Expiry year (YYYY)
  "card.cvv":
    example: "123"
    minLength: 3
    maxLength: 4
    format: string
    description: CVV/CVC
  tokenize:
    example: true
    format: boolean
    description: Save card as customer account if applicable
  "payer.firstName":
    example: "John"
    minLength: 0
    maxLength: 50
    format: string
    description: Payer first name (card-only)
  "payer.lastName":
    example: "Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Payer last name (card-only)
  "payer.email":
    example: "[email protected]"
    minLength: 4
    maxLength: 254
    format: email
    description: Payer email (card-only)
  "payer.phoneNumber":
    example: "5551234567"
    minLength: 5
    maxLength: 15
    format: string
    description: Payer phone number without country code (card-only)
  "payer.phoneCountryCode":
    example: "1"
    minLength: 0
    maxLength: 5
    format: E.164
    description: Payer country dial code without "+" (card-only)
  "payer.birthDate":
    example: "1985-04-12"
    minLength: 10
    maxLength: 10
    format: date
    description: Payer date of birth (card-only)
  "payer.document":
    example: "AO1234567"
    minLength: 0
    maxLength: 50
    format: string
    description: Payer document number (card-only)
  "payer.documentType":
    example: "passport"
    minLength: 0
    maxLength: 50
    format: string
    description: Payer document type (card-only)
  "payer.type":
    example: "organization"
    minLength: 0
    maxLength: 50
    format: string
    description: Payer type (card-only)
  "payer.residenceCountryCode":
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Payer residence country (card-only)
  "payer.birthCountryCode":
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Payer birth country (card-only)

  "document.holderName":
    example: "John Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Document owner full name (card-only)
  "document.type":
    example: "passport"
    minLength: 0
    maxLength: 50
    format: string
    description: Document type (card-only)
  "document.subtype":
    example: "national"
    minLength: 0
    maxLength: 50
    format: string
    description: Document subtype (card-only)
  "document.number":
    example: "A1234567"
    minLength: 0
    maxLength: 50
    format: string
    description: Document number (card-only)
  "document.countryCode":
    example: "US"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Issuing country (card-only)

  "bankInformation.bankId":
    example: "BR001"
    minLength: 0
    maxLength: 255
    format: string
    description: Identifier code of financial institution on integration side
  "bankInformation.bankAccountId":
    example: "1234567890"
    minLength: 0
    maxLength: 100
    format: string
    description: Bank account ID
  "bankInformation.bankAccountName":
    example: "John Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Account name
  "bankInformation.bankAccountFirstName":
    example: "John"
    minLength: 0
    maxLength: 50
    format: string
    description: Account first name
  "bankInformation.bankAccountLastName":
    example: "Doe"
    minLength: 0
    maxLength: 50
    format: string
    description: Account last name
  "bankInformation.bankIBAN":
    example: "DE89370400440532013000"
    minLength: 0
    maxLength: 34
    format: string
    description: IBAN
  "bankInformation.bankBBAN":
    example: "NQ00 0000 0000 0000"
    minLength: 0
    maxLength: 34
    format: string
    description: BBAN (where applicable)
  "bankInformation.bankIFSC":
    example: "HDFC0001234"
    minLength: 0
    maxLength: 11
    format: string
    description: Indian IFSC
  "bankInformation.bankBIC":
    example: "DEUTDEFF"
    minLength: 8
    maxLength: 11
    format: string
    description: BIC/SWIFT
  "bankInformation.bankName":
    example: "Deutsche Bank"
    minLength: 0
    maxLength: 255
    format: string
    description: Bank name
  "bankInformation.bankCountryCode":
    example: "DE"
    minLength: 2
    maxLength: 2
    format: iso3166-alpha-2
    description: Bank country
  "bankInformation.bankCity":
    example: "Berlin"
    minLength: 0
    maxLength: 100
    format: string
    description: Bank city
  "bankInformation.bankProvince":
    example: "ON"
    minLength: 0
    maxLength: 255
    format: string
    description: Province/region
  "bankInformation.bankCorrAccount":
    example: "123456789012345"
    minLength: 0
    maxLength: 255
    format: string
    description: Correspondent bank account
  "bankInformation.bankBranch":
    example: "00123"
    minLength: 0
    maxLength: 50
    format: string
    description: Bank branch ID
  "bankInformation.bankClearingSystemCode":
    example: "ACH"
    minLength: 0
    maxLength: 255
    format: string
    description: Clearing system code
  "bankInformation.bankClearingSystemId":
    example: "001234567"
    minLength: 0
    maxLength: 18
    format: string
    description: Clearing system identifier (CA: 0 + institution(3) + transit/branch(5))
  "bankInformation.bankCode":
    example: "001234567890"
    minLength: 0
    maxLength: 15
    format: string
    description: Bank code (IFSC/Zengin/other country-specific)
  "bankInformation.bankIspbCode":
    example: "12345678"
    minLength: 8
    maxLength: 8
    format: string
    description: Brazilian ISPB code
  "bankInformation.sortCode":
    example: "12-34-56"
    format: string
    description: UK sort code
  "bankInformation.bankAddress":
    example: "1 Main St"
    minLength: 0
    maxLength: 255
    format: string
    description: Bank address
  "bankInformation.bankPostalCode":
    example: "10115"
    minLength: 0
    maxLength: 100
    format: postal-code
    description: Bank postal code
  bankInformation2:
    type: array
    items: object
    description: Array of bank information objects (same structure as bankInformation)
  bankInformation3:
    type: array
    items: object
    description: Additional bank information (integration-specific)

  "attributes.paymentiq.verifyUser":
    type: object
    format: object
    description: Additional user specific parameters (values must be scalar types)
  payhost:
    type: object
    description: Integration-specific attributes
  depositCount:
    type: number
    description: Count of deposits on merchant’s side
  withdrawalCount:
    type: number
    description: Count of withdrawals on merchant’s side

Authorization Request Schema

When a payment is initiated through the Cashier widget, FinteqHub sends an authorization request to your configured endpoint to approve or decline the operation.

FinteqHub → Merchant Authorization Request:

POST {authIntegrationURL} (configured in project settings)

Headers:

Content-Type: application/json
X-Request-ID: {uuid}
Authorization: Bearer {system_auth_token}  # Optional

Request Payload:

{
  "operationId": "01926c4e-8b5f-7890-1234-567890abcdef",
  "merchantOperationId": "MERCH_REF_12345",
  "amount": "150.00",
  "currencyCode": "USD",
  "txType": "deposit",
  "customer": {
    "merchantCustomerId": "USER_789",
    "email": "[email protected]",
    "name": "John Doe",
    "countryCode": "US",
    "phoneNumber": "+1234567890"
  },
  "paymentMethod": "card-acquirer",
  "credentials": {
    "card": {
      "maskedNumber": "411111******1111",
      "expiryMonth": 12,
      "expiryYear": 2025,
      "holder": "JOHN DOE"
    },
    "payer": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "session": {
    "ip": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "country": "US"
  },
  "metadata": {
    "originalAmount": "150.00",
    "promotions": ["PROMO2025"],
    "riskScore": 0.2
  }
}

Expected Merchant Response:

Your endpoint must respond with HTTP 201 Created and one of these authorization status options:

✅ Immediate Approval:

{
  "authorizationStatus": "succeeded",
  "merchantOperationId": "APPROVED_OP_12345",
  "merchantTransactionId": "TXN_12345"
}

❌ Immediate Rejection:

{
  "authorizationStatus": "failed",
  "merchantOperationId": "REJECTED_OP_12345",
  "merchantTransactionId": "TXN_12345"
}

⏳ Delayed Authorization (NOT IMPLEMENTED):

{
  "authorizationStatus": "waiting_authorization",
  "merchantOperationId": "PENDING_OP_12345",
  "merchantTransactionId": "TXN_12345"
}

⚠️ Note: Delayed authorization is currently not implemented. Any status other than "succeeded" will result in operation failure.

Important Requirements:

• HTTP Status: Your endpoint MUST respond with HTTP 201 Created
• Success Status: Only "authorizationStatus": "succeeded" will process the payment
• Failure Handling: Any other status ("failed", "waiting_authorization", etc.) will mark the operation as failed
• Required Fields:
  • authorizationStatus: Must be "succeeded", "failed", or "waiting_authorization"
  • merchantOperationId: Your internal operation reference (optional, max 100 chars)
  • merchantTransactionId: Your internal transaction reference (optional, max 100 chars)

For Delayed Authorization (when implemented): Send final decision later via POST /v1/cashier/authorization-operation/{operationId} with same response format