Integrate your WPF

Integrate your WPF into your store and display it to your customers at checkout.

When you integrate and display the WPF to your customers, you create a payment session through which your customers can pay using the emerchantpay Genesis gateway. If you have an existing storefront, integrate the WPF into your existing platform to create a payment session whenever a customer checks out.


To interact with the Genesis gateway, provide your API credentials using standard HTTP Basic Authentication. Your API credentials are found in the Merchant account creation email you received from emerchantpay support, or by logging in to Genesis.

To get your API credentials in Genesis:

  1. Log in to Genesis.
  2. In the navigation menu, select Configuration > Merchants.
  3. Next to your merchant name, select Terminals.
  4. Select the Terminal through which you would like to process.
  5. The Api access section lists the Api login and Api password fields.
  6. Send your API credentials alongside your initial Create method request:

emerchantpay recommends you authenticate using HTTP Basic Authentication whenever possible. However, you may need to authenticate through other methods depending on the language library you use.

Example of passing API credentials as a file:

use \Genesis\Config as GenesisConfig;

// Point to the directory containing your configuration file
Example of passing API credentials individually:
import com.emerchantpay.gateway.api.constants.Endpoints;
import com.emerchantpay.gateway.api.constants.Environments;;
import com.emerchantpay.gateway.util.Configuration;

// Specify environment and endpoint
Configuration configuration = new Configuration(Environments.STAGING, Endpoints.EMERCHANTPAY);

// Add your API authentication credentials

1. Send an initial Create method request

Create an endpoint from your server that connects to the Genesis gateway and requests a WPF that is displayed to your customer. The endpoint passes information to the Gateway like the transaction amount, currency, customer information, and type of payment.

Example of passing transaction information:
  <?xml version=”1.0″ encoding=”UTF-8″?>
    <usage>40208 concert tickets</usage>
    <description>You are about to buy 3 tickets.</description>
Example of passing billing information:
    <address1>123 Main St.</address1>
Example of passing transaction type details:
    <transaction_type moto=”true” name=”authorize” fx_rate_id=”123″/>
    <transaction_type crypto=”true” name=”sale” fx_rate_id=”123″/>

2. Receive a response

You will receive a Success or Error response to your Create method request. A Success response will contain a redirect_url that contains a unique URL address of the payment session for you to redirect your customer to.

Example of a Create method response:
  <?xml version=”1.0″ encoding=”UTF-8″?>
    <technical_message>Transaction successful!</technical_message>
    <message>Transaction successful!</message>

3. Redirect your customer

Redirect your customer to the unique URL address of the payment session that you received in the redirect_url parameter of your WPF Create method request. Your customer sees your WPF hosted on the emerchantpay servers.

Depending on how your Merchant account is configured, your customer will see a range of payment methods through which to pay for the transaction.

Example of a WPF your customer uses to pay for the transaction: emerchantpay Web Payment Form (WPF)

4. Show a success page

After your customer submits their payment, they will be redirected back to your storefront. Here they will see a success page, failure page, or another type of status page that you host on your server. Status pages are submitted as part of your initial Create method request.

Example of passing status pages as part of the initial Create method request:

5. Verify the payment

In addition to the Success response to your Create request, you will receive a HTTP POST notification for each payment session from the Genesis gateway to the notification_url that you supplied with the Create method request.

The wpf_status parameter shows the result of the transaction.

Example of an Approved notification from the Genesis gateway:

Use the signature field to verify that the notification has been sent by the Genesis gateway. Each session signature is generated by combining the wpf_unique_id and your API password, and generating a SHA-512 hash function of the combined string.

signature = SHA-512 hash value of <wpf_unique_id><API password>

Notification signature examples:
wpf_unique_id API password signature
26aa150ee68b1b2d6758a0e6c44fce4c 50fd87e65eb415f42fb5af4c9cf497662e00b785 c5219b3d385e74496b2b48a549
3f760162ef57a829011e5e2379b3fa17 50fd87e65eb415f42fb5af4c9cf497662e00b785 14519d0db2f7f8f407efccc9b099

After you have verified the notification state and validity, render an XML page containing the transaction’s unique id to acknowledge that you have received the notification.

Example of a notification reply you use to confirm a notification:
<?xml version=”1.0″ encoding=”UTF-8″?>

6. Optional: Reconcile the transaction

Send a reconcile request to the Genesis gateway to get information about a transaction. Reconcile a transaction to verify a successful payment, or to get information about a transaction that has timed out, returned an error, or is in chargeback.

Reconcile a transaction by sending request that contains the unique_id returned by the Create method request.

Example of a Reconcile request:
<?xml version=”1.0″ encoding=”UTF-8″?>