Set up direct server integration

Connect to the emerchantpay payment gateway in a direct server-to-server integration.

To process payments with emerchantpay, send a transaction request to the emerchantpay Genesis gateway each time a customer checks out of your online store. During onboarding, your Account Manager will have assisted you in determining the type of transaction request that is most appropriate for your business.


To send a transaction request, you must first collect your customer’s payment information, and authenticate with the payment gateway using your emerchantpay account credentials.

Collect your customer’s payment information

Present a payment form to your customer to collect the required payment information for the types of payments you intend to offer. This payment information will be passed to the Genesis payment gateway as part of your initial transaction request.

Authenticate with the payment gateway

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, Api password, and Terminal (Token) fields.
  6. Send your API credentials alongside your initial transaction 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.

1. Send an initial transaction request

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

Example of passing transaction information for a card payment:
<?xml version=”1.0″ encoding=”UTF-8″?>
    <usage>40208 concert tickets</usage>
    <card_holder>John Smith</card_holder>
Example of passing billing information:
      <address1>123 Main St.</address1>

2. Receive a response

For both synchronous and asynchronous payment methods, you receive a Success or Error response to your transaction request.

Example of a Success payment response:
  <?xml version=”1.0″ encoding=”UTF-8″?>
    <avs_response_text>Response provided by issuer processor; Address information not verified</avs_response_text>
    <descriptor>Descriptor one</descriptor>

3. Optional: Redirect your customer

If you are using an asynchronous payment method—one that requires input from your customer to complete the transaction—redirect your customer to the URL address of the payment session that you received in the redirect_url parameter of your transaction response.

Example of an asynchronous payment response with a redirect URL:
  <?xml version=”1.0″ encoding=”UTF-8″?>
    <descriptor>Descriptor one</descriptor>

In addition to the transaction response, for an asynchronous payment you will receive a notification from the gateway that informs you of the payment result.

Asynchronous notification

For an asynchronous payment, the result of your customer’s payment is sent as a separate HTTP POST notification from the gateway to the notification_url that you supplied with the transaction request.

Example of a notification:

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

signature = SHA-1 hash value of <unique_id><API password>

Notification signature examples:
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″?>

4. Show a confirmation page

After your customer submits their payment, display a success page, failure page, another type of status page, or even go back to your store. The page that you display should inform your customer of the status of their order, once you have verified it from the transaction response or gateway notification.

Depending on your merchant account setup and type of payment, you may pass status pages as part of the transaction request.

Example of passing status pages as part of the initial transaction request:

Additional actions

There are additional types of requests that you can make to the Genesis gateway before, during, and after the payment transaction.

Capture a transaction

To complete an authorize transaction, send a capture request to transfer the reserved funds from your customer’s account.

Use the unique_id from the authorize request in the reference_id field of the capture request.

Example of a capture request:
  <?xml version=”1.0″ encoding=”UTF-8″?>
    <usage>40208 concert tickets</usage>

Reconcile a 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 a request that contains the unique_id returned by the transaction request.

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