Simulator (Testing connector)

The Simulator is an adapter for integration & testing purposes only. No real transaction will be performed at any payment provider.

Test data

Credit cards

Direct Debit IBANs

You can use any IBAN you like.

The last four digits will control the result:

Example: AT00 0000 0000 0000 1111 => Successful transaction

Simulate pending status change

You may simulate a transaction status change by adding the extraData pendingOutcome. Do note that this simulation may only be evoked by submitting an IBAN with outcome pending (ending with 2222) via the simulator payment page.

The status will change in approx. 5 minutes after submission.

Adyen

Payment Methods

Additional parameters

none

AmazonPayments

Payment Methods

Integration guide

AmazonPayments require you to display the Amazon Widget on your Checkout page. This is handled by the payment.js integration.

​1. Embed the payment.min.js in your page

<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.min.js"></script>

​2. Provide DIV elements on your page for the various Amazon widgets

<div id='loginButton'></div>
<div id='addressWidgetDiv'></div>
<div id='walletWidgetDiv'></div>
<div id='consentWidgetDiv'></div>

​3. Initialize the payment.js with the following parameters:

• publicIntegrationKey of the AmazonPayments connector
• IDs of the DIV elements
• Javascript function to handle AmazonPayments events
• Additional parameters (see below in example, refer to AmazonPayments Documentation for possible options)
• Javascript function to handle initialization completion

<script type="text/javascript">
    var payment = new PaymentJs("1.2");

    amazonEventHandler = function(eventName, data) {
        //handle events here
    }

    completeHandler = function(paymentJsInstance) {
        //you can do additional stuff in here, e.g. make the DIVs visible if they were hidden
    }

    var additionalParameters = {
        buttonType: "PwA", // Type of AmazonPayments Button
        buttonColor: "Gold", // Color of AmazonPayments Button
        buttonSize: "small", // Size of AmazonPayments Button
        loginPopup: true, // Use Pop-Up for logging customers in into their Amazon account
        autoShow: true, // automatically show AmazonPayments Login button once ready
        loginRedirectUrl: // if loginPopup is false, provide the URL to get back redirected after customer logged in to Amazon
    };

    payment.initAmazon(
        'public-integration-key',
        'loginButton', // mandatory
        'addressWidgetDiv', //optional
        'walletWidgetDiv', // mandatory
        'consentWidgetDiv', // optional, necessary for recurring transactions
        amazonEventHandler,
        additionalParameters,
        completeHandler
    );
</script>

​4. You can react on the various AmazonPayments events in your amazonEventHandler.

If you set autoShow to true, the various widget will be automatically shown to fulfill the payment flow.

If set to false, you have to take care about that on your own.

The following events will be fired:

• login.ready: ready to show login button
• login.shown: login button was shown
• login.error: failed to show login button, data will include code and message with Amazon error information
• login.complete: customer successfully logged in
• addressBook.error: failed to show addressBook widget, data will include code and message with Amazon error information
• addressBook.shown: addressBook widget was shown
• addressBook.selected: customer has chosen/changed the delivery address
• wallet.error: failed to show wallet widget, data will include code and message with Amazon error information
• wallet.selected: customer has chosen a wallet
• wallet.shown: wallet widget was shown
• consent.complete: consent was granted by customer
• consent.incomplete: consent is not yet granted by customer
• consent.error: failed to show consent widget, data will include code and message with Amazon error information

The individual widgets can be shown and hidden with payment.js methods.

<script type="text/javascript">
    // show/hide login button
    payment.amazon().login.show();
    payment.amazon().login.hide();

    // show/hide addressBook widget
    payment.amazon().addressBook.show();
    payment.amazon().addressBook.hide();

    // show/hide wallet widget
    payment.amazon().wallet.show();
    payment.amazon().wallet.hide();

    // show/hide consent widget
    payment.amazon().consent.show();
    payment.amazon().consent.hide();

</script>

​5. Once wallet.selected (or consent.complete to enable recurring transactions) was fired, and the customer confirms the order on your checkout page, you must call the tokenize method to obtain a payment token. This token is then to be used in the transactionToken element of the Debit call to the Transaction API.

<script type="text/javascript">
    payment.tokenize(
        {}, //optional additional data
        function(token) {
            //Submit token to your server and perform transaction through Transaction API

            //Example:
            $('#transaction_token').val(token); //store the transaction token
            $('#payment_form').get(0).submit(); //submit the form
        },
        function(errors) {
            //show/handle errors
        }
    );
</script>

ApplePay

ApplePay is not an adapter itself, but a common type of payment supported by some of the listed adapters.

Prerequisites

For processing transactions with ApplePay tokens, the Gateway has to be configured with your Payment Processing certificate first. Please ask your Gateway administrator to do so.

Instruction on how to acquire this certificate can be found directly in the Apple documentation: https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server

Transaction Processing

For ApplePay transactions acquire a Payment Token through your iOS App, or ApplePay on the Web. (Refer to https://developer.apple.com/documentation/passkit & https://developer.apple.com/documentation/apple_pay_on_the_web).

The resulting token must be submitted in the transactionToken element of the Debit/Preauthorize, prefixed with applepay:

Example:

<transactionToken>applepay:{"token":{"paymentData":{"version":"EC_v1","data":"...","signature":"...","publicKeyHash":"...","transactionId":"...."}},"paymentMethod":{"displayName":"Some card","network":"MasterCard","type":"debit"},"transactionIdentifier":"..."}}</transactionToken>

Authorize.net

Payment Methods

Additional Parameters

none

BillPay

Payment Methods

Note: any Debit transaction automatically creates the authorization & the invoice on BillPay side.

Mandatory parameters

Braintree

Payment Methods

Integration guide

Braintree requires you to display the PayPal Button on your Checkout page. This is handled by the payment.js integration.

​1. Embed the payment.min.js in your page

<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.min.js"></script>

​2. Provide a DIV element on your page for the PayPal button

<div id='paypalButtonDiv'></div>

​3. Initialize the payment.js with the following parameters:

• ID of the DIV element
• Boolean option to state whether device data should be gathered (needed for merchant initiated Card-On-File transactions)
• Javascript function to handle payment completion
• Javascript function to handle error events
• Javascript function to handle cancellation events
• PayPal options (see below in example, refer to Braintree Documentation for possible options. The option 'flow' is set to 'vault' automatically)

<script type="text/javascript">
    var payment = new PaymentJs("1.2");

    errorHandler = function(error) {
        //handle error events here
    }

    cancellationHandler = function(data) {
        //handle cancellation event here - called if user cancelled payment process
    }

    completeHandler = function(paymentNonce, deviceData) {
        //send the paymentNonce to Ixopay via the transactionToken parameter
        //send deviceData to Ixopay via the extraData.deviceData parameter if the parameter 'gatherDeviceData' was set to true
    }

    var paypalOptions = {
        amount: "9.99",
        currency: "EUR"
    };

    payment.initBraintreePaypal(
        'public-integration-key',
        'paypal-button-div',
        false, // gatherDeviceData, set true for merchant initiated card-on-file transactions
        completeHandler,
        errorHandler,
        paypalOptions
    );
</script>

​4. You can now call the Transaction API with the transaction token set to the paymentNonce returned to the completeHandler.

If you set gatherDeviceData to true, the completeHandler will receive a second parameter deviceData which can be sent via the Transaction API using the extraData.deviceData parameter.

If set to false, device data will not be gathered and the deviceData parameter will be null.

Collecting device data is only required for Card-On-File transactions.

Transaction API Additional Parameters

When sending the payment token received by the completeHandler to the Transaction API, the following extraData keys can be used:

Customer ExtraData Parameters:

Customer Identification Mandatory

The parameter customer.identification is mandatory in the following cases:

• When creating a new register transaction
• When creating a debit or preauthorize transaction with the flag withRegister
• When creating a merchant initiated Card-On-File transaction

Cardeta

Payment Methods

Additional Mandatory Parameters

CashFlows

Payment Methods

Additional parameters

CheckoutCom

Payment Methods

Additional Parameters

none

CKB

Payment Methods

Additional Parameters

Clearhaus

Payment Methods

Additional Parameters

none

CM

Payment Methods

Additional parameters

CoinGate

Payment Methods

Additional Parameters

none

Credorax

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Dalenys

Payment Methods

Additional Parameters

• description (required)
• useragent (extra data, required):
  The browser's useragent (even for recurring transactions).
• descriptor (extra data, optional): needs to be enabled on Daleny's side too.
• identification (customer, required)
• email (customer, required)
• IP address (customer, required)
• Reference Transaction (maybe required):
  Depending on your MCC, it might be required to reference a 3DS authed transaction for payouts.

3D-Secure Verification parameters are supported, however MANDATORY will behave like OPTIONAL. That is, if the card is not enrolled for 3DS authentication, the transaction will pass unauthenticated.

Dimoco

Payment Methods

Additional Parameters

none

Options Request

EPS

For EPS you can retrieve the bank list via the Options request identifier epsBankList. You can display this list to your customer in order to pre-select the desired bank.

The result contains a list of banks available for EPS, with BIC code as key and bank name as value. The chosen BIC code of the chosen bank should then be passed as bic element in the IbanCustomer element of the XML.

dLocal

Payment Methods

Additional Parameters

Credit card

Note: 3D-Secure behaviour is dependent on dLocal's configuration

APM & BankTransfer

Payouts

Depending on the country and receiving bank, a variety of additional parameter may be required (refer to dLocal's documentation).

Options Request

Debit - BankTransfer

For BankTransfer you can retrieve a list of available banks in a country via the Options request identifier getBankList. You can display this list to your customer having him selecting his bank. The selected bank code should be submitted as bank_id in extra data.

EasyPay (ePay.bg)

Payment Methods

Additional Parameters

• invoice (optional):
  If missing, a random id will be generated. The invoice will always be returned in the response.
• success URL (required for redirect)
• cancel URL (required for redirect)

Ecommpay

Because of a restriction on Ecommpay side, you need to set the particular setting "Accept postbacks from other connectors (list GUIDs comma-separated)" inside the connector where you passed the notification URL to Ecommpay if you want to configure multiple connectors.

As value you need to pass the connector ID from all other Ecommpay connectors of the same account, example: "CO-8ce8-4ed7-e9d9-9261-715a-fad8,CO-02c7-62dd-d0e8-5918-6373-7e75". With this setting, all connectors will work with the same notification URL. This setting only needs to be set on the connector where you passed the notification URL to Ecommpay.

If you only have one connector per Ecommpay account, you don't need to configure this setting.

Payment Methods

*Payout/Refund doesn't require any customer interaction or redirection.

**For Alipay refunds you have to activate the 'merchant_refund_id' field on Ecommpay side. Please talk to your Ecommpay Account Manager for further information.

Additional parameters for BankTransfer Debit

Additional parameters for BankTransfer Payout

• To retrieve a list of bank identifiers you need to send an options request with the identifier debit-bank-list or payout-bank-list and as parameter the bank name (available: vietnam, malaysia, philippines, indonesia, thailand).

** To retrieve a list of region identifiers you need to send an options request with the identifier region-list and as parameter the bank name (available: vietnam, malaysia, philippines, indonesia, thailand).

You can find more information about the options request here: Options Request

Additional parameters for AliPay / DOKU Wallet / Nganluong Wallet Debit

Additional parameters for China Union Pay Payout

• To retrieve a list of bank identifiers you need to send an options request with the identifier debit-bank-list or payout-bank-list and as parameter the bank name (available: vietnam, malaysia, philippines, indonesia, thailand).

** To retrieve a list of region identifiers you need to send an options request with the identifier region-list and as parameter the bank name (available: vietnam, malaysia, philippines, indonesia, thailand).

You can find more information about the options request here: Options Request

Additional parameters for Alipay Refund

Additional parameters for Nganluong Wallet Payout

Additional parameters for DOKU Wallet Payout

EmerchantPay

Payment Methods

Additional Parameters

none

ESR / SwissQR Bill

Payment Methods

Additional parameters

• additionalId1: mandatory - must contain the reference number for the bill.
• description: optional - description for the bill
• customer.firstName: optional
• customer.lastName: optional
• customer.billingAddress1: optional
• customer.billingPostcode: optional
• customer.billingCity: optional
• customer.billingCountry: optional

Return Values

In the response you will find the key qrCode within the extraData element. This contains the Base64-encoded Image for the QR Code.

expressÜberweisung

Payment Methods

Additional parameters

Finance Wide

Payment Methods

Additional Parameters

3D-Secure Verification parameters are ignored entirely, however the underlying gateway manages and changes the behavior of 3D-Secure requirements on demand.

Finrax

Payment Methods

Additional Parameters

You can use the following extraData keys, which will be passed in the corresponding fields to Finrax:

FinTecSystems

Payment Methods

Additional parameters

Fortumo

Payment Methods

Additional Parameters

none

GiroSolutions

Payment Methods

Additional Parameters

none

GooglePay™

GooglePay is not an adapter itself, but a common type of payment supported by some of the listed adapters.

Prerequisites

You can use GooglePay in your Android app or on your website.

To integrate GooglePay in your Android app please refer to the following links:

• Google Pay Android developer documentation
• Google Pay Android integration checklist
• Google Pay Android brand guidelines

To integrate GooglePay in your website please refer to the following links:

• Google Pay Web developer documentation
• Google Pay Web integration checklist
• Google Pay Web brand guidlines

Transaction Processing

For GooglePay transactions acquire a Payment Token through your Android app, or on your website.

Use the following parameters when sending a request to Google and replace YOUR_MERCHANT_ID with the GUID of your merchant: gateway = "YOUR_GATEWAY_PARAMETER" gatewayMerchantId = "YOUR_MERCHANT_ID"

If you are unsure about your gateway parameter, please contact your account manager.

The resulting token must be submitted in the transactionToken element of the Debit/Preauthorize, prefixed with googlepay:

Example: <transactionToken>googlepay:{"signature":"...","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"...\",\"keyExpiration\":\"...\"}","signatures":["..."]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"...\",\"ephemeralPublicKey\":\"...\",\"tag\":\"...\"}"}</transactionToken>

Card Parameters

A billing address is not required for processing transactions, therefore no billing address parameters need to be given with a card.

Supported Card Authentication Methods

• PAN_ONLY
• CRYPTOGRAM_3DS

Supported Card Networks

• AMEX
• DISCOVER
• INTERAC
• JCB
• MASTERCARD
• VISA

Ingenico Connect

Payment Methods

Required parameters

• customer.billingCountry: mandatory
• customer.identification: mandatory for register, debit with register, authorization with register
• transaction.indicator: mandatory for card on file, card on file merchant initiated, recurring (see Recurring Transactions)

Webhooks

To use webhooks with Ingenico Connect you have to register the webhooks callback URL inside the Ingenico Connect Interface or talk with your account managerr on Ingenico side.

Testcards

3DS Test cards can be found here:

Ingenico Connect Test Cases

iSignThis

Payment Methods

Additional parameters

• customer.identification: mandatory
• customer.firstName: mandatory
• customer.lastName: mandatory
• customer.email: mandatory
• customer.ipAddress: mandatory

Kalixa

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Kassa Compleet

Payment Methods

Additional Parameters

none

Klarna

Payment Methods

Additional Parameters

none

Mastercard Payment Gateway Services

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

MasterPayment

Payment Methods

Additional Parameters

none

MocoPay

Payment Methods

Additional Parameters

none

Mollie

Payment Methods

Additional Parameters

none

MultiSafePay

Following features has to be enabled from your Multisafepay Account Manager

• 0 Cent Authorization if you want to use register without the pre-authorization / void workflow
• Flexible 3ds if you want to control when the user has to 3DS authenticate

Payment Methods

Additional Parameters

none

Neteller

To fully set up the Neteller Connector you will have to fulfill the following (mandatory) steps:

• Enter your Private Key Username & Private Key Password in the "Extra Data" Fields. (Merchants / User / Connectors / Neteller / Config / Extra Data).

  • You can retrieve your Private and Public keys via the NETELLER Merchant Dashboard (Developer / Apps; You might need to "Add application")
  • Copy the Username & Password from the Section "PRIVATE Key".

  
  

• Inform Paysafe ([email protected]) to set up your Webhook URL.

  • You can retrieve your Webhook URL via the Connector Settings (Merchants / User / Connectors / Neteller / Base Data / Notification Url).
  • Send them the given "Notification URL".

Payment Methods

Additional Parameters

NMI (Network Merchants Integrated)

Payment Methods

Additional Parameters

none

Ochapay

Payment Methods

Additional Parameters

none

Pago46

Payment Methods

Additional Parameters

none

Options Request

Paying an Agent (sandbox only)

In order to mock the event on the sandbox that a customer has payed an agent an Options Request is required. Use payAgent as identifier and pass the adapter's transaction ID in the transaction parameter.

Paymentwall PCI

Payment Methods

Recurring payments

The same customer identification must be used for all affected transactions (for the initial, as well as for subsequent transactions).

Additional Parameters

• 3D-Secure Verification Parameters

Required Parameters

• productId
• productName
• identification (Customer)
• email (Customer)
• ipAddress (Customer)
• firstName (Customer)
• lastName (Customer)

Paymentwall

Payment Methods

Additional Parameters

• email (Customer)
• productId
• productName
• successUrl
• errorUrl

PayOn

Payment Methods

Additional Parameters

none

PayPal

Payment Methods

PayPal Payment Types

PayPal supports different kind of payments:

• Sale: Will charge the user for the full amount of the transaction
• Authorization: Only authorizes the user's payment instrument. This needs afterwards to be captured with a Capture request
• Order: Only gets consent from user for this particular order. No funds will be authorized

A Debit will always use the Sale type. A Preauthorize will by default use the Authorization type.

You can control the behavior for Preauthorize by sending the paypalPaymentAction parameter (see below).

Additional Parameters

You can use the following extraData keys, which will be passed in the corresponding fields to PayPal:

Items

If submitting items, the following fields are Mandatory:

Item ExtraData Parameters:

Paysafecard

Payment Methods

Additional Parameters

none

Powercash21

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Mandatory Parameters

Trustly

PPRO

Payment Methods

Additional Parameters

none

Qualpay

Payment Methods

Additional Parameters

none

SafeCharge

Payment Methods

Additional Parameters

none

SecureTrading

Payment Methods

Additional Parameters

none

SepaExpress

Payment Methods

Depending on your setup SepaExpress can be used as Server-to-Server only integration, or with an iFrame Payment form.

For the Server-to-Server integration the IBAN must be sent within the customer details, otherwise the customer will enter its IBAN within the iFrame form.

Additional parameters

• additionalId1: must contain the Order ID. One Order ID can contain more than one transaction! Relevant for SEPAexpress to detect the sequence of the transaction and for refunds.
• additionalId2: for recurring transactions it must contain the Contract ID: A unique identifier of the user or contract of the user on merchant level. One Contract ID can contain more than one Order IDs! Relevant to detect the sequence of the transaction.
• description: mandatory
• customer.firstName: mandatory
• customer.lastName: mandatory
• customer.iban: mandatory (for Server-to-Server)
• customer.bic: optional
• customer.mandateId: mandatory
• customer.mandateDate: mandatory

Shimotomo

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Depending on your merchant account, additional parameters might be mandatory.

Skrill

Payment Methods

Additional Parameters

Sofort

Payment Methods

*Refund is only available in BE, NL

Additional Parameters

iDeal debit

*For the BIC you may do an Options Request using the identifier iDealBankList. It will return a list of available banks for iDeal which you should render to let the customer pick a bank. You should then pass the selected bank code as bic element inside IbanCustomer.

iDeal refund

Spreedly

Payment Methods

Additional Parameters

none

Stripe

Payment Methods

Additional Parameters

none

TECS

Payment Methods

Additional Parameters

none

TNG

Payment Methods

Additional Parameters

none

Options Request

Obtaining a QR code

In order to generate a QR code which shall be displayed by the payer in the app, an Options Request is required. Use requestTopupCode as identifier and pass the customer's ID in the customerId parameter.

Truevo

Payment Methods

Additional Parameters

none

Trustly

Payment Methods

Additional parameters

WeAccept

Payment Methods

Additional parameters

*) only certain states and cities within Egypt are supported.
Refer to WeAccept's cash annex.

Wirecard

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Worldpay

Payment Methods

Additional Parameters

none

Worldpay Access

Payment Methods

Additional Parameters

Creditcard

• 3D-Secure Verification Parameters

Worldpay Express

Payment Methods

Additional Parameters

none

Zip Payments

Payment Methods

Additional Parameters

Wallet (Debit & Preauthorize)

Mandatory Parameters

Wallet (Debit & Preauthorize)

Integration through ZIP Widget

The integration from the Gateway works by default through the redirect flow from ZipPayments. You can also integrate by using ZIP's Widget solution ("Lightbox Checkbout Library"), but you have to handle the Javascript part on your own. The Gateway returns you the following extraData values upon the initial Debit or Preauthorize call, which you will need for the ZIP Widget:

• zipId
• zipUri
• zipRedirectUri

You will have to use these values within the your HTTP endpoint which is called by the ZIP Widget:

{
  "id": "value of extraData.zipId",
  "uri": "value of extraData.zipUri",
  "redirect_uri": "value of extraData.zipRedirectUri"
}