The Paysafe Gateway (formerly Optimal Payments)

Using the Paysafe gateway, we can currently process donations from Visa, MasterCard, American Express or Discover credit cards.

Paysafe can also process UK Direct Debits as long as you bank with Barclays. Read this help article for the setup of PDDs with Paysafe. Within the ‘Single Euro Payments Area’ you can also set up direct debit payments using SEPA as the payment type.

In addition to supporting USD, CAD, EUR, GBP and AUD, Paysafe can support these currencies subject to your arrangements with Paysafe.

We strongly recommend that you explicitly confirm the payment methods and currencies available to you with Paysafe before setting up the gateway.

The currency is selected when you set up the gateway with Paysafe – it is not necessary to include a currency form field in your default supporter record, or on your donation pages. It is possible to take single and recurring payments through the same page by including the ‘Recurring payment’ field as a dropdown, radio button, or check box.

Before setting up

Before creating donation pages using the Paysafe gateway you will need to have arranged your merchant account with Paysafe. You will also need to decide what base URL you would like to use for your donation pages, and ensure that a certificate exists for it on our load balancer.

Setting up the gateway

It is recommended that you create and keep two separate gateway records in your account, one for testing and one linked to your live gateway. Donation pages should be linked to a test gateway initially, and then switched to a live gateway before launch. To create each one:

  1. Go to Hello YOURNAME > Account Settings > Gateways

  2. Click ‘New payment gateway’ to create a new entry

  3. The fields are set up as follows:

Field

Description

Field

Description

Reference name

A unique name for the gateway. It is a good idea for the name to include the type of gateway (eg. Optimal Payments Live), the currency, and whether it is a live or test gateway.

Select gateway

Select the Optimal Payments gateway

Username

Your Paysafe account user name.

API key

Paysafe will provide this, along with your Account ID. 

When copying the API key, note that the “Copy” button in Paysafe will also copy the username. Please be careful not to include this in the API key value in Engaging Networks

Account ID

See above.

Currency

Select the appropriate currency for the gateway, subject to what you have agreed with Paysafe. Note that changing this field in Engaging Networks will only change how currency is reported in our platform. The actual currency of donations is determined by the currency of your Paysafe account.

Test mode

Should be checked for a test gateway, but must be unchecked for a gateway that will accept live donations.

 

Form Fields

The following fields should be set up in the default supporter record with the appropriate field ‘tag’ and added to your donation form.

Standard fields required for every Paysafe donation page

Field

Mandatory

Field type

Description

Field

Mandatory

Field type

Description

Email Address

Mandatory

Alphanumeric

Supporter’s email address

First Name

Mandatory

 

Alpha

The cardholder’s first name.

Last Name

Mandatory

Alpha

The cardholder’s last name.

 

Address 1

Mandatory

 

Alphanumeric

The first address line of the cardholder

City

Mandatory

 

Alpha

The address city of the cardholder

Region

Mandatory

 

Alpha

The address region of the cardholder. For the US and Canada, this should be a 2 character code for the state/province. For other countries, it is a free text field.

ZIP/postal code/postcode

Mandatory

 

Alphanumeric

The post/postal/zip code of the cardholder

Country

Mandatory

Alpha

The country of the cardholder. This should be a 2 character code for the country.

Donation Amount

Mandatory

 

Numeric

May be entered as a whole number, or with two decimal places. Eg. Twelve dollars may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types ‚Äì see below.

Adding fields for card payments

Field

Mandatory

Field type

Description

Field

Mandatory

Field type

Description

Credit Card Number

Mandatory

Token

Credit card number w/o spaces

Credit Card Expiration

Mandatory

Date

Format must be MM/YYYY. It is strongly recommended that you use the ‘split select’ field type for this form field. See below for details.

Additional fields for ACH/EFT payments

Additional fields are required for Canadian clients. Please see here for more information.

Field

Mandatory

Field type

Description

Field

Mandatory

Field type

Description

Payment Type

Mandatory

Alpha

ACH or EFT

Bank Account Type

Mandatory

Alpha

Checking or Savings

Bank Account Number

Mandatory

Numeric

The account number for the payment.

Bank Routing/ Transit Number

Mandatory

Numeric

The routing number for the payment. Must be 9-digits for ACH.

Bank Name

Mandatory

Alpha

Required for EFT only to pass institution and bank number.

Additional Required Fields for Recurring Payments

If you want to accept recurring payments and have confirmed with Paysafe that you have this option enabled for your account, in addition to the credit card fields you will need to add the following:

Field

Mandatory

Field type

Field

Mandatory

Field type

Recurring Payment

Alpha

Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment.

Recurring Frequency

Alpha

If ‘Recurring Payment’ is set to ‘Y’. Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. Please see the notes below on ‘select’ field types for details of ways of presenting these fields to supporters.

Recurring Day

Numeric

The day of the month on which the recurring payment should be taken, from 1-28.

Testing Paysafe donation pages

Provided that you are using a gateway set up in test mode, you can use the following details during the testing process. Entering different donation amounts will simulate different scenarios from the Paysafe gateway as detailed below. You will be able to check responses are being returned correctly by viewing the supporter record used for testing in Data & Reports > Lookup supporter.

Test Credit Cards

Card type

Test card number

Test card number

Card type

Test card number

Test card number

Visa

4530910000012345

4510150000000321

 

MasterCard Debit (Maestro)

6759950000000162

5036150000001115

 

MasterCard

5191330000004415

5191330000004415

 

American Express

370123456789017

375529360131002

 

Discover

6011234567890123

 

 

 

When testing with the test credit cards you can use any expiry date set in the future.

Simulating Response Codes (errors)

With the Paysafe gateway in test mode, you can use the table below to simulate different responses by entering one of the donation amounts listed.

Donation amount

HTTPS status code

Error code

Response

Donation amount

HTTPS status code

Error code

Response

.01

200

 

Approved

.04

402

3015

The bank has requested that you process the transaction manually by calling the card holder’s credit card company.

.05

402

3009

Your request has been declined by the issuing bank.

.06

500

1007

Clearing house timeout (although the simulator returns immediately; if delay is desired, see amount 96).

.11

402

3022

The card has been declined due to insufficient funds.

.12

402

3023

Your request has been declined by the issuing bank due to its proprietary card activity regulations.

.13

402

3024

Your request has been declined because the issuing bank does not permit the transaction for this card.

.20

500

1007

An internal error occurred.

.23

402

4002

The transaction was declined by our Risk Management department.

.24

402

3007

Your request has failed the AVS check.

.25

402

4001

The card number or email address associated with this transaction is in our negative database.

.90

200

 

Approved with 5-second delay

.91

200

 

Approved with 10-second delay

.92

200

 

Approved with 15-second delay

.93

200

 

Approved with 20-second delay

.94

200

 

Approved with 25-second delay

.95

200

 

Approved with 30-second delay

.96

500

1007

Declined with 35-second delay. Transaction timed out after 30 seconds.

1.00

200

 

Approved