PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Customer and Merchant Initiated Transactions

CIT/MIT Rules and Specific Requirements

Nowadays, subscription-based services, eCommerce, and digital payments incorporate the vital distinction between Customer Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT).

PayConex™ V4 API supports CIT/MIT parameters that provide the necessary information to the issuers to distinguish between CITs and MITs. These parameters apply a set of requirements including:

  1. Clear identification of transaction types.
  2. Enhanced authorization and authentication.
  3. Transparency and communication.
  4. Dispute rights and protections.

For more detailed technicalities on CIT/MIT, see An Overview Of Customer And Merchant Initiated Transaction Distinctions.

📘

Note on Card Present Transactions

These parameters are not optimal for CP transactions as these transactions are always customer-initiated. For this reason, only the scheduleIndicator can be specified to either be SCHEDULED or UNSCHEDULED. See Card Present Request Parameters and MIT/CIT Use Case.

Parameters Use Cases

These are the use cases where CIT/MIT parameters are made either optional or default.

  • SALE and AUTHORIZATIONS (greater than $0) transactions do not contain any default values for these parameters but can be included in the API request.
  • STORE and $0 AUTHORIZATION transactions have default values of:
    • storedCredentialIndicator of INITIAL
    • transactionInitiator of CUSTOMER
    • scheduleIndicator of UNSCHEDULED

CIT/MIT Use Case

For the illustrated workflow of the CITs/MITs within the PayConex™ system, we recommend that you review both the CIT/MIT Use Case and Healthcare Auto-Substantiation use cases.

SALE Transaction Using CIT/MIT Parameters

This transaction is a typical SALE transaction utilizing the credentialOnFile parameters to communicate to the card issuers that the transaction was initiated by a merchant's customer, that it is the first (or initial) transaction, and that it was an unscheduled transaction.

credentialOnFile

ParameterTypeDescriptionExample
transactionInitiatorstringWhether this transaction was initiated by a customer or performed by the merchant.[ "MERCHANT", "CUSTOMER" ].
storedCredentialIndicatorstringWhether this is an initial or subsequent transaction.[ "INITIAL", "SUBSEQUENT" ].
scheduleIndicatorstringWhether this is a scheduled or unscheduled transaction.[ "SCHEDULED", "UNSCHEDULED" ].
networkTransactionIdstringThe card issuer transaction identifier primarily provided in requests with ShieldConex® token recurring payments, which is required for card issuer authorization. This identifier is returned from and represents an originally ran CIT transaction and is required for MIT transactions.
In the case of PayConex™ token, we store this identifier of as part of the token itself therefore this field isn't required.		"910C910ABCF25"

Customer Initial

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "CUSTOMER",
    "storedCredentialIndicator": "INITIAL",
    "scheduleIndicator": "UNSCHEDULED"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Response

{
  ...
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "bfTokenReference": "bft_aab...",
  ...
}

🚧

Note

For security reasons, the transaction metadata does not explicitly indicate whether it is a CIT or an MIT transaction, as this distinction is primarily relevant to merchants and issuers.

With set savePaymentOption to true, the CIT sale/authorization/store transaction response includes bfTokenReference and shieldConexToken. Otherwise, they are stripped out. For more examples, refer to Transaction Processing: Token Retrieval.

Merchant Subsequent - Reissuing Transactions

As the name implies, upon processing the initial transaction, the merchant is able to process a subsequent scheduled recurring payment based on a prior agreement with the customer. The merchant does this by reissuing a SALE with the CIT/MIT parameters, which uses the vaulted PayConex™ token of the CIT. This action is performed on behalf of their customer. For more, see PayConex™ Token vs ShieldConex® Token.

📘

Note

To ensure the recurring functionality, the iframe configuration must check the savePaymentOption setting; or the CP transaction must check the savePayment. This setting indicates whether the user has permitted the merchant to store the token for reuse. For example, the iframe configuration/instance can either have "savePaymentOption": "required" or "savePaymentOption": "optional".

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "bft_aab...",
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "MERCHANT",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "SCHEDULED"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

In some scenarios, this can also be an unscheduled transaction.

{
  "bfTokenReference": "bft_aab...",
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "MERCHANT",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "UNSCHEDULED"
  }
}

Merchant Subsequent - Authorization Transaction

An authorization transaction request with MIT parameters is identical to the sale transaction.

📘

Note

As this authorization remains to be captured and after capturing, the workflow is the same to that of a sale transaction since a sale essentially does both the authorization and capturing. It is the merchant that decides what's the best for their particular use case.

The merchant can also perform an authorization transaction with CIT parameters depending on their use case.

Also see:

POST /api/v4/accounts/{accountId}/payments/auth

{
  "bfTokenReference": "bft_aab...",
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "MERCHANT",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "SCHEDULED"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:auth

MITs with ShieldConex® Token

As mentioned above, when a ShieldConex® Token is used for MIT (recurring) payments, the networkTransactionId from the CIT is required for the card issuers to perform authorization, which prevents fraud.

📘

networkTransactionId

The networkTransactionId can be received by Processing a Sale as CIT, Storing a Card on File, or Getting Transaction Metadata. Particularly, in the response it is trace.networkTransactionId.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "shieldConexToken": {
    "bfid": "djI6MT...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  },
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "MERCHANT",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "SCHEDULED",
    "networkTransactionId": "910C910ABCF25"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

🚧

Note

When it comes to the PayConex™ token, the networkTransactionId is not required as it is made part of the token internally. However, if provided with the PayConex™ token in the request body, the PayConex™ services prioritize grabbing the networkTransactionId from the request body.

Authorization Transaction with ShieldConex® Token

For an authorization transaction with ShieldConex® Token, the request body is identical to that of Sale MIT with ShieldConex® Token except that the authorization remains to be captured.

POST /api/v4/accounts/{accountId}/payments/auth

{
  "shieldConexToken": {
    "bfid": "djI6MT...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  },
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "MERCHANT",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "SCHEDULED",
    "networkTransactionId": "910C910ABCF25"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:auth

Customer Subsequent with ShieldConex® Token

In the case of a ShieldConex® Token, networkTransactionId is also required for customer subsequent transactions due to its purpose and common usage. See below.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "shieldConexToken": {
    "bfid": "djI6MT...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  },
  "posProfile": "SERVER",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "CUSTOMER",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "UNSCHEDULED",
    "networkTransactionId": "910C910ABCF25"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Customer Subsequent

Lastly, the customer has the option to make a subsequent unscheduled transaction on their own behalf. In this scenario, the merchant has previously generated the token that the customer can select for use in a SALE transaction.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "bft_aab...",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "credentialOnFile": {
    "transactionInitiator": "CUSTOMER",
    "storedCredentialIndicator": "SUBSEQUENT",
    "scheduleIndicator": "UNSCHEDULED"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale