Storing Payment Methods

Card brands' requirements for their Stored Credential Transaction framework mandate the identification of both the initial storage and subsequent use of payment credentials.

Stax enables merchants to comply with these requirements, allowing them to benefit from higher transaction approval rates and lower decline rates offered by the Stored Credential Transaction framework.

API Overview

cogRequired API Properties

Stax has implemented enhancements to the API to introduce additional flexibility and granularity when defining transaction characteristics. These updates are relevant for tracking and understanding transaction types within our systems. Any clients who have built to the Stax Charge API or the Stax Pay an Invoice API will be required to provide these property values to maintain compliance.

These properties are available and required for compliance in the request body for the POST/charge route as follows:

1. meta.transaction_initiation_type (required, string)

Values: MIT or CIT
Usage: This specifies whether a transaction is a Merchant-Initiated Transaction (MIT) or a Customer-Initiated Transaction (CIT).

2. meta.transaction_schedule_type (required, string)

Values: scheduled or unscheduled
Usage: "Scheduled" denotes a recurring transaction or installment; "unscheduled" signifies a new payment not linked to any recurring schedule

Stax Scheduled Payments

calendar-check

Automated Payments

If you are using the Stax Scheduled Invoices APIs or Stax Pay Schedules within the portal for autopayments, the Stax system generates these payments automatically. No additional actions are required.

credit-card

One-Time Payments

Using Stax Hosted Payments Page, Payment Links, or StaxJS pay() method for one-time payments are all customer-initiated and unscheduled. Stax's system populates the correct transaction characteristics automatically.

wrench

Custom Schedules

If you opt to use your own schedule, you must include the specified data fields in Charge API requests and correctly identify whether an invoice is first-time or recurring.

Understanding Transaction Types

user

Customer Initiated Transaction (CIT)

When the customer actively participates in checkout

Customer engagement: Active involvement, either physically in-store or online
Initiation: Customer starts the payment process by providing payment details
Real-time interaction required

store

Merchant Initiated Transaction (MIT)

When merchant charges without active customer involvement

Pre-authorization: Customer has previously allowed merchant to initiate transactions
Dependency: Generally follows a CIT to capture necessary authorization
No customer presence required

Transaction Flow

Initial Transaction (CIT):

Subsequent Transactions (MIT):

Implementation Examples

Customer Initiated (CIT) One-time Payment (Unscheduled)

The ISV builds its own hosted payments page where the customer (payer) can make a one-time payment.

{
  "transaction": {
    "payment_method_token": "exampleToken12345",
    "amount": 150,
    "currency_code": "USD",
    "meta": {
      "transaction_initiation_type": "CIT",
      "transaction_schedule_type": "unscheduled"
    }
  }
}

Merchant Initiated (MIT) One-time Payment (Unscheduled)

The customer orders a product online and later adds accessories. Merchants can initiate this additional charge without requiring the customer to go through the payment process again.

{
  "transaction": {
    "payment_method_token": "exampleToken12345",
    "amount": 150,
    "currency_code": "USD",
    "meta": {
      "transaction_initiation_type": "MIT",
      "transaction_schedule_type": "unscheduled"
    }
  }
}

Merchant Initiated (MIT) Scheduled Payment

An ISV provides a subscription service, and the merchant must charge customers for the subscription on a regular and automatic basis.

{
  "transaction": {
    "payment_method_token": "exampleToken12345",
    "amount": 150,
    "currency_code": "USD",
    "meta": {
      "transaction_initiation_type": "MIT",
      "transaction_schedule_type": "scheduled"
    }
  }
}

Setting Up Recurring Payments

The customer initiates the first transaction but also sets up a schedule for recurring payments.

First Payment: CIT Unscheduled

{
  "transaction": {
    "payment_method_token": "exampleToken11223",
    "amount": 75,
    "currency_code": "USD",
    "meta": {
      "transaction_initiation_type": "CIT",
      "transaction_schedule_type": "unscheduled"
    }
  }
}

Future Payments: MIT Scheduled

{
  "transaction": {
    "payment_method_token": "exampleToken11223",
    "amount": 75,
    "currency_code": "USD",
    "meta": {
      "transaction_initiation_type": "MIT",
      "transaction_schedule_type": "scheduled"
    }
  }
}