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.
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:
- 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:
Example of passing billing information:
<?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>email@example.com</customer_email> <customer_phone>+001234567890</customer_phone>
<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>
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>
redirect_urladdress. 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.
<?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.
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.
?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
statusfield provides you with information on the outcome of the transaction. See Transaction States for more information about transaction statuses.
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.
Notification signature examples:
signature = SHA-1 hash value of
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>
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>
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.
unique_id from the authorize request in the
reference_id field of the 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>
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.
<?xml version=”1.0″ encoding=”UTF-8″?> <reconcile> <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id> </reconcile>