HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
Product Docs
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo

FreedomPay

Connect FreedomPay to Recurly using your Store ID, Terminal ID, Enhanced Security Key, and RSA Key to process card payments, gateway tokens, and Point of Sale subscriptions.

FreedomPay is a full-service payment platform that supports ecommerce and recurring transactions. Integrating it with Recurly lets you process credit and debit card payments, gateway tokens, and — with additional configuration — Point of Sale–derived subscriptions. You'll need a FreedomPay Store ID, Terminal ID, Enhanced Security Key, and RSA Key Slot ID to complete setup.
Available on all Recurly plans
1Definition 2Key details 3Configuring FreedomPay in Recurly 4Processing with FreedomPay 5FAQs

Prerequisites

  • An existing relationship with FreedomPay is required to use this gateway.
  • Point of Sale / NTID via API — To use a POS system with FreedomPay and provide POS-derived NTIDs via the Recurly API, contact Recurly Support to enable the Allow NTIDs to be sent via API feature flag on your account.

Limitations

  • Multi-currency requires multiple gateway instances — FreedomPay currencies are managed per credential set. To support multiple currencies, configure a separate FreedomPay gateway instance in Recurly for each currency.

Definition

FreedomPay is a full-service payment platform that supports ecommerce and recurring transactions via Recurly.js, the API, Checkout, and Hosted Payment Pages. It uses Store ID, Terminal ID, Enhanced Security Key, and RSA Key Slot ID credentials for authentication. If you're using a Card Present Point of Sale system with FreedomPay and want to offer subscriptions, contact Recurly Support for guidance.

Key details

FeatureDetails
Services that work with RecurlyPayment processing, renewals, MOTO processing
Supported integrationsRecurly.js, API, Checkout, HPP
Supported operationsVerify, Purchase, Void, Refund
Supported payment typesCredit and debit cards, gateway tokens
Supported card brandsVisa, Mastercard, Discover, Amex, JCB, Diners, UnionPay
Gateway-specific 3DS2 supportedN/A
Supported capabilitiesCard on file, gateway tokens, ZDA
RegionsUnited States
CurrenciesSee all available

Configuring FreedomPay in Recurly

Note No additional URL configuration is needed beyond setting your Recurly site mode. Recurly automatically connects to the correct FreedomPay environment based on mode:

Development mode → FreedomPay UAT: https://cs.uat.freedompay.com/Freeway/Service.asmx
Production mode → FreedomPay production: https://cs12.freedompay.us/Freeway/Service.asmx
Sandbox mode → Recurly internal test gateway (FreedomPay not used)

Step 1: Obtain your Store ID and Terminal ID

Log in to your FreedomPay Gateway account and retrieve your Store ID and Terminal ID. If you don't have an account, sign up with FreedomPay first.

Step 2: Generate your Enhanced Security (ES) Key

1

Navigate to Enhanced Security Keys

In FreedomPay, go to Administration → Enhanced Security Keys and click Create new under the All enhanced security keys section.

2

Configure the key

Enter a description (e.g., Recurly Configuration Key) and ensure Freeway Payments is checked.

3

Verify Tiers and Stores before creating

Do not click Create yet. Click the Freeway Payments tab and confirm the correct Tiers and Stores are associated with this key.

4

Create and copy the key

Click Create at the bottom of the page, then copy the key using the copy icon. You can click to view the masked key, but copying is all that's needed for configuration.

Step 3: Acquire RSA Key permissions and Key Slot ID

1

Enable RSA Key Management

Ask your FreedomPay contact to enable RSA Key Management for your Freeway user account.

2

Create a new RSA key

Navigate to Administration → RSA Key Management. Select FreedomPay as the RSA Key Provider (this is the default), then click Create New RSA Key.

3

Name and save the key slot

Enter an alphanumeric Key Slot ID name with no spaces — choose a name you'll recognize to avoid accidental deletion. Add a description for future reference, then click Save.

Step 4: Enter credentials in Recurly

1

Open Payment Gateways

In Recurly, navigate to Payment Gateways, click Add a New Gateway, and select FreedomPay.

2

Enter your credentials

Input your Store ID, Terminal ID, Enhanced Security Key (from Step 2), Enterprise Code (provided by your FreedomPay representative), and RSA Key ID (from Step 3).

Step 5: Configure gateway settings and save

1

Select card types and currencies

Under Accepted Credit Card Types, select the card brands you accept in FreedomPay. Under Accepted Currencies, select your supported currencies.

2

Save the gateway

Click Add Payment Gateway once all sections are complete.

Processing with FreedomPay

Further reading

Escalating to FreedomPay or Recurly Support

When escalating a transaction issue to FreedomPay, have the following details ready:

  • Store ID, Terminal ID, Error Code, Request ID of the transaction

Gateway Store and Terminal IDs are in your Recurly account under Configuration → Payment Gateways — select the appropriate gateway instance.

Gateway error codes appear at the top of a declined or errored transaction. In the example below, the error code is 431.

The Reference field maps to the FreedomPay Request ID.

FreedomPay contact details:

Payload examples and error documentation

FreedomPay error code documentation See the FreedomPay Error Code Guide. If you can't access the PDF, contact FreedomPay directly — Recurly Support cannot grant access.

Per FreedomPay's request, the following are examples of a standard payment request and response.

Token request example

<SOAP-ENV:Body>  
    <Submit>  
      <request>  
        <storeId>******</storeId>  
        <terminalId>******</terminalId>  
        <esKey>******</esKey>  
        <merchantReferenceCode>{{Recurly-UUID}}</merchantReferenceCode>  
        <brand>VS</brand>  
        <ccAuthService run="true">  
          <transType>purchase</transType>  
          <allowPartial>N</allowPartial>  
          <returnBalance>Y</returnBalance>  
          <cofIndicator>U</cofIndicator>  
          <cofComplianceData>{{NTID}}</cofComplianceData>  
          <enableAVS>Y</enableAVS>  
          <commerceIndicator>internet</commerceIndicator>  
          <recurring>Y</recurring>  
        </ccAuthService>  
        <ccCaptureService run="true">  
          <isSplitTransaction>N</isSplitTransaction>  
        </ccCaptureService>  
        <billTo>  
          <customerID>{{Recurly-Account-Code}}</customerID>  
          <firstName>Jane</firstName>  
          <lastName>Doe</lastName>  
          <street1>123 Main</street1>  
          <city>Chicago</city>  
          <state>IL</state>  
          <postalCode>12345</postalCode>  
          <country>US</country>  
        </billTo>  
        <card>  
          <accountNumber>{{gateway-token}}</accountNumber>  
          <cardType>token</cardType>  
          <cvNumber>{{masked-cvv}}</cvNumber>  
          <nameOnCard>Jane Doe</nameOnCard>  
        </card>  
        <invoiceHeader>  
          <invoiceNumber>1000</invoiceNumber>  
          <purchaserCode>12345</purchaserCode>  
        </invoiceHeader>  
        <clientMetadata>  
          <sellingSystemName>merchantdomain.com</sellingSystemName>  
          <sellingSystemVersion>1.0</sellingSystemVersion>  
          <sellingMiddlewareName>Recurly</sellingMiddlewareName>  
          <sellingMiddlewareVersion>1.0</sellingMiddlewareVersion>  
        </clientMetadata>  
        <pos>  
          <entryMode>keyed</entryMode>  
          <cardPresent>N</cardPresent>  
          <paymentDate>2024-12-31T17:22:18Z</paymentDate>  
          <caps>K</caps>  
        </pos>  
        <purchaseTotals>   
          <chargeAmount>10.00</chargeAmount>  
          <taxTotal>0</taxTotal>  
        </purchaseTotals>  
        <items>  
          <item>  
            <id>1234567890</id>  
            <productName>Product Name</productName>  
            <productDescription>Description of the Product</productDescription>  
            <unitPrice>10.00</unitPrice>  
            <quantity>1</quantity>  
            <totalAmount>10.00</totalAmount>  
            <unitOfMeasure>EA</unitOfMeasure>  
            <saleCode>S</saleCode>  
            <taxAmount>0</taxAmount>  
            <taxIncludedFlag>N</taxIncludedFlag>  
          </item>  
        </items>  
      </request>  
    </Submit>  
  </SOAP-ENV:Body>  
</SOAP-ENV:Envelope>

Token response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">  
  <soap:Body>  
    <SubmitResponse xmlns="http://freeway.freedompay.com/">  
      <SubmitResult>  
        <merchantReferenceCode>{{Recurly-UUID}}</merchantReferenceCode>  
        <ccAuthReply>  
          <amount>10.00</amount>  
          <processorTransactionID>1234567890</processorTransactionID>  
          <enhancedDataEnabled>N</enhancedDataEnabled>  
          <avsCodeRaw>N</avsCodeRaw>  
          <processorResponseCode>100</processorResponseCode>  
          <reasonCode>100</reasonCode>  
          <authorizationCode>123456</authorizationCode>  
          <avsCode>N</avsCode>  
          <partialAmount>N</partialAmount>  
          <cvCode>M</cvCode>  
          <authorizedDateTime>2024-12-01T17:22:18.8622020Z</authorizedDateTime>  
          <processorResponseMessage>APPROVED</processorResponseMessage>  
          <requestDateTime>2024-12-01T17:22:18.7641802Z</requestDateTime>  
          <cvCodeRaw>M</cvCodeRaw>  
          <reconciliationID>252306047</reconciliationID>  
        </ccAuthReply>  
        <requestID>01Z6MGHC2A97U6G5L9DH6JCG10BDCLTD</requestID>  
        <networkData>  
          <network>FREEWAY</network>  
        </networkData>  
        <tokenInformation>  
          <brand>VS</brand>  
          <accountNumberMasked>411111xxxxxx1111</accountNumberMasked>  
          <cardExpirationYear>29</cardExpirationYear>  
          <cardExpirationMonth>12</cardExpirationMonth>  
          <cardType>credit</cardType>  
        </tokenInformation>  
        <decision>ACCEPT</decision>  
        <reasonCode>100</reasonCode>  
        <ccCaptureReply>  
          <processorTransactionID>252306047</processorTransactionID>  
          <amount>55.15</amount>  
          <requestDateTime>2024-12-10T17:22:18.7641802Z</requestDateTime>  
          <processorResponseCode>100</processorResponseCode>  
          <purchasingLevel3Enabled>N</purchasingLevel3Enabled>  
          <enhancedDataEnabled>N</enhancedDataEnabled>  
          <reasonCode>100</reasonCode>  
          <reconciliationID>1234567890</reconciliationID>  
          <partialAmount>N</partialAmount>  
          <processorResponseMessage>APPROVED</processorResponseMessage>  
        </ccCaptureReply>  
      </SubmitResult>  
    </SubmitResponse>  
  </soap:Body>  
</soap:Envelope>

Security suggestions

Security suggestions from FreedomPay See FreedomPay's Ecommerce Integration Requirements for Security. Not all recommendations will apply to Recurly or your own systems — contact FreedomPay directly with any questions.

FAQs

How do I contact Recurly Support?

See the Do you need help? page for all Recurly Support contact options.

What if my customer doesn't provide an address or CVV and AVS rejection is enabled?

FreedomPay will still generate AVS and CVV response codes in those cases, which will likely result in a rejection due to missing address or CVV data. Collect billing information and CVV codes for all customer-initiated transactions to reduce declines when these features are enabled.

I'm getting authentication failure or gateway configuration errors when making a purchase. How do I fix this?

Check the following:

  • Verify your ES Key has the correct mappings to your Terminal and Store IDs in FreedomPay (this must be done in your FreedomPay account, not in Recurly).
  • Check which Tiers the ES Key is mapped to in your Enterprise FreedomPay login — review the Enterprise Management tab if you have special mappings.
  • Confirm you're not using a UAT Store ID, Terminal ID, or ES Key in Production mode (or vice versa).
  • Verify that the card types selected in Recurly match what's enabled at FreedomPay. If a card brand is selected in Recurly but not enabled in FreedomPay, either contact your FreedomPay representative to add it or remove it from your Recurly gateway configuration.

If the issue persists, contact FreedomPay Support directly.

I'm using a Point of Sale card terminal. How can I connect it to Recurly?

Recurly does not directly support EMV or Card Present transactions. To set up a Card Present → Recurring Subscription flow, first build your card present solution with FreedomPay. That integration should produce a gateway token and a subscription Network Transaction ID (NTID). Once complete, follow the Recurly.js guide to create subscriptions and provide the external NTID correctly. See also: Card on File compliance documentation.

How does customer data flow from my site to FreedomPay?

Data flows from a supported front-end — the Recurly API, Recurly.js, or a Hosted Page — into Recurly and through to FreedomPay via their API connection. Recurly supports two transaction types: CIT (Customer Initiated) and MIT (Merchant Initiated). See Card on File for compliance details.

For Merchant Initiated Transactions, the customer is no longer in session, but their bank still approves or declines the transaction. Recurly does not approve or decline transactions — for decline details, have the customer contact their bank directly.

More Recurly resources For general Recurly troubleshooting and how-tos, search docs.recurly.com. Helpful starting points: Getting started, Subscription lifecycle, Developer Hub, and Auth and Capture.

Updated 7 days ago

Did this page help you?