Skip to main content

USIO

USIO ACH​

The USIO ACH connector (adapter USIO, payment method ACHDirectDebit) processes US domestic ACH debits, refunds and payouts via the USIO Payments API. Only USD is supported.

For transaction types, request fields, response data, error codes and examples see the adapter-specific API documentation.

Connector Configuration​

Configure the following parameters for the Connector (see Connector Config - USIO ACH):

  1. Fill in the mandatory Username: the USIO Login
  2. Fill in the mandatory Password: the USIO Password
  3. Fill in the mandatory Extra Data: merchantId: the USIO MerchantID
  4. Enable Testmode to process transactions against the USIO sandbox (https://devpayments.usiopay.com). If disabled, the USIO production environment (https://payments.usiopay.com) is used.
  5. Select the optional Extra Data: standardEntryCode: the NACHA Standard Entry Class (SEC) code — WEB, PPD, TEL, CCD. It is the default for every transaction and can be overridden per transaction. A transaction is rejected if neither the connector nor the transaction provides a valid value.
  6. Set Extra Data: checkNegativeAccounts (True, False): checks the account against USIO's negative accounts list. USIO requires this flag on every payment. If left empty, true is sent. Any other value than True or False is a configuration error and the transaction is rejected. It can be overridden per transaction with extraData.checkNegativeAccounts.
  7. Set the optional Extra Data: disableDuplicateCheck (True, False): defaults to false, i.e. USIO's duplicate check stays enabled. It can be overridden per transaction with extraData.disableDuplicateCheck.
  8. Fill in the conditional Extra Data: creditMerchantId, Extra Data: creditUsername and Extra Data: creditPassword: see Payout Credentials

Payout Credentials​

USIO can provision a separate merchant account for ACH credits (payouts). Only in that case fill in creditMerchantId, creditUsername and creditPassword with the credentials of the credit account.

  • If all three are filled in, payouts are submitted with the credit credentials.
  • If any of the three is empty, payouts fall back to the standard Username, Password and merchantId.

The NACHA WEB account validation that runs before a WEB payment always uses the standard credentials, also for payouts.

note

The USIO PCI connector handles payout credentials differently: Pinless Debit payouts do not fall back to the standard credentials. If you run both connectors, configure each one according to its own rules.

Data Fetcher Configuration​

USIO does not send webhooks or status notifications. A debit or payout stays pending until the Reconciliation Data Fetcher reads its final status from USIO's ACH reports, so the Data Fetcher is required for this connector.

You have the option to configure Data Fetchers (see section Enable and Set Up Reconciliation on the Provider Level) either on Provider or on Connector Level, depending on which setup works better for your provider.

Reconciliation​

Configure the following parameters for the Reconciliation Data Fetcher, which fetches USIO's ACH batch and ACH return reports via the API (see Reconciliation Data Fetcher - USIO ACH):

  1. Fill in the expected Interval in which the reconciliation data should be fetched - days, hours. USIO recommends once a day.
  2. Select the Adapter USIO
  3. Enable Testmode to fetch from the USIO sandbox (https://devpayments.usiopay.com). If disabled, the USIO production environment (https://payments.usiopay.com) is used.
  4. Fill in the mandatory Extra Data: merchantId: the USIO MerchantID
  5. Fill in the mandatory Extra Data: username: the USIO Login
  6. Fill in the mandatory Extra Data: password: the USIO Password
  7. Fill in the optional Extra Data: creditMerchantId, Extra Data: creditUsername and Extra Data: creditPassword if payouts use a separate USIO credit account (see Payout Credentials). The credit account's reports are then fetched as well.

With a daily interval, expect the final status of a debit or payout on the business day after USIO has batched it. Settlement data is not fetched by this connector.

Reconciliation Settings​

Set the following in the Reconciliation Settings of the connector:

  • Allow Success to Error: ACH returns (R-codes) can arrive after a transaction was already reported as success, for example when a consumer disputes a debit as unauthorized up to 60 calendar days after settlement. Enable this setting to let a return change the transaction to error automatically. If disabled, the return appears in the Conflicts Tab and has to be resolved manually.
  • Allow Error to Success: if the IXOPAY platform does not receive a clear answer from USIO (e.g. a timeout), the transaction fails, but USIO may have accepted it. Enable this setting to let reconciliation update such a transaction to success automatically. If disabled, it appears in the Conflicts Tab.

USIO PCI​

The USIO PCI connector (adapter USIOPci, payment methods Creditcard and PinlessDebit) processes Credit Card and Pinless Debit payments via the USIO Payments API. Only USD is supported.

For transaction types, request fields and the supported extraData fields see the adapter-specific API documentation.

Connector Configuration​

Configure the following parameters in the Vault Config of the Connector:

  1. Select the mandatory Test Mode: Test, Live. Test routes to the USIO sandbox (https://devpayments.usiopay.com, https://devcheckout.usiopay.com) and only accepts USIO test card numbers. Live routes to USIO production.
  2. Fill in the mandatory MerchantID: the USIO Payments API MerchantID
  3. Fill in the mandatory Username: the USIO Payments API Login
  4. Fill in the mandatory Password: the USIO Payments API Password
  5. Fill in the conditional CheckoutMerchantKey: the USIO Checkout API merchant key. Required for Credit Card Register and Debit or Preauthorize with register. Not needed for a Pinless Debit only connector.
  6. Enable the optional DisableDuplicateCheck to stop USIO from rejecting repeated transactions with identical card, amount and timing as duplicates. A transaction can override this setting with extraData.disableDuplicateCheck (true or false) on Debit, Preauthorize and Payout.
  7. Fill in the conditional CreditMerchantID, CreditLogin and CreditPassword: see Payout Credentials

Configure the following optional parameter in the Config of the Connector:

  1. Enable the optional Send merchantTransactionId as MerchantPayAccount if extraData.merchantPayAccount is not set (Extra Data: merchantTransactionIdAsMerchantPayAccount, disabled by default). If enabled, the transaction's merchantTransactionId is sent as USIO MerchantPayAccount on Debit, Preauthorize and Payout whenever the merchant does not send extraData.merchantPayAccount. A value sent by the merchant always takes precedence. USIO accepts at most 32 characters for MerchantPayAccount, so keep this option disabled if the merchantTransactionId can be longer.

Payout Credentials​

Pinless Debit payouts require a separate USIO merchant account. Fill in CreditMerchantID, CreditLogin and CreditPassword with the credentials of that account.

  • All three are required for a payout. A payout with a missing payout credential is rejected with a configuration error before it is sent to USIO.
  • Payouts never fall back to the standard MerchantID, Username and Password. If USIO has enabled payments and payouts on the same account, enter that account's credentials in both sets of fields.

Credit Card payouts are not supported.