NAV Navbar
Logo
JavaScript PHP

Introduction

This is the API documentation and implementation guide for the XTECH Payment Gateway.

Each Merchant will be handed an API key, outgoing key and incoming key. The Merchant should specify a unique order_id for each transaction. This order_id will be included in the response together with XTECH’s unique transaction_id.

The merchant is identified and authenticated by the API key and a checksum calculated with request parameters and the outgoing key. The API key and incoming/outgoing keys should be treated carefully and not revealed to outsiders. There are seperate API key for our test and production environment.

To make requests use the following URLs:

The production API URLs must only be used for actual live payments.

The API accepts POST requests and returns response data in JSON format. Some payment methods involve redirecting the user to the payment schemes’ website, in which case the response includes instructions about whether to use GET or POST redirection and what special parameters to include. Payment methods that involve redirection require success and error URLs to be defined.

We have examples provided in PHP and JS. More languages will be added. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Payment Methods

Credit Card

When paying with credit card, the merchant’s web shop redirects the user to the payment form hosted by XTECH, where card data is entered. After completing the payment, the user is redirected back to the merchant’s website. If the credit card payment requires 3-D verification, XTECH will take care of redirecting the user to the bank’s website for extra verification steps, so the payment does not look different to the merchant in any way.

This method can also be used inside an iframe on the merchant’s website, so the user never leaves the merchant’s page. After completing the payment, the web page in the merchant’s success/error URL can include a JavaScript code snippet that breaks out of the iframe if needed.

SOFORT Uberweisung

SOFORT Uberweisung is an online payment service which is offered by SOFORT GmbH. It redirects the user to a website hosted by SOFORT where they can complete the transaction by entering their bank account information and login credentials. The user confirms the transaction with a TAN, after which the browser is redirected back to the merchant’s website.

SOFORT redirects the user using a GET request to a URL specifically generated for the transaction.

PayPal

PayPal is an online payment service offered by PayPal Inc. Technically it is very similar to SOFORT: the user is redirected to a payment site hosted by PayPal and returns back to the Merchant’s site after completing the transaction.

For recurring transactions PayPal Reference Transactions are used. This is a feature PayPal only makes available on explicit request by the Merchant.

Payment Requests

A valid payment request (HTTP POST) consists of a set of mandatory payment request parameters. Optional parameters can be used to alter default values or to provide additional data.

API end points:

Mandatory Request Parameters

$params = array(
   "api_key" => "aab1fbbca555e0e70c27",
   "payment_type" => "cc",
   "order_id" => "order 456",
   "amount" => "17.50",
   "first_name" => "Joanne",
   "last_name" =>  "Smith",
   "address" => "Breite Str. 144a",
   "postal_code" => "12345",
   "city" => "Berlin",
   "country" => "DE",
   "email" => "joanne_s@gmail.com",
   "postback_url" => "https://api.awesomeproducts.com/payment_status.php",
   "success_url" => "https://awesomeproducts.com/thankyou/",
   "error_url" => "https://awesomeproducts.com/error/");
$query = http_build_query($params, NULL, "&", PHP_QUERY_RFC3986);
$outgoing_key = "4d422da6fb8e3bb2749a";
$checksum = sha1($query . $outgoing_key);
printf($checksum);
9b6b075854fc3473c09700e20e19af3fbc3ff543
Parameter Comments
api_key Merchant-specific API key
payment_type cc (for credit card), sofort (for SOFORT Uberweisung), paypal (for PayPal)
order_id Any alphanumeric string to identify the Merchant’s order
amount Payment total amount (decimal number, e.g. 1.23). Including shipping cost and VAT, if applicable
first_name User’s first name
last_name User’s last name
address Street address
postal_code Postal code
city City
country country code, e.g. DE
email User’s email
postback_url The URL where updates about transaction status are posted to
success_url Redirection target after a successful transaction
error_url Redirection target after a failed transaction
checksum A checksum of posted parameters and their values; see below for a complete explanation

Optional Request Parameters

Parameter Comments
merchant _reference What to display as the reference on the user’s bank statement. Default value: merchant order id shop name (as defined in the merchant portal)
shipping_costs Should be set if the order includes any shipping costs (decimal number, e.g. 1.23)
vat VAT amount (decimal number) if known
currency 3-letter currency code (ISO 4217). Defaults to EUR
locale Can be used change the language of payment forms in credit card and Paypal payments. Currently supported locales are en and de
address2 Second address line (billing address)
state State
phone User’s phone number

Signing Requests With Checksums

To prevent tampering with payment data, the parameters require signing with a checksum. Each merchant is assigned a private outgoing and incoming key. The API applies the following checksum calculation algorithm to verify the authenticity of the posted data.

Checksum Algorithm

  1. Make a key/value list of all used parameters (except the checksum itself), in the same order they are posted to the API request.
  2. Convert the parameters into a query string using the application/x-www-form-urlencoded format (RFC 1738). That is, spaces are encoded as plus (+) characters and special characters are encoded with a percentage sign followed by two hexadecimal digits. For instance, if the company parameter has the value “John & Sons”, the resulting string would be “company=John+%26+Sons”
  3. Append the outgoing key to the query string.
  4. Calculate an SHA1 digest of the resulting string.
  5. Set the value of the checksum parameter to the SHA1 digest.

Payment Request Responses

All requests return responses in the JSON format. The following parameters are possible:

Parameter Comments
transaction_id Unique transaction ID created by XTECH payment gateway
order_id The order ID specified by the merchant
status_code Transaction’s status code (see table below)
status Transaction status in human readable text
error_code Error code; if this is 0, everything is fine. See table below for a list of codes.
error_message If the error code is other than 0, the error message will be included here
client_action Possible values are: postform - build a POST form from the data included in the action_data array and immediately submit it to the URL included in action_data redirect - redirect to the URL specified in action_data
action_data If client_action is specified, this array includes the following data: URL, fields (in case of a POST form, this array specifies the key/value pairs of the data to be posted)

Action Required: Redirection

{
  transaction_id: "0b3c2327-9394-4ab4-be18-6e9d85e652fd",
  order_id: "1230238",
  status_code: 1,
  status: "started",
  error_code: 0,
  client_action: "redirect",
  action_data: {
    url: "https://www.sofort.com/payment/go/508712aa8572615d6151de6111"
  }
}

Some payment processors, such as SOFORT, generate a URL for each transaction, where the user can be redirected to with no POST parameters required. In such cases, client_action is set to redirect and the target URL is included in action_data.

Error Response

{
  error_code: 101,
  error_message: "Merchant not found."
}

If the API returns an error, the response will look like this.

Postbacks

On completing the transaction, the API will perform a POST request to the URL specified in postback_url before redirecting the user to the Merchant’s website. The purpose of this additional request is to pass transaction information to the Merchant without the end user seeing the contents, and to ensure the Merchant is informed about completing the transaction even if the user for some reason does not return to the Merchant’s website.

If the postback target URL is not responding or responds with any status other than 200 OK, the API will attempt to re-post the data every ten minutes. The maximum number of attempts is 10. Note that if the transaction is successful or pending, the end user will be redirected back to the shop’s success URL even if the postback target URL is not responding.

The following data will be posted in all postback requests:

Parameter Comments
transaction_id unique ID of the transaction generated by XTECH
status_code Status code of the transaction; see below
status Transaction status in human readble format; see table below
order_id Merchant order ID
checksum Checksum of the above data using the incoming key
message Additional info about the transactions status
card_last_four only for CC payments: Last four digits of the credit card number, e.g. 1881
card_brand only for CC payments: Brand of the credit card (in caps, e.g. VISA, AMEX, MASTER)

Querying Transactions

Existing transactions can be queried from the gateway’s transaction store.

List of Transactions

GET Request

resp = conn.get("https://api.xsettlepay.com/rest/transactions", 
       "api_key" => "81d345b3d68cbd51c9fe", 
       "from" => "2016-10-05T17:50:28+02:00", 
       "to" => "2016-10-05T18:50:28+02:00", 
       "checksum" => "d9f4e651f88121479d8c6cda4441ecba65687415")

JSON Response

[ 
  {
    "transaction_id": "f17f33b3-d439-4770-b2fe-562b5318d896",
    "created_at":"2016-08-02T11:27:19.053+02:00",
    "status_code":1,
    "status":"started",
    "amount":23.42,
    "currency":"EUR",
    "order_id":"Foo Merchant Order 420",
    "payment_method":"paypal"
  },

  {
    "transaction_id": "d18c33e3-k339-4471-a2ce-a6db5f1fd8c6",
    "created_at":"2016-08-01T11:22:15.053+02:00",
    "status_code":2,
    "status":"pending",
    "amount":0.23,
    "currency":"EUR",
    "order_id":"Foo Merchant Order 559",
    "payment_method":"cc"
  }
]

A list of transactions in JSON format is available through a GET request to the following end point:

https://api.xsettlepay.com/rest/transactions

The response includes the last 50 transactions. Optionally the parameters from and to can be used to specify a timeframe the transactions occurred in. It is also possible to specify one or more transaction status in a comma-separated list (see the chapter “Transaction Status” below for a list of status codes and their meanings).

Parameter Required Comment
api_key Yes API key of the merchant
from No Optional earliest date in ISO-8601, e.g. 2016-10-05T17:50:28+02:00
to No Optional latest date in ISO-8601, e.g. 2016-10-05T18:50:28+02:00
status No Optional status code or a comma-separated list of status codes, e.g. status=3 or status=2,3
currency No Optional 3-letter currency code
checksum Yes Checksum of the sent parameters

Getting Single Transaction

HTTP GET request

resp = conn.get("https://api.xsettlepay.com/rest/transactions/f17f33b3-d439-4770-b2fe-562b5318d896", 
                "api_key" => "81d345b3d68cbd51c9fe", 
                "id" => "f17f33b3-d439-4770-b2fe-562b5318d896",
                "checksum" => "d9f4e651f88121479d8c6cda4441ecba65687415")

JSON response

[
  {
    "transaction_id": "f17f33b3-d439-4770-b2fe-562b5318d896",
    "created_at":"2016-08-02T11:27:19.053+02:00",
    "status_code":1,
    "status":"started",
    "amount":23.42,
    "currency":"EUR",
    "order_id":"Foo Merchant Order 23",
    "payment_method":"cc"
  }
]

The details of a single transaction can be requested through a GET request to https://api.xsettlepay.com/rest/transactions/TRANSACTION_ID Where the required parameter TRANSACTION_ID is an existing transaction ID.

Transaction Status

Code Name Description
1 started Transaction has been started; user has been redirected to the acquirer’s website.
Transactions that remain in this state for longer than an hour should be considered aborted by the user.
2 pending The user submitted the payment, but the acquirer has marked the transaction as pending; this usually means that it takes longer than average to complete the transaction.
The pending status is treated as a successful payment; the API returns a successful state or redirects to the merchant’s success URL
3 complete The acquirer has marked the transaction as completed.
Payment is successful; API returns a successful state or redirects to success URL
4 error There has been an error with the transaction.
API returns an error state or redirects to the shop’s error URL
5 canceled Customer has canceled the payment on the acquirer’s website.
API redirects to the error URL or returns a canceled status
6 declined The acquirer has declined the payment. Payments that require a risk check are marked as declined if the risk check fails.
API returns a declined state or redirects to the shop’s error URL
7 refunded There are partial or full refunds for this transaction.
This status is usually not returned by the API but visible in the merchant portal after refunds have been made.
8 authorized The payment has been authorized successfully but not yet executed.
This payment should be captured or reversed later.
9 registered A credit card has been registered for this transaction but payment has not been executed. OR: A successful precheck has been completed but the transaction is not yet authorized.
This transaction should be completed using the payment request.
10 debt collection A debt collection process has been initiated for this transaction.
The transaction has gone into debt collection; awaiting further status updates.
11 debt paid The debt collection process has been completed for this transaction.
The debt has been collected.
12 reversed Authorization has been reversed (canceled).
13 chargeback A Chargeback has been issued for a completed or pending transaction.

Errors

The API can return the following errors with explanation messages. Please note that these messages are not meant to be displayed to the end user because most of them are of very technical nature. Instead, the Merchant’s system should decide what to do in each case (for instance, suggest a differnent payment method when the risk check fails). This list is still subject to change as features are added to the API.

Code Meaning
101 Merchant not found: Merchant does not exist or was not recognized. Check api_key.
102 Transaction not found: Transaction does not exist. Rare; may occur when redirecting back from the acquirer. Try again later; contact XTECH.
103 The checksum does not match: Either the calculation algorithm or the outgoing key is invalid. Check the checksum calculation algorithm and the outgoing key. Pay particular attention not to confuse outgoing and incoming keys.
104 Unsupported payment type: Payment method does not exist or merchant is not configured for this payment method. Check payment_type or talk to XTECH staff to have this method added to your merchant account.
106 The payment processor is not responding: Acquirer’s service is not responding. Try again later.
107 There has been an error with the payment processor: Acquirer’s service is not functioning and is returning errors. Try again later.
108 Payment error: Acquirer returned a payment-related error. Further information is usually included in the message.
109 Merchant does not have payment processor for this payment type: No acquirer has been defined for the merchant. Contact XTECH.
110 Customer did not agree to the risk check process required for this payment method: Customer must explicitly agree to the risk check process. Check risk_check_approval; remind the customer that risk check must be approved.
111 Risk check processor not found: Contact XTECH.
112 Customer did not pass the risk check: Customer had insufficient risk check score, wasn’t identified by the risk check service or the address does not exist. Inform the customer and suggest alternative payment methods.
113 There has been an error with the risk check: Error in the risk check processor’s service. Try again later or contact XTECH in case error persists.
114 Too many risk check attempts from this address: Customer attempted multiple order submits from the same IP (and failed the risk check), possibly with different personal/address data. Suggest alternative payment methods.
115 Payment provider not found: Contact XTECH.
116 Risk check adapter not found: Contact XTECH.
117 Payment adapter not found: Contact XTECH.
118 Recurring payment could not find the original transaction: You are trying to run a recurring transaction, but the original transaction was not found. Check original_transaction_id.
119 This payment processor does not support recurring payments: You are trying to make a recurring payment with an acquirer that doesn’t support recurring payments. Submit a regular (non-recurring) payment request.
120 Recurring payment could not find the original payment token: The tokens needed to make a repeat transaction with the acquirer could not be found. Most likely the acquirer did not support recurring payments at the time of the original transaction. Submit a new non-recurring payment request.
121 This payment processor does not support refunds: Contact XTECH to discuss alternative ways to refund the customer.
122 The refunded amount cannot exceed the original amount: Combined sum of past refunds for this transaction is larger than the original amount. Check the amount to be refunded.
123 This currency is not supported: The selected currency is not supported by this acquirer. Change currency.
124 Invalid country code: The country parameter has not been specified in the correct format. Make sure the country code is in the ISO 3166-1 format.
125 Invalid or missing return URLs: No valid return URLs have been specified in the payment request. Check parameters success_url, error_url and postback_url.
126 Invalid bank account information: The bank data of a direct debit transaction does not pass the validation. Check IBAN and BIC.
127 This payment processor does not support authorization: The payment processor does not support authorize/capture/reverse operations. Use payment call or contact xTech.
128 Transaction has not been authorized for capture or reverse operation: The status of transaction is other than authorized, that is, it has already been captured or reversed or was not authorized to begin with. Create a new payment request.
131 This payment processor does not support SEPA Direct Debit mandate generation: Use payment call or contact XTECH.
133 This payment processor does not support generic postbacks: The payment processor can’t handle generic postbacks and the transaction will not be updated. Contact XTECH.
134 Amount cannot be zero or negative: Payments with zero or negative amounts are rejected by all acquirers and therefore not accepted by XTECH either. Only send payments with an amount greater than zero.