Directory
DevelopersSupportContact usBook demo
Start typing to search…

FreedomPay

FreedomPay Gateway: A secure and innovative payment platform enabling seamless transactions, advanced data analytics, and enhanced customer experiences for retail, e-commerce, and SaaS businesses.

Overview

Required plan

This feature or setting is available to all customers on any Recurly subscription plan.

Prerequisites

To use a Point of Sale system with FreedomPay and provide POS-derived NTIDs via API, your Recurly account must have the following prerequisites:

  • Feature flag: Allow NTIDs to be sent via API. Reach out to support to have this enabled.

Limitations

FreedomPay currencies are managed by credentials. You will need multiple FreedomPay gateway instances to support multiple currencies.

Definition

FreedomPay is a full-service payment platform. When configured with Recurly, it allows you to securely manage your transactions. You will need a FreedomPay Store ID, Terminal ID, and Enhanced Security Key to enable this integration.

Recurly supports Ecommerce and Recurring transactions with FreedomPay. If you are using a Card Present Point of Sale system with FreedomPay and want to offer subscriptions, reach out to Support for guidance.

Key details

FeaturesAvailability
Services that work with RecurlyPayment Processing, Renewals
Supported integrationsRecurly.js, API, Checkout, HPP
Supported operationsVerify, Purchase, Void, and 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
CurrenciesFreedomPay supports all ISO-standard currencies. See all available.

Configuring FreedomPay gateway in Recurly

Follow the steps below to configure FreedomPay in Recurly. Make sure you use the correct site mode and FreedomPay credentials for a seamless setup.

Please note: While the URLs are listed below, there is no configuration or specific integration necessary other than Recurly site mode to access these endpoints.

Step 1: Obtain your FreedomPay Store ID and Terminal ID

Log into your FreedomPay Gateway account. If you do not have an account, sign up with FreedomPay first.

Step 2: Generate your Enhanced Security (ES) Key

  1. Navigate to Administration → Enhanced Security Keys.
  2. Click Create new under the All enhanced security keys section.
  3. Enter a description for the key (e.g., Recurly Configuration Key).
  4. Ensure Freeway Payments is checked.
  5. Do not click "Create" yet. Instead, click the Freeway Payments tab and verify the correct Tiers and Stores are associated with the key.
  6. Click Create at the bottom of the page.
  7. Copy the key using the copy icon. You can click to view the masked key, but it's not necessary for configuration.

Step 3: Acquire RSA Key Permissions and RSA key Slot ID from FreedomPay

  1. Ask your FreedomPay contact to enable RSA Key Management for your Freeway user account.
  2. Navigate to Administration › RSA Key Management.
  3. Select ‘RSA Key Provider’ of ‘FreedomPay’. This should be the default.
  4. Click CREATE NEW RSA KEY
  5. Type in a Key Slot ID name. The key name must be alpha-numeric with no spaces. Ensure you will recognize the key slot ID to avoid deletion.
  6. Type in a description of the key slot ID for future reference.
  7. Click Save

Step 4: Enter your FreedomPay credentials in Recurly

  1. Log into your Recurly account and navigate to the Payment Gateways page.
  2. Click Add a New Gateway.
  3. Select FreedomPay from the list of gateways.
  4. Enter your Store ID and Terminal ID.
  5. Enter the Enhanced Security Key (ES Key) generated in Step 2.
  6. Enter the Enterprise Code given to you by your FreedomPay representative.
  7. Enter your RSA Key ID generated in Step 3.

Step 5: Configure your gateway settings

  1. Under Accepted Credit Card Types, select which card types you want to accept. This should match what you have set up in your FreedomPay account.
  2. Under Accepted Currencies, select the currencies you want to accept.
  3. Click Add Payment Gateway once all sections are complete.

Processing with FreedomPay

Further reading on Recurly functionality can be found elsewhere on this site. Please use the left-menu to discover and troubleshoot other features of our platform

Escalating to FreedomPay or Recurly Tech Support

If you need to reach out to FreedomPay directly, ensure you have all appropriate details available to provide when escalating for troubleshooting.

Details to Collect and Provide

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

Contact Details

How to Find Details

Gateway Store and Terminal IDs can be found in your Payment Gateway configuration details under Configuration › Payment Gateways and select the appropriate gateway instance.

Gateway error codes will be available at the top of a given transaction that was declined or produced an error. In the example below, the code in question is “431”.

The Reference below will map to the FreedomPay Request ID.

Payload examples and error documentation

FreedomPay Error Code Documentation:Error Code Guide

Per FreedomPay request, we are providing examples of a proper request and response to a standard payment.

If you cannot access this PDF, please reach out to FreedomPay directly. Recurly support does not have authority to grant access.

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>
\<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

Per FreedomPay request, we are providing their security suggestions. Not all of these will apply to Recurly systems, or your own. If there are any questions on this document, reach out to FreedomPay directly.

Please, read:Ecommerce Integration Requirements for Security.

FAQs

How do I contact Recurly Support?

Please reference this page: https://docs.recurly.com/docs/do-you-need-help

What if my customer does not provide an address or CVV on the initial transaction and AVS Rejection is enabled?

FreedomPay will still generate AVS and CVV response codes in such cases, which will likely result in a rejection due to the absence of address and CVV information. It's important to capture billing information and CVV codes for all customer-initiated transactions to prevent an increase in declines when these features are enabled.

I am getting authentication failure or gateway configuration messages when I try to make a purchase. How can I fix this?

Check the following:

  • Ensure your ES (Enhanced Security) Key has the correct mappings to your Terminal and Store IDs in the FreedomPay gateway. This action must be taken in your FreedomPay gateway account, not within Recurly.
  • Verify which Tiers the ES Key is mapped to in your Enterprise FreedomPay login. If you have set up special mappings, check the Enterprise Management tab in FreedomPay to ensure it has the correct access.
  • Ensure you are not using a UAT Store ID, Terminal ID, or ES Key in Production Mode (and vice versa).
  • Verify that the correct card types are selected in Recurly. If a card brand is selected in Recurly but not enabled at FreedomPay, contact your FreedomPay representative to add this card type or remove it from your Recurly gateway configuration.
    If you continue to experience issues, please reach out directly to FreedomPay support.

I am using a Point of Sale card terminal. How can I connect this to Recurly?

Recurly does not directly support EMV or Card Present transactions. To set up a Card Present → Recurring Subscription flow, first integrate and build out your card present solution with FreedomPay. Your card present integration should result in a gateway token and your subscription Network Transaction ID (NTID).
Once that is complete, follow this guide to create subscriptions in Recurly and provide the external NTID correctly. Learn more about Card on File in our compliance documentation.

How does information get from my customer to FreedomPay?

In general, all data gets to our gateway partners in the same way. Data flows from one of our supported front-end solutions, such as our API, Recurly.js, or a Hosted page, into Recurly and through to a gateway partner through their API connection.

There are two types of transactions Recurly supports: CIT (Customer Initiated) and MIT (Merchant Initiated). Learn more about Card on File in our compliance documentation.

For Merchant Initiated Transactions, the customer is no longer in session, but their bank is still approving or declining these transactions.

Recurly does not approve or decline transactions. If you would like more information on a decline, we suggest having the customer reach out directly to their bank.

Additional resources

For additional Recurly troubleshooting and how-tos, please search this documentation site, as this FAQ is specific to FreedomPay: Recurly Documentation

Here are some helpful starter pages:

Updated 7 days ago