Paysafe Gateway (Optimal Payments Gateway)
The Paysafe Gateway, identified as Optimal Payments Gateway on Engaging Networks, can be used for card payments or Direct Debit payments in Canada (ACH or EFT), Europe (SEPA) or the UK (BACS).
Setting Up Paysafe
To create your live and test gateway:
Log in to your Paysafe account to locate your Account ID, Username, and API Key:
i. To find Account IDs, go to Business > Account Statements and use the drop-down. If you have a Card and Direct Debits enabled, you should see two separate account IDs:
ii. To find your User Name and API Key, go to Developer > API Keys and authenticate to unlock the ‘secret’ key:
When copying the API key, note that the “copy” button in Paysafe will also copy the username. Do not include the username in the API key value in Engaging Networks. Additionally, be aware that the user name and API key are the same whether you’re adding your card or a direct debit gateway.
In Engaging Networks, go to Hello YOURNAME > Account Settings > Gateways
Click ‘New payment gateway’ to create a new entry
The fields are set up as follows:
Field | Description |
|---|---|
Reference name | Paysafe operates separate gateways for card payments and Direct Debits. |
Select gateway | Select the Optimal Payments gateway |
Username | Add the user name from your Paysafe account |
API key | Add the secret key from your Paysafe Account |
Account ID | The account ID from your Paysafe Account. |
Currency | Select the appropriate currency for the gateway. Note that changing this field in Engaging Networks will only change how currency is reported in our platform; otherwise, currency is determined by 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 by using the appropriate field ‘tag’ in your account and added to the form on your page:
Standard Paysafe fields
Payment Type | Field Name | Mandatory (Y/N) | Field Type | Description |
|---|---|---|---|---|
All | Email Address | Y | Alphanumeric | Supporter’s email address |
All | First Name | Y | Alpha | Cardholder’s first name. |
All | Last Name | Y | Alpha | Cardholder’s last name.
|
All | Address 1 | Y | Alphanumeric | Cardholders address |
All | City | Y | Alpha | Cardholders city |
All | Region/State/ | Y | Alpha | Cardholder Region. |
All | ZIP/postal code/postcode | Y | Alphanumeric | The post/postal/zip code of the cardholder |
All | Country | Y | Alpha | Cardholder Country. Always use a 2-character country code as values. |
All | Donation Amount | Y | Numeric | Entered as a whole number or with two decimal places. |
Card payment fields
These fields are required for card payments:
Payment Type | Field Name | Mandatory (Y/N) | Field Type | Description |
|---|---|---|---|---|
Card | Credit Card Number | Y | Token | Credit card number |
Card | Credit Card Expiration | Y | Date | Format must be MM/YYYY. SEPA |
ACH/EFT/SEPA payment fields
These fields are required for Direct Debit payments:
Payment Type | Field Name | Mandatory (Y/N) | Field Type | Description |
|---|---|---|---|---|
ACH/EFT/SEPA | Credit Card Holder Name | Y | Alpha | Paysafe uses this for bank account holders only, as cardholders are captured using the First and Last Name fields. |
ACH/EFT/SEPA | Payment Type | Y | Alpha | ACH or EFT or SEPA |
ACH/EFT/SEPA | Bank Account Type | Y | Alpha | CHECKING or SAVINGS or LOAN (Loan is for SEPA only) |
ACH/EFT/SEPA | Bank Account Number | Y | Numeric | The account number for the payment. |
ACH/EFT/SEPA | Bank Routing Number | Y | Numeric | ACH or EFT: The routing number for the payments must be nine digits for ACH. |
ACH/EFT/SEPA | Bank Name | Y | Alpha | Required for EFT only and must be a numeric value. |
ACH/EFT/SEPA | Recurring Payment | Y | Alpha | Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment. |
ACH/EFT/SEPA | Recurring Frequency | Y - ACH/EFT | Alpha | If ‘Recurring Payment’ is set to ‘Y’. Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. SEPA: If not submitted, will to MONTHLY. |
ACH/EFT/SEPA | Recurring Day | N | Numeric | The day of the month on which the recurring payment should be taken, from 1 to 28. If the field is not submitted, the default recurring payment day will be taken from the “day” of the Recurring Start Date. |
Invalid Characters
To prevent invalid data from being submitted through your forms and causing errors, you can use validators on the form fields. Several built-in validator types can be created to handle standard Alphanumeric data or donation amounts. However, you can also create custom validators using regular expressions. When dealing with payment gateways, pay particular attention to input that could cause problems.
For Paysafe, the following list of characters should never be part of any data submitted as part of the Direct Debit setup, as it will result in an error:
Character | Code | Description |
|---|---|---|
“ | 22 | Double quotes (or speech marks) |
; | 3B | Semicolon |
^ | 5E | Caret, circumflex |
* | 2A | Asterisk |
< | 3C | Less than (or open angled bracket) |
/ | 2F | Slash or divide |
[ | 5B | Opening bracket |
] | 5D | Closing bracket |
\ | 5C | Backslash |
Testing & Troubleshooting Paysafe donation pages
If your gateway is set up in test mode, you can use the test card details below for testing purposes. Further information on testing can be found on the Paysafes Developer website.
Testing using different donation amounts will simulate different response codes from the Paysafe gateway. You can verify that responses are being returned correctly by viewing the supporter record used for testing in Data & Reports > Lookup Supporter.
Test Credit Cards
For test credit cards, use any expiry date set in the future.
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 |
|
Response Codes
For testing these scenarios, you must be using a test gateway and include the decimal before the value. When setting up the donation amounts on your forms, you can use integers with or without the decimal included.
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 cardholder’s credit card company. |
.05 | 402 | 3009 | The issuing bank has declined your request. |
.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 | The issuing bank has declined your request 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 | Our Risk Management department declined the transaction. |
.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 a 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 a 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 |
Troubleshooting
EFT will not work on event pages.
If you’re experiencing issues when trying to process test or live donations after following the setup guide, firstly, verify that customer records are being created in Paysafe and that error messages are being created against the transaction on the supporter record.
Error Code | Possible Issue |
|---|---|
5279: Invalid credentials | The details entered for the Gateway could be incorrect. |
5016: The merchant account submitted with your request could not be found | You have the wrong account ID associated with the payment type you’re attempting. |
7505: The merchantCustomerId provided for this profile has already been used for another profile | Check the customer's status in Paysafe and/or try an alternative email address. |
4001: The card number or email address associated with this transaction is in our negative database. | Check if you’re using a test card on a live gateway or vice versa |
5270: The credentials provided with the request do not have permission to access the data requested. | Check if you’re using a test card on a live gateway or vice versa |
5017: The merchant account submitted with your request is disabled. | Contact Paysafe with your account ID and ask them to enable your account |