USA ePay Gateway Guide

USA ePay fact sheet

Quick Start

New to integrating USA ePay with Spreedly? Here's your setup guide:

Retrieve your USA ePay credentials:
1. Create a source key in the USA ePay console and copy the source_key.
2. If that source key has a pin, copy the pin as well. Spreedly does not send the pin itself. It uses the pin to build the request hash USA ePay expects. Leave pin blank when the source key has no pin.
Get familiar with the Spreedly API:
1. Review Spreedly API basics.
2. Review Gateways, Payment Methods, and Transactions.
Add a USA ePay gateway to Spreedly in sandbox mode.
Review this documentation to understand more about how to test transactions.

Additional notes

Additional notes
Invoice vs order id: `UMinvoice` is 10 digits maximum. If you do not send the `invoice` gateway-specific field, Spreedly copies `order_id` into USA ePay's invoice. When `order_id` is omitted, both values are the Spreedly transaction token, which is longer than 10 characters. `order_id` is also sent as `UMorderid` (up to 64 characters). Send a separate `invoice` of at most 10 digits whenever `order_id` is longer than 10 characters. Customer receipts: `cust_receipt` is sent only when the transaction or payment method has an email. If an email is present and `cust_receipt` is omitted, Spreedly sends `No`, which overrides the receipt setting on the USA ePay source. Amounts are minor units: Spreedly amounts are integers in cents. `1000` is sent to USA ePay as `10.00`. Currency is not forwarded: Spreedly requires `currency_code` on Purchase, Authorize, Capture, and Refund. This integration does not send `UMcurrency`. USA ePay uses the currency of the merchant account. Bank accounts: A bank-account Purchase is `check:sale`. Authorize, Capture, Verify, and Store are card commands. The merchant account must have check processing enabled before ACH purchases will succeed. Store of a bank account is accepted by Spreedly and is still sent as `cc:save`, which does not vault the bank account. General credit: Refund is a linked `cc:refund` against the original transaction. Open credit (`cc:credit`) and unlinked check credit (`check:credit`) are not supported.

Invoice vs order id: UMinvoice is 10 digits maximum. If you do not send the invoice gateway-specific field, Spreedly copies order_id into USA ePay's invoice. When order_id is omitted, both values are the Spreedly transaction token, which is longer than 10 characters. order_id is also sent as UMorderid (up to 64 characters). Send a separate invoice of at most 10 digits whenever order_id is longer than 10 characters.
Customer receipts: cust_receipt is sent only when the transaction or payment method has an email. If an email is present and cust_receipt is omitted, Spreedly sends No, which overrides the receipt setting on the USA ePay source.
Amounts are minor units: Spreedly amounts are integers in cents. 1000 is sent to USA ePay as 10.00.
Currency is not forwarded: Spreedly requires currency_code on Purchase, Authorize, Capture, and Refund. This integration does not send UMcurrency. USA ePay uses the currency of the merchant account.
Bank accounts: A bank-account Purchase is check:sale. Authorize, Capture, Verify, and Store are card commands. The merchant account must have check processing enabled before ACH purchases will succeed. Store of a bank account is accepted by Spreedly and is still sent as cc:save, which does not vault the bank account.
General credit: Refund is a linked cc:refund against the original transaction. Open credit (cc:credit) and unlinked check credit (check:credit) are not supported.

Adding a USA ePay gateway

To add a USA ePay gateway, create it in the Spreedly dashboard or with the API below. Select Sandbox to process test transactions. To learn more about creating and managing gateways, review the Gateway user guide.

Required credentials

source_key: Your USA ePay source key. Spreedly sends it as UMkey. This value is returned on the gateway and in credentials.
pin: Optional gateway setting. Required only when the source key has a pin configured in USA ePay. Spreedly uses it to build UMhash and does not send the pin as its own field. The stored pin is returned under gateway_settings. See Specifying a pin.

Sandbox requests are posted to https://sandbox.usaepay.com/gate with UMtestmode=1. Live requests are posted to https://www.usaepay.com/gate with UMtestmode=0. Include <sandbox>true</sandbox> on create to use the sandbox endpoint. Without it, the gateway is live.

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>usa_epay</gateway_type>
        <source_key>YourSourceKey</source_key>
        <pin>YourPin</pin>
        <sandbox>true</sandbox>
      </gateway>'

Omit pin when the source key has no pin.

Response

<gateway>
    <token>6DSJWJY0VA9CxxxxxxxQX4XYZ</token>
    <gateway_type>usa_epay</gateway_type>
    <name>USA ePay</name>
    <description nil="true"/>
    <merchant_profile_key nil="true"/>
    <sub_merchant_key nil="true"/>
    <source_key>YourSourceKey</source_key>
    <characteristics>
        <supports_purchase type="boolean">true</supports_purchase>
        <supports_authorize type="boolean">true</supports_authorize>
        <supports_capture type="boolean">true</supports_capture>
        <supports_partial_capture type="boolean">true</supports_partial_capture>
        <supports_credit type="boolean">true</supports_credit>
        <supports_partial_credit type="boolean">true</supports_partial_credit>
        <supports_general_credit type="boolean">false</supports_general_credit>
        <supports_void type="boolean">true</supports_void>
        <supports_verify type="boolean">true</supports_verify>
        <supports_reference_purchase type="boolean">false</supports_reference_purchase>
        <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
        <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
        <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
        <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
        <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
        <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
        <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
        <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
        <supports_store type="boolean">true</supports_store>
        <supports_remove type="boolean">false</supports_remove>
        <supports_fraud_review type="boolean">false</supports_fraud_review>
        <supports_network_tokenization type="boolean">false</supports_network_tokenization>
        <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
        <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
        <supports_transaction_retry type="boolean">false</supports_transaction_retry>
        <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    </characteristics>
    <credentials>
        <credential>
            <name>source_key</name>
            <value>YourSourceKey</value>
        </credential>
    </credentials>
    <gateway_settings>
        <pin>YourPin</pin>
    </gateway_settings>
    <gateway_specific_fields>
        <gateway_specific_field>cust_receipt</gateway_specific_field>
        <gateway_specific_field>cust_receipt_name</gateway_specific_field>
        <gateway_specific_field>check_format</gateway_specific_field>
        <gateway_specific_field>account_type</gateway_specific_field>
        <gateway_specific_field>custom_fields</gateway_specific_field>
        <gateway_specific_field>line_items</gateway_specific_field>
        <gateway_specific_field>invoice</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
        <payment_method>bank_account</payment_method>
        <payment_method>third_party_token</payment_method>
    </payment_methods>
    <state>retained</state>
    <redacted type="boolean">false</redacted>
    <sandbox type="boolean">true</sandbox>
    <mode>default</mode>
    <created_at type="dateTime">2026-10-26T07:22:39Z</created_at>
    <updated_at type="dateTime">2026-10-26T07:22:39Z</updated_at>
</gateway>

Specifying a pin

Set pin when the USA ePay source key has a pin. Spreedly sends UMhash in this form: s/<seed>/<sha1>/n

The SHA1 digest is of command:pin:amount:invoice:seed. command is the USA ePay command, such as cc:sale. amount is the decimal amount sent to USA ePay, such as 10.00, not the cents integer. Spreedly sends this hash even when pin is omitted; the pin segment is then empty. The pin is not included as its own request field. If the source key has a pin and this setting does not match it, USA ePay rejects the transaction. If the source key has no pin, omit the setting. See USA ePay's source pin documentation.

Purchase (Auth and Capture)

Purchase sends cc:sale for a credit card and check:sale for a bank account. Authorize sends cc:authonly. Capture sends cc:capture for the original reference and the capture amount, which may be less than the authorized amount. Authorize and Capture are card commands. A bank account supports Purchase, and Void or Refund of that purchase.

gateway_transaction_id on a successful Purchase, Authorize, Capture, Refund, or Void is USA ePay's UMrefNum. Pass that value implicitly by referencing the Spreedly transaction when you capture, void, or refund. You do not send UMrefNum yourself.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>1000</amount>
        <currency_code>USD</currency_code>
        <order_id>order-10001</order_id>
        <description>Blue widget</description>
        <email>[email protected]</email>
        <ip>203.0.113.10</ip>
        <billing_address>
          <name>Jane Shopper</name>
          <address1>123 Main St</address1>
          <address2>Apt 4</address2>
          <city>Austin</city>
          <state>TX</state>
          <zip>78701</zip>
          <country>US</country>
        </billing_address>
        <shipping_address>
          <name>Jane Shopper</name>
          <address1>500 Warehouse Rd</address1>
          <city>Austin</city>
          <state>TX</state>
          <zip>78702</zip>
          <country>US</country>
        </shipping_address>
        <gateway_specific_fields>
          <usa_epay>
            <invoice>10001</invoice>
            <cust_receipt>Yes</cust_receipt>
            <cust_receipt_name>Default Receipt</cust_receipt_name>
          </usa_epay>
        </gateway_specific_fields>
      </transaction>'

currency_code is required by Spreedly on Purchase, Authorize, Capture, and Refund, and it is not sent to USA ePay. 1000 is sent as UMamount=10.00. USA ePay charges in the currency of the merchant account. This integration does not send UMcurrency, so multi-currency (MCP) accounts are not supported.

Capture, void, and refund

Spreedly transaction	USA ePay command	Reference field	Amount
Capture	`cc:capture`	Original `UMrefNum`	Capture amount, including a partial amount
Void	`cc:void:release`	Original `UMrefNum`	Not sent
Refund (credit)	`cc:refund`	Original `UMrefNum`	Refund amount, including a partial amount

Void releases the authorization immediately. A card transaction can be voided until the batch closes. A check transaction can be voided until USA ePay sends the ACH file, typically at the end of the business day.

Refund requires the original transaction reference. This integration does not support open credit (cc:credit) or unlinked check credit (check:credit).

Bank account transactions

Purchase with a bank account payment method sends check:sale. The merchant account must have check processing enabled with USA ePay. Authorize, Capture, Verify, and Store are card commands. A Store call for a bank account is accepted by Spreedly and is still sent as cc:save, which does not vault the bank account at USA ePay.

Spreedly field	USA ePay field	Notes
`bank_routing_number`	`UMrouting`	Required for a check purchase
`bank_account_number`	`UMaccount`	Required for a check purchase
Account holder name	`UMname`	Payment method first and last name
`bank_account_type`	`UMaccounttype`	Set on the bank account payment method. Send `checking` or `savings`. Spreedly sends `Checking` or `Savings`. Any other value fails the transaction. When omitted, USA ePay defaults to Checking.
`check_format` gateway-specific field	`UMcheckformat`	ACH format, such as `ARC`. Not supported by every check processor.

bank_account_type belongs on the bank account payment method. The gateway-specific field account_type is accepted on the transaction and returned in gateway_specific_fields, and it is not forwarded to USA ePay.

{
  "payment_method": {
    "bank_account": {
      "first_name": "Jane",
      "last_name": "Shopper",
      "bank_routing_number": "021000021",
      "bank_account_number": "9876543210",
      "bank_account_type": "savings"
    }
  }
}

{
  "transaction": {
    "payment_method_token": "bank_account_token",
    "amount": 1000,
    "currency_code": "USD",
    "gateway_specific_fields": {
      "usa_epay": {
        "check_format": "ARC",
        "invoice": "10001"
      }
    }
  }
}

Store and third-party tokens

Store sends cc:save for a credit card. The returned UMcardRef is stored as a Spreedly third-party token and is also the Store transaction's gateway_transaction_id.

Use that third-party token as payment_method_token on a later Purchase, Authorize, or Verify. Spreedly sends the card reference as UMcard. Remove is not supported. Store does not vault a bank account.

Verify

Verify sends cc:authonly for $0.01 and then cc:void:release for that authorization. The result of the verification is the authorization result. Use Verify with a credit card or with a third-party token created by Store. A bank account cannot be verified.

Billing, shipping, and shopper data

These transaction fields are sent on Authorize and Purchase:

Spreedly field	USA ePay field
`order_id`	`UMorderid`. Also used as `UMinvoice` when the `invoice` gateway-specific field is omitted. `UMinvoice` is 10 digits maximum.
`description`	`UMdescription`
`email`	`UMcustemail`. Transaction email is used when present; otherwise the payment method email is used.
`ip`	`UMip`. When the transaction has no IP, Spreedly sends `127.0.0.1`.
Cardholder or account holder name	`UMname`
Expiration	`UMexpir` as `MMYY`
`verification_value`	`UMcvv2`

Billing and shipping addresses are sent with a bill or ship prefix. The address name is split on spaces: the last word is the last name, and everything before it is the first name. When the address has no name, Spreedly uses the payment method first and last name.

Spreedly address field	Billing	Shipping
`name`	`UMbillfname`, `UMbilllname`	`UMshipfname`, `UMshiplname`
`address1`	`UMbillstreet` and `UMstreet` (AVS)	`UMshipstreet`
`address2`	`UMbillstreet2`	`UMshipstreet2`
`city`	`UMbillcity`	`UMshipcity`
`state`	`UMbillstate`	`UMshipstate`
`zip`	`UMbillzip` and `UMzip` (AVS)	`UMshipzip`
`country`	`UMbillcountry`	`UMshipcountry`
Payment method `company`	`UMbillcompany`, only when the transaction omits `billing_address`	Not sent
Payment method `phone_number`	`UMbillphone`, only when the transaction omits `billing_address`	Not sent

A billing or shipping address on the transaction replaces the payment-method address. Transaction addresses do not carry company, and their phone is stored as phone_number, which this gateway does not read. UMbillcompany and UMbillphone are sent from the payment method only when the transaction omits billing_address. Shipping company and shipping phone are not sent.

UMstreet and UMzip are the billing street and postal code used for AVS. AVS and CVV results are returned on the standard Spreedly response as avs_code (UMavsResultCode) and cvv_code (UMcvv2ResultCode).

Gateway specific fields

Gateway-specific fields must be nested under usa_epay. They are applied to Authorize and Purchase. line_items and custom_fields may be sent as JSON objects or as JSON strings.

<gateway_specific_fields>
  <usa_epay>
    <cust_receipt>Yes</cust_receipt>
    <cust_receipt_name>Default Receipt</cust_receipt_name>
    <check_format>ARC</check_format>
    <invoice>10001</invoice>
    <custom_fields>{"1":"web","2":"campaign-spring"}</custom_fields>
    <line_items>[{"sku":"WIDGET-1","name":"Blue widget","cost":1000,"quantity":1}]</line_items>
  </usa_epay>
</gateway_specific_fields>

Field Name	Type	Required	Use Case (Description)	Example Value
`cust_receipt`	String	No	`Yes` or `No`. Sent as `UMcustreceipt` only when an email is present. When an email is present and this field is omitted, Spreedly sends `No`.	`Yes`
`cust_receipt_name`	String	No	Receipt template name, sent as `UMcustreceiptname`. Sent only when `cust_receipt` is sent. If the template is missing, USA ePay uses the default customer receipt.	`Default Receipt`
`check_format`	String	No	ACH format for a bank-account purchase, sent as `UMcheckformat`. For example, `ARC`. Availability depends on the check processor.	`ARC`
`account_type`	String	No	Accepted on the transaction and returned in `gateway_specific_fields`. USA ePay receives account type from the bank account payment method (`bank_account_type` of `checking` or `savings`), not from this field.	`savings`
`custom_fields`	Object	No	Merchant-defined values sent as `UMcustom1` through `UMcustom20`. USA ePay accepts keys `"1"` through `"20"`, and each value can be up to 255 characters. Spreedly rejects key `"0"` and non-numeric keys. Spreedly does not reject keys above `"20"` or values longer than 255 characters.	`{"1":"web","2":"campaign-spring"}`
`line_items`	Array	No	Order lines. USA ePay stores up to 100 lines. Spreedly numbers lines from zero: the first item is `UMline0sku`, `UMline0cost`, and so on. `cost` is an integer in cents and is sent as a decimal amount. Spreedly does not enforce the 100-line cap or the field lengths below.	See example below
`invoice`	String	No	Sent as `UMinvoice`. USA ePay's maximum is 10 digits. When omitted, Spreedly sends `order_id`, or the transaction token when `order_id` is omitted. Send this field when `order_id` is longer than 10 characters.	`10001`

Line item fields

Field	Sent as	Notes
`product_ref_num`	`UMline{n}productrefnum`	Optional product reference. USA ePay maximum is 12 characters.
`sku`	`UMline{n}sku`	USA ePay maximum is 32 characters.
`name`	`UMline{n}name`	USA ePay maximum is 255 characters.
`description`	`UMline{n}description`	Long description. USA ePay maximum is 64 KB.
`cost`	`UMline{n}cost`	Integer cents. `119` is sent as `1.19`. A string cost is rejected.
`quantity` or `qty`	`UMline{n}qty`	Quantity
`unit`	`UMline{n}um`	Unit of measure. USA ePay uses `EA` when this is blank or invalid. USA ePay maximum is 12 characters.
`taxable`	`UMline{n}taxable`	`Y` or `N`
`tax_rate`	`UMline{n}taxrate`	Tax rate, such as `8.250`. Used for level 3 processing.
`tax_amount`	`UMline{n}taxamount`	Tax amount. When blank, USA ePay calculates it from `tax_rate`.
`commodity_code`	`UMline{n}commoditycode`	USA ePay maximum is 12 characters. Used for level 3 processing.
`discount_rate`	`UMline{n}discountrate`	Discount percentage. Used for level 3 processing.
`discount_amount`	`UMline{n}discountamount`	Discount amount. When blank, USA ePay calculates it from `discount_rate`.

{n} starts at 0 for the first array element. The lengths above are USA ePay's maximums. Spreedly forwards the values without truncating them.

{
  "line_items": [
    {
      "product_ref_num": "1234",
      "sku": "WIDGET-1",
      "name": "Blue widget",
      "description": "A blue widget",
      "cost": 1000,
      "quantity": 1,
      "unit": "EA",
      "taxable": "Y",
      "tax_rate": "8.250",
      "commodity_code": "53131600"
    },
    {
      "sku": "WIDGET-2",
      "name": "Red widget",
      "cost": 250,
      "qty": 2
    }
  ],
  "custom_fields": {
    "1": "web",
    "2": "campaign-spring"
  }
}

Gateway specific response fields

A Purchase or Authorize response includes auth_code when USA ePay returns UMauthCode.

<transaction>
  <token>GEmCSGNCtBAvrM7YPrRVG6iexyz</token>
  <transaction_type>Purchase</transaction_type>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <gateway_transaction_id>55074409</gateway_transaction_id>
  <gateway_specific_response_fields>
    <usa_epay>
      <auth_code>001716</auth_code>
    </usa_epay>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>Success</message>
    <avs_code>Y</avs_code>
    <cvv_code>M</cvv_code>
    <error_code>00000</error_code>
  </response>
</transaction>

Field Name	Type	Description
`auth_code`	String	Issuer authorization code from `UMauthCode`.

Other USA ePay response values are mapped onto the standard Spreedly response:

Spreedly field	USA ePay field	Description
`succeeded` / `response.success`	`UMstatus`	`true` when the status is `Approved`.
`response.message`	`UMerror`	`Success` when approved. Otherwise the USA ePay error text, or `Unspecified error` when that text is blank.
`response.error_code`	`UMerrorcode`	USA ePay's numeric error code. An approval returns `00000`. A card decline returns `10127`.
`response.avs_code`	`UMavsResultCode`	AVS result code.
`response.cvv_code`	`UMcvv2ResultCode`	CVV result code.
`gateway_transaction_id`	`UMrefNum`	Transaction reference. On Store, this is `UMcardRef` instead.

Additional resources

📘
If you need support with this gateway, please contact Support at [email protected].

📘
USA ePay Transaction API : Transaction API - USAePay Help
Source pin documentation: https://help.usaepay.info/developer/transaction-api/#source-pin-code
API endpoint: https://www.usaepay.com/gate
Sandbox endpoint: https://sandbox.usaepay.com/gate