Skip to main content

BlueSnap Gateway


BlueSnap Gateway

BlueSnap provides payment gateway services that provide online credit card payment processing. This gateway is pre-integrated with Zuora for easy configuration and use with ACH and credit card payments.

Note: The ACH payment method verification request has not been implemented because this operation is not supported by BlueSnap.

To set up the BlueSnap Payment Method Updater service in Zuora, see Configure BlueSnap Payment Method Updater for more information.

Supported Payment Methods

BlueSnap supports the following payment methods:

  • Credit Cards, including:
    • Visa
    • Mastercard
    • Discover
    • American Express
    • JCB (in select countries)
    • Diners Club 
    • Elo
    • Hipercard
    • Argencard
    • Cabal
    • Cencosud
    • Nativa
    • Tarjeta Naranja
    • Tarjeta Shopping
    • Cartão MercadoLibre
  • ACH
  • SEPA

Stored Credential Transactions

BlueSnap gateway includes support for the Stored Credential Transactions framework. For details about the supported payment methods, see Support for stored credential transactions overview.

Supported Payment Operations

The following payment operations are available through BlueSnap:

  • Payment

    The Soft Descriptor field is also supported if you create a SEPA payment.

  • Full Refund

    For SEPA refunds, it takes about 7 days for a SEPA payment to reach a stage when it can be refunded.

  • Multiple, Partial Refund (Referenced Refund)

    BlueSnap's API supports only the first partial refund.  An error will occur if attempting to refund multiple partials.  BlueSnap Support team can be contacted to handle this scenario.

  • Payment Cancel / Auth Reversal (Void)

    This operation is available prior to transaction capture.  Once the transaction is captured, then a Refund request can be used.

Support for 3D Secure 2.0 

See Enable 3DS2 for BlueSnap gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information.

Supported Gateway Reconciliation Event Types

The BlueSnap, Payment API v2.0 gateway integration supports the following Gateway Reconciliation event types for ACH transactions:

  • Payment Settlement
  • Payment Rejection
  • Payment Chargeback
  • Refund Settlement

Payer Name Extraction

While Zuora stores the name of a credit card payment method as a single string, e.g., "John Smith", BlueSnap requires that the first name and last name are sent as two separate fields. To conform to BlueSnap's requirement, Zuora extracts the first name and last name from the single name string. BlueSnap recommends splitting the name by the first space character. 

Configure the BlueSnap Gateway

  1. Navigate to Settings > Payments > Setup Payment Gateway
  2. Click Gateway Type field and select BlueSnap, Payment API v2.0.
  3. Click create gateway
  4. Specify the field values.
  5. Click save gateway information.

BlueSnap Configuration Fields

On the BlueSnap gateway configuration page, configure the fields displayed.

Common Configuration Fields

The following are the common configuration fields you must specify for all gateways. See Setting Up Payment Gateways for the general information about setting up a payment gateway and specifying the values for the common fields: 

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
  • Verify new payment method (optional)
  • Verify updated payment method (optional)

Additional required fields

In addition to the common fields, you must provide the following field values that are specific to the BlueSnap gateway. All the fields are required:

  • Username: Username for the BlueSnap API. Follow the steps at BlueSnap Payment API Credentials to create a username for BlueSnap API.
  • Password: Password for the BlueSnap API. Follow the steps at BlueSnap Payment API Credentials to create a password for BlueSnap API.
  • Soft DescriptorYour DBA (doing business as) name as it appeared on your shopper's credit card statement. This field is required by BlueSnap for each payment request. The example format looks like BLS*CompanyName 2125552222.
    • The CompanyName portion of the descriptor supports 20 alphanumeric and special characters: '&', ',', '.', '-', '#'.
    • The phone number supports 0-9 numbers and should contain your customer support phone number.
  • Merchant's Company Name: This field is required if your customers try to add an ACH payment method and select "Business Checking" as the account type. The BlueSnap payment gateway requires that the Company Name is included in the request if the account type is CORPORATE_CHECKING; otherwise, the gateway will mark the transaction as "failed". The value is a maximum of 50 characters. Zuora recommends you to always specify this field for both existing and new gateway instances.

Additional optional fields

Enable L2

By selecting this checkbox, you are agreeing to send extra information related to a transaction in order to qualify for certain purchasing interchange rates. The extra information is required by the gateway, which must be submitted to achieve Level 2 Interchange rates for Visa and MasterCard.

Enable L3

By selecting this checkbox, you are agreeing to send extra information related to a transaction in order to qualify for certain purchasing interchange rates. The extra information is required by the gateway, which must be submitted to achieve Level 3 Interchange rates for Visa and MasterCard.

Custom Field Commodity Code API Name

This is the API Name of the commodity code custom field. Commodity code is one of the mandatory fields to qualify for Visa Level 3 Interchange rates. This custom field must be created in the product rate plan charge level. 

Enable gateway reconciliation

This checkbox is used to enable the Gateway Reconciliation feature for your BlueSnap gateway instance. The section below provides more details about the gateway reconciliation for BlueSnap.

For general information about the Gateway Reconciliation feature, see Gateway Reconciliation.

Transaction Order Source

To configure a BlueSnap gateway instance to process MOTO payment transactions with Credit Card payment methods, select MOTO for this field. The MOTO payment indicator will be passed to the gateway. All transactions through this gateway instance will be processed as the MOTO payment transactions. The subsequent recurring transactions under the agreement made through the MOTO transaction will be processed by another BlueSnap gateway instance with Transaction Order Source set to None (defer to gateway).

If you only want to indicate a specific transaction as a MOTO transaction without configuring a gateway instance for MOTO transactions, use the TransactionOrderSource gateway option field. See Supported gateway option fields for more information.

Supported Gateway Option Fields

If the support for Level 2 or Level 3 data processing is enabled, you can submit additional information to the BlueSnap gateway using gateway options. Currently, BlueSnap Payment API v2.0 supports the following gateway option fields:

  • InvoiceNum
  • TaxSum
  • TransactionOrderSource: To indicate that the current transaction is a MOTO payment transaction, specify MOTO for this field. If you want to configure a gateway instance, through which all transactions will be processed as MOTO transactions, see Transaction Order Source configuration field.

You can use these fields in Payment Pages 2.0, SOAP API, or the following REST API:

Testing Your Configuration 

We recommend that you test your payment gateway by using both your payment gateway's test and production (live) environments.  Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

You can use the test card information and testing scenarios provided by the gateway vendor to test your integration. See the following documents in BlueSnap Support Guides for details.

Gateway Reconciliation

Select the Enable gateway reconciliation checkbox from the gateway configuration page to enable gateway reconciliation for BlueSnap. The reconciliation job retrieves the reconciliation report from the BlueSnap gateway daily at 3:00 pm PST. 

Zuora uses the /TransactionDetail and /DirectDebit endpoints from BlueSnap to reconcile. It usually takes 3-10 days for these endpoints to be updated with the status of the transaction.

For refund transactions, the BlueSnap, Payment API v2.0 gateway integration only supports the settlement event. The refunds in the Rejected status are ignored.