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 proceed with this solution, you must have an emerchantpay merchant account. Apply for a merchant account by filling out and submitting this contact form.

You will be assigned an emerchantpay Account Manager, who will provide you with credentials and assist you with any of emerchantpay’s payment solutions.

To integrate, connect to the Genesis gateway using the emerchantpay Processing API. You should have a working knowledge of web programming languages, HTTP methods in XML and JSON formats, and UTF8 encoding. Use the Genesis SDK libraries with code samples to integrate with the gateway in a range of languages.

For a solution that requires less development overhead, accept payments through the emerchantpay Web Payment Form (WPF). Contact your Account Manager and tell them you want to accept payments through the WPF, and refer to the WPF API.

Prerequisites

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.

To collect an store sensitive customer data, your server must meet the highest level of compliance: SAQ D. For a solution that requires a lower compliance level, process your customer data on a like the emerchantpay Web Payment Form (WPF).

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.

If you do not have a Merchant account, see First steps.

To get your API credentials in Genesis:

You will first be given access to the Genesis staging environment, where you will find your staging environment credentials to initially set up and test your integration. Once you are ready to move to production and accept live payments, authenticate using your Genesis production environment and credentials, and set your endpoint to PRODUCTION.

Log in to Genesis.
In the navigation menu, select Configuration > Merchants.
Next to your merchant name, select Terminals.
Select the Terminal through which you would like to process.
The Api access section lists the Api login, Api password, and Terminal (Token) fields.
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″?>
  <payment_transaction>
    <transaction_type>authorize</transaction_type>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <remote_ip>123.456.789.0</remote_ip>
    <amount>100</amount>
    <currency>USD</currency>
    <card_holder>John Smith</card_holder>
    <card_number>4200000000000000</card_number>
    <expiration_month>12</expiration_month>
    <expiration_year>2023</expiration_year>
    <cvv>123</cvv>
    <customer_email>jsmith@example.com</customer_email>
    <customer_phone>+001234567890</customer_phone>

Example of passing billing information:

    <billing_address>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <address1>123 Main St.</address1>
      <zip_code>12345</zip_code>
      <city>London</city>
      <country>UK</country>
    </billing_address>
  </payment_transaction>

See the API documentation for the complete list of parameters required as part of a transaction request.

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″?>
  <payment_response>
    <transaction_type>authorize</transaction_type>
    <status>approved</status>
    <mode>live</mode>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
    <consumer_id>123456</consumer_id>
    <token>ee946db8-d7db-4bb7-b608-b65b153e127d</token>
    <avs_response_code>5I</avs_response_code>
    <avs_response_text>Response provided by issuer processor; Address information not verified</avs_response_text>
    <cvv_result_code>M</cvv_result_code>
    <authorization_code>345678</authorization_code>
    <retrieval_reference_number>016813015184</retrieval_reference_number>
    <response_code>00</response_code>
    <timestamp>2022-07-11T14:12:42Z</timestamp>
    <descriptor>Descriptor one</descriptor>
    <amount>100</amount>
    <currency>USD</currency>
    <sent_to_acquirer>true</sent_to_acquirer>
    <scheme_transaction_identifier>019091214161031</scheme_transaction_identifier>
    <scheme_settlement_date>0712</scheme_settlement_date>
    <scheme_response_code>00</scheme_response_code>
  </payment_response>

Depending on the payment method used, the response may contain a redirect_url address. Payments where you redirect your customer to complete the transaction are known as asynchronous transactions. See redirect your customer for information on how to process these payments.

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″?>
  <payment_response>
    <transaction_type>authorize3d</transaction_type>
    <status>pending_async</status>
    <mode>live</mode>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
    <consumer_id>123456</consumer_id>
    <token>ee946db8-d7db-4bb7-b608-b65b153e127d</token>
    <redirect_url>https://staging.gate.emerchantpay.net/threeds/authentication/44177a21403427eb96664a6d7e5d5d48</redirect_url>
    <redirect_url_type>3ds_v1_payer_authentication</redirect_url_type>
    <timestamp>2022-07-11T14:12:45Z</timestamp>
    <descriptor>Descriptor one</descriptor>
    <amount>100</amount>
    <currency>USD</currency>
    <sent_to_acquirer>false</sent_to_acquirer>
  </payment_response>

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.

Because an asynchronous transaction relies on customer input, the notification could be delayed until your customer completes the payment.

Example of a notification:

?transaction_id=82803B4C-70CC-43BD-8B21-FD0395285B40
&unique_id=44177a21403427eb96664a6d7e5d5d48
&transaction_type=authorize3d
&terminal_token=394f2ebc3646d3c017fa1e1cbc4a1e20
&status=approved
&amount=500
&signature=088e16a1019277b15d58faf0541e11910eb756f6
&consumer_id=123456
&token=ee946db8-d7db-4bb7-b608-b65b153e127d
&eci=05
&avs_response_code=5I
&avs_response_text=Response+provided+by+issuer+processor%3B+Address+information+not+verified
&cvv_result_code=M
&scheme_response_code=00
&scheme_transaction_identifier=MCS267BG0
&scheme_settlement_date=1103

The status field provides you with information on the outcome of the transaction. See Transaction States for more information about transaction statuses.

For the full list of notification parameters, see Notifications.

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″?>
<notification_echo>
  <unique_id>3f760162ef57a829011e5e2379b3fa17</unique_id>
</notification_echo>

Although the notification and confirmation method is enough to verify that the transaction is successful, emerchantpay recommends that you always perform a reconcile.

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:

<notification_url>https://www.example.com/notification</notification_url>
<return_success_url>http://www.example.com/success</return_success_url>
<return_failure_url>http://www.example.com/failure</return_failure_url>
<return_cancel_url>http://www.example.com/cancel</return_cancel_url>
<return_pending_url>http://www.example.com/pending</return_pending_url>

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″?>
  <payment_transaction>
    <transaction_type>capture</transaction_type>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <remote_ip>123.456.789.0</remote_ip>
    <reference_id>43672</reference_id>
    <amount>100</amount>
    <currency>USD</currency>
  </payment_transaction>

You can only capture funds reserved through a successful authorize request for the same transaction on the same terminal. See the capture API documentation for more information and code samples.

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″?>
  <reconcile>
    <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
  </reconcile>

See the reconcile API documentation for the complete list of reconcile parameters and code samples.