Transaction Request

The Gateway API expects an HTTP POST request with XML Payload and an Authorization header containing a Hash HMAC signature (see Signing Requests below).

The destination URL is: https://gateway.dimoco-payments.eu/transaction

There is also PHP Client implementation available which takes care about generating XML, signature generation and parsing responses into PHP objects automatically.

Installing PHP Client via Composer:
composer require dimocopayments/php-client

PHP Client on Github:
https://github.com/dimocopayments/php-Client

Basic Scheme

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>YOUR_USERNAME</username>
  <password>SHA1 HASHED PASSWORD</password>
  <debit>
    <transactionId>Your Transaction ID</transactionId>
    <customer>
      <!-- refer to Transaction Data for all available fields -->
      <identification>Customer ID</identification>
      <billingCountry>2-letter country code of your customer</billingCountry>
      <email>email address of your customer</email>
      <ipAddress>127.0.0.1</ipAddress>
    </customer>
    <extraData key="some_key">value_here</extraData>
    <amount>9.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <withRegister>false</withRegister>
  </debit>
</transaction>

$username = 'Your Username';
$password = 'Your password';
$apiKey = 'Connector API Key';
$sharedSecret = 'Connector Shared Secret';

// see https://github.com/dimocopayments/php-Client/blob/master/README.md
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$debit = new \PaymentGateway\Client\Transaction\Debit();
$debit
  ->setTransactionId('Your transaction ID')
  ->setAmount(9.99)
  ->setCurrency('EUR')
  ->setDescription('Your Description')
  ->setSuccessUrl('https://link.to/your/payment-successful-page')
  ->setCancelUrl('https://link.to/your/payment-canceled-page')
  ->setErrorUrl('https://link.to/your/payment-failed-page')
  ->setCallbackUrl('https://link.to/your/notification-handler');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('The User ID')
  ->setBillingCountry('AT')
  ->setEmail('email_address@of_your_customer.com')
  ->setIpAddress('127.0.0.1');

$debit->setCustomer($customer);

$result = $client->debit($debit);

The examples show the basic data most connector requires. Depending on the connector type more data could be necessary. Please refer to the Connector Types documentation for concrete requirements.

To see all available fields please refer to Transaction Data.

For some languages we already provide a ready-to-use client implementation on GitHub.

Debit

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <debit>
    <transactionId>transaction-00001</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <extraData key="some_key">value_here</extraData>
    <merchantMetaData>my-category-1</merchantMetaData>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <withRegister>false</withRegister>
    <transactionIndicator>SINGLE</transactionIndicator>
  </debit>
</transaction>

<?php
// see https://github.com/dimocopayments/php-Client/blob/master/README.md
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$debit = new \PaymentGateway\Client\Transaction\Debit();
$debit
  ->setTransactionId('transaction-00001')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setDescription('Transaction Description')
  ->setSuccessUrl('https://link.to/your/payment-successful-page')
  ->setCancelUrl('https://link.to/your/payment-canceled-page')
  ->setErrorUrl('https://link.to/your/payment-failed-page')
  ->setCallbackUrl('https://link.to/your/notification-handler');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('1111')
  ->setBillingCountry('AT')
  ->setEmail('[email protected]')
  ->setIpAddress('123.123.123.123');

$debit->setCustomer($customer);

$result = $client->debit($debit);

curl https://gateway.dimoco-payments.eu/transaction \
  -d "PUT_XML_HERE" \
  -H "Authorization: Gateway ConnectorKey:Signature" \
  -H "Content-Type: text/xml"

A Debit performs a complete customer-to-merchant payment

Recurring Debits (and Preauthorizations)

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <debit>
    <transactionId>transaction-00002</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <referenceTransactionId>ID-FROM-FIRST-TRANSACTION</referenceTransactionId>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <transactionIndicator>RECURRING</transactionIndicator> <!-- or CARDONFILE -->
  </debit>
</transaction>

For recurring charges the initial transaction must either be a Register, or a Debit resp. Preauthorize with the withRegister flag set to true.

You must store the returned referenceId and use for recurring transactions in the field referencedTransactionId.

Debits with payment.js Integration

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <debit>
    <transactionToken>ix::abcdefghijklmnopqrstuvw</transactionToken>
    <transactionId>transaction-00001</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <withRegister>false</withRegister>
    <transactionIndicator>SINGLE</transactionIndicator> <!-- or INITIAL, if withRegister = true -->
  </debit>
</transaction>

If you've integrated the payment.js Javascript Library, you must put the token acquired with the tokenize call inside the transactionToken element.

Preauthorize

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <preauthorize>
    <transactionId>transaction-00001</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <merchantMetaData>my-category-1</merchantMetaData>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <withRegister>false</withRegister>
  </preauthorize>
</transaction>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$preAuth = new \PaymentGateway\Client\Transaction\Preauthorize();
$preAuth
  ->setTransactionId('transaction-00001')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setDescription('Transaction Description')
  ->setSuccessUrl('https://link.to/your/payment-successful-page')
  ->setCancelUrl('https://link.to/your/payment-canceled-page')
  ->setErrorUrl('https://link.to/your/payment-failed-page')
  ->setCallbackUrl('https://link.to/your/notification-handler');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('1111')
  ->setBillingCountry('AT')
  ->setEmail('[email protected]')
  ->setIpAddress('123.123.123.123');

$preAuth->setCustomer($customer);

$result = $client->preauthorize($preAuth);

A Preauthorize reserves the payment amount on the customer's payment instrument.

Depending on the payment method you have up to 7 days until you must Capture the transaction before the authorization expires.

Capture

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <capture>
    <transactionId>transaction-00002</transactionId>
    <referenceTransactionId>uuid_of_preauthorize_transaction</referenceTransactionId>
    <amount>4.99</amount>
    <currency>EUR</currency>
  </capture>
</transaction>

<?php
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$capture = new \PaymentGateway\Client\Transaction\Capture();
$capture
  ->setTransactionId('transaction-00002')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setReferenceTransactionId('UUID_of_Preauthorize_Transaction');

$result = $client->capture($capture);

A Capture completes the payment which was previously authorized with the Preauthorize method.

Depending on the payment method you can even capture only a partial amount of the authorized amount.

Void

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <void>
    <transactionId>transaction-00002</transactionId>
    <referenceTransactionId>uuid_of_preauthorize_transaction</referenceTransactionId>
  </void>
</transaction>

<?php
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$void = new \PaymentGateway\Client\Transaction\VoidTransaction();
$void
  ->setTransactionId('transaction-00002')
  ->setReferenceTransactionId('UUID_of_Preauthorize_Transaction');

$result = $client->void($void);

A Void cancels a previously performed authorization made with the Preauthorize method.

Refund

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <refund>
    <transactionId>transaction-00002</transactionId>
    <referenceTransactionId>uuid_of_debit_or_capture_transaction</referenceTransactionId>
    <amount>4.99</amount>
    <currency>EUR</currency>
  </refund>
</transaction>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$refund = new \PaymentGateway\Client\Transaction\Refund();
$refund
  ->setTransactionId('transaction-00002')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setReferenceTransactionId('uuid_of_debit_or_capture_transaction');

$result = $client->refund($refund);

A Refund reverses a payment which was previously performed with Debit or Capture.

Depending on the payment method you can even refund only a partial amount of the original transaction amount.

Payout

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <payout>
    <transactionId>transaction-00001</transactionId>
    <referenceTransactionId>ID-FROM-FIRST-TRANSACTION</referenceTransactionId> <!-- this is optionally, but maybe required for certain methods -->
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
  </payout>
</transaction>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$payout = new \PaymentGateway\Client\Transaction\Payout();
$payout
  ->setTransactionId('transaction-00001')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setDescription('Transaction Description');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('1111')
  ->setBillingCountry('AT')
  ->setEmail('[email protected]')
  ->setIpAddress('123.123.123.123');

$payout->setCustomer($customer);

$result = $client->payout($payout);

A Payout credits the customer's account with the given amount.

Depending on the connector, either referenceUuid or cardData will be required.

Register

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <register>
    <transactionId>transaction-00001</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
  </register>
</transaction>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$register = new \PaymentGateway\Client\Transaction\Register();
$register
  ->setTransactionId('transaction-00001')
  ->setDescription('Transaction Description')
  ->setSuccessUrl('https://link.to/your/payment-successful-page')
  ->setCancelUrl('https://link.to/your/payment-canceled-page')
  ->setErrorUrl('https://link.to/your/payment-failed-page')
  ->setCallbackUrl('https://link.to/your/notification-handler');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('1111')
  ->setBillingCountry('AT')
  ->setEmail('[email protected]')
  ->setIpAddress('123.123.123.123');

$register->setCustomer($customer);

$result = $client->register($register);

Registers a customer's payment instrument for future charges (Debits or Preauthorizations)

Deregister

<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <deregister>
    <transactionId>transaction-00002</transactionId>
    <referenceTransactionId>uuid_of_preauthorize_transaction</referenceTransactionId>
  </deregister>
</transaction>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$deregister = new \PaymentGateway\Client\Transaction\Deregister();
$deregister
  ->setTransactionId('transaction-00002')
  ->setReferenceTransactionId('UUID_of_Register_Transaction');

$result = $client->deregister($deregister);

A Deregister deletes a previously registered payment instrument using Register.

Debit with starting a Schedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<transaction xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Transaction">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <language>en</language>
  <debit>
    <transactionId>transaction-00001</transactionId>
    <customer>
      <identification>1111</identification>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <billingCountry>AT</billingCountry>
      <email>[email protected]</email>
      <ipAddress>123.123.123.123</ipAddress>
    </customer>
    <amount>9.99</amount>
    <currency>EUR</currency>
    <description>Transaction Description</description>
    <successUrl>https://link.to/your/payment-successful-page</successUrl>
    <cancelUrl>https://link.to/your/payment-canceled-page</cancelUrl>
    <errorUrl>https://link.to/your/payment-failed-page</errorUrl>
    <callbackUrl>https://link.to/your/notification-handler</callbackUrl>
    <withRegister>true</withRegister>
    <startSchedule>
      <amount>4.99</amount>
      <currency>EUR</currency>
      <periodLength>1</periodLength>
      <periodUnit>MONTH</periodUnit>
      <startDateTime>2018-06-05 10:54:51 UTC</startDateTime>
    </startSchedule>
  </debit>
</transaction>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>true</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <registrationId>aab69791ddedcaeae4ae</registrationId>
  <returnType>FINISHED</returnType>
  <scheduleId>SC-7FF3-37B8-0F27-8BCA-5B3D-90DB</scheduleId>
  <scheduleStatus>ACTIVE</scheduleStatus>
  <scheduledAt>2018-07-05 16:22:06 UTC</scheduledAt>
</result>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$debit = new \PaymentGateway\Client\Transaction\Debit();
$debit
  ->setTransactionId('transaction-00001')
  ->setAmount(4.99)
  ->setCurrency('EUR')
  ->setDescription('Transaction Description')
  ->setSuccessUrl('https://link.to/your/payment-successful-page')
  ->setCancelUrl('https://link.to/your/payment-canceled-page')
  ->setErrorUrl('https://link.to/your/payment-failed-page')
  ->setCallbackUrl('https://link.to/your/notification-handler');

$customer = new \PaymentGateway\Client\Data\Customer();
$customer
  ->setFirstName('John')
  ->setLastName('Smith')
  ->setIdentification('1111')
  ->setBillingCountry('AT')
  ->setEmail('[email protected]')
  ->setIpAddress('123.123.123.123');

$debit->setCustomer($customer);

$debit->setWithRegister(true);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setAmount(5.99);
$scheduleData->setCurrency('EUR');
$scheduleData->setPeriodLength(1);
$scheduleData->setPeriodUnit('MONTH');

$firstPeriodIsTrialPeriod = true;
$trialPeriodLength = '10 days';
$startDateTime = \new DateTime('+' . $trialPeriodLength);

if ($firstPeriodIsTrialPeriod) {
  $scheduleData->setStartDateTime($startDateTime);
}

$debit->setSchedule($scheduleData);

$result = $client->debit($debit);

You can start a transaction with a schedule on the fly, the transaction must be either a Register, a Debit with-register or a Preauthorize with-register.

The field startDateTime is optional and can be used to set a differing length for the first period (e.g. as trial period).

If your customer is already registered, and you can provide the registrationId, then it is recommended to use the Schedule API instead (see Schedule API).

Transaction Response

As response to the API call the gateway answers with a Result XML with the status and further instructions.

Generally there are 4 possible results:

FINISHED

<?xml version="1.0" encoding="utf-8"?>
<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>true</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <returnType>FINISHED</returnType>
</result>

$result = $client->debit($debit);

if ($result->getReturnType() == \PaymentGateway\Client\Transaction\Result::RETURN_TYPE_FINISHED) {
  //transaction was successful
  $uuid = $result->getReferenceId();
  //proceed with your checkout process
}

The transaction completed and was processed successfully. You can deliver the ordered goods.

ERROR

<?xml version="1.0" encoding="utf-8"?>
<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>false</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <returnType>ERROR</returnType>
  <errors>
    <error>
      <message>Card number invalid</message>
      <code>2008</code>
      <adapterMessage>Invalid card number</adapterMessage>
      <adapterCode>200</adapterCode>
    </error>
  </errors>
</result>

$result = $client->debit($debit);

if ($result->getReturnType() == \PaymentGateway\Client\Transaction\Result::RETURN_TYPE_ERROR) {
  //transaction failed
  $error = $result->getFirstError();
    $errorMessage = $error->getMessage();
    $errorCode = $error->getCode();
  //if reasonable tell your customer to choose a different payment method
}

The transaction failed or was declined. See the error code and message for further details.

You will find the native error message and code from the payment provider/acquiring bank in the fields adapterMessage and adapterCode.

REDIRECT

<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>true</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <returnType>REDIRECT</returnType>
  <redirectUrl>https://gateway.dimoco-payments.eu/redirect/12345678901234567890/ABCDEF01234567890ABCDEF01234567890=</redirectUrl>
</result>

$result = $client->debit($debit);

if ($result->getReturnType() == \PaymentGateway\Client\Transaction\Result::RETURN_TYPE_REDIRECT) {
  //transaction needs redirection
  $uuid = $result->getReferenceId();
    $redirectUrl = $result->getRedirectUrl();
    header('Location: '.$redirectUrl);
    exit;
}

You must redirect the user to the URL defined in redirectUrl to proceed with the transaction. Afterwards the user will be back redirected to your shop (one of the URLs you defined in the API call in successUrl, cancelUrl or errorUrl). In parallel the gateway sends a status notification to you callbackUrl with the final result.

PENDING

<?xml version="1.0" encoding="utf-8"?>
<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>true</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <returnType>PENDING</returnType>
</result>

$result = $client->debit($debit);

if ($result->getReturnType() == \PaymentGateway\Client\Transaction\Result::RETURN_TYPE_PENDING) {
  //transaction is pending
  $uuid = $result->getReferenceId();
  //wait for the postback notification for the final result
}

The transaction was accepted for processing, but is not yet completed. You will receive a status notification to the URL you defined in callbackUrl once it reaches a final state.

Depending on the payment method, this can take from seconds up to several days.

Response with Schedule

<?xml version="1.0" encoding="utf-8"?>
<result xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Result">
  <success>true</success>
  <referenceId>12345678901234567890</referenceId>
  <purchaseId>20170101-12345678901234567890</purchaseId>
  <registrationId>aab69791ddedcaeae4ae</registrationId>
  <returnType>FINISHED</returnType>
  <scheduleId>SC-7AA3-37B8-0F27-8BCA-5B3D-90DB</scheduleId>
  <scheduleStatus>ACTIVE</scheduleStatus>
  <scheduledAt>2018-07-05 16:22:06 UTC</scheduledAt>
</result>

If you have started a Schedule please store the received scheduleId for further schedule handling, the scheduleId is required for operating with the Schedule API (see Schedule API).

Postback Notifications

The Gateway sends you an asynchronous notification once a transaction reaches its final state. Per default, the format of the notification will be in the same format as your request.

A typical success notification looks like this (the element returnData can differ depending on the payment method):

<?xml version="1.0" encoding="utf-8"?>
<callback xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Callback">
  <result>OK</result>
  <referenceId>edcba123456789012345</referenceId>
  <transactionId>YOUR_TRANSACTION_ID</transactionId>
  <purchaseId>20170120-edcba123456789012345</purchaseId>
  <transactionType>DEBIT</transactionType>
  <merchantMetaData>YOUR_OPTIONAL_META_DATA</merchantMetaData>
  <amount>4.99</amount>
  <currency>USD</currency>
  <returnData type="creditcardData">
    <creditcardData>
      <type>visa</type>
      <cardHolder>Max Mustermann</cardHolder>
      <expiryMonth>10</expiryMonth>
      <expiryYear>2020</expiryYear>
      <firstSixDigits>411111</firstSixDigits>
      <lastFourDigits>1111</lastFourDigits>
      <fingerprint>ABCXYZ...</fingerprint>
      <threeDSecure>MANDATORY</threeDSecure>
      <eci>05</eci>
      <binBrand>VISA</binBrand>
      <binBank>Issuing Bank</binBank>
      <binCountry>AT</binCountry>
    </creditcardData>
  </returnData>
  <customerData>
    <identification>1111</identification>
    <firstName>John</firstName>
    <lastName>Smith</lastName>
    <billingCountry>AT</billingCountry>
    <email>[email protected]</email>
    <ipAddress>123.123.123.123</ipAddress>
  </customerData>
</callback>

This is an example for an error notification:

<?xml version="1.0" encoding="utf-8"?>
<callback xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Callback">
  <result>ERROR</result>
  <referenceId>edcba123456789012345</referenceId>
  <transactionId>YOUR_TRANSACTION_ID</transactionId>
  <purchaseId>20170120-edcba123456789012345</purchaseId>
  <transactionType>DEBIT</transactionType>
  <merchantMetaData>YOUR_OPTIONAL_META_DATA</merchantMetaData>
  <amount>4.99</amount>
  <currency>USD</currency>
  <errors>
    <error>
      <message>Card invalid</message>
      <code>2008</code>
      <adapterMessage>Invalid Card Entered</adapterMessage>
      <adapterCode>100.000.100</adapterCode>
    </error>
  </errors>
  <returnData type="creditcardData">
    <creditcardData>
      <type>visa</type>
      <country>AT</country>
      <cardHolder>Max Mustermann</cardHolder>
      <expiryMonth>10</expiryMonth>
      <expiryYear>2020</expiryYear>
      <firstSixDigits>411111</firstSixDigits>
      <lastFourDigits>1111</lastFourDigits>
    </creditcardData>
  </returnData>
  <customerData>
    <identification>1111</identification>
    <firstName>John</firstName>
    <lastName>Smith</lastName>
    <billingCountry>AT</billingCountry>
    <email>[email protected]</email>
    <ipAddress>123.123.123.123</ipAddress>
  </customerData>
</callback>

Result Codes

The result tag will either contain "OK" or "ERROR". In case of error the XML contains an errors element with further information.

<?xml version="1.0" encoding="utf-8"?>
<callback xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Callback">
  <result>OK</result>
  <referenceId>edcba123456789012345</referenceId>
  <transactionId>YOUR_TRANSACTION_ID</transactionId>
  <purchaseId>20170120-edcba123456789012345</purchaseId>
  <transactionType>DEBIT</transactionType>
  <merchantMetaData>YOUR_OPTIONAL_META_DATA</merchantMetaData>
  <amount>4.99</amount>
  <currency>USD</currency>
  <errors>
    <error>
      <message>Card declined</message>
      <code>2003</code>
      <adapterMessage>Card declined by authorisation System</adapterMessage>
      <adapterCode>301.110</adapterCode>
    </error>
  </errors>
</callback>

Data Verification

To prove the authenticity of the notification the Gateway signs every request with the same shared secret as used for signing your requests.

You should verify the signature by calculating it on your system and compare it to the given one.

The mechanism is the same as described in Signature, but instead of defining the various values (request URI, date, etc.), you must take them out of the HTTP request you received from us. You should also verify that the Date header is within a reasonable deviation of the current timestamp (e.g. 60 seconds)

Additional data

If you need additional information to process the notification for your shop order, you can use the optional field merchantMetaData, or you can provide that data as GET parameters in the callbackUrl you define.

E.g. https://www.merchant.com/notification-url?someKey=someValue&anything=else

Chargeback Notifications

If a transaction gets charged back by the customer, the Gateway will send you a notification to the URL from the original transaction (i.e. the Debit or Capture transaction).

The notification XML will then contain an element chargebackData with further information

<?xml version="1.0" encoding="utf-8"?>
<callback xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Callback">
  <result>OK</result>
  <referenceId>edcba123456789012345</referenceId>
  <transactionId>auto-generated-id</transactionId>
  <purchaseId>20170120-edcba123456789012345</purchaseId>
  <transactionType>CHARGEBACK</transactionType>
  <amount>9.99</amount>
  <currency>EUR</currency>
  <chargebackData>
    <originalReferenceId>abcdef123456123456</originalReferenceId>
    <originalTransactionId>YOUR_TRANSACTION_ID</originalTransactionId>
    <amount>9.99</amount>
    <currency>EUR</currency>
    <reason>customer_chargeback</reason>
    <chargebackDateTime>2017-02-10T04:36:09Z</chargebackDateTime>
  </chargebackData>
</callback>

You must confirm the notification in the same manner as normal status notifications with status code 200 and text "OK" in the response's payload.

Chargeback Reversal Notification

As a follow-up on chargebacks there can be a chargeback reversal. Again the Gateway will send you a notification to the URL of the original transaction.

For this kind of notification the XML contains an element chargebackReversalData with information to the original transaction and the chargeback transaction

<?xml version="1.0" encoding="utf-8"?>
<callback xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Callback">
  <result>OK</result>
  <referenceId>b5c36138ada44ca09d45</referenceId>
  <transactionId>auto-generated-id</transactionId>
  <purchaseId>20170120-edcba123456789012345</purchaseId>
  <transactionType>CHARGEBACK-REVERSAL</transactionType>
  <amount>9.99</amount>
  <currency>EUR</currency>
  <chargebackReversalData>
    <originalReferenceId>abcdef123456123456</originalReferenceId>
    <originalTransactionId>YOUR_TRANSACTION_ID</originalTransactionId>
    <chargebackReferenceId>edcba123456789012345</chargebackReferenceId>
    <amount>9.99</amount>
    <currency>EUR</currency>
    <reason>dispute_won</reason>
    <reversalDateTime>2017-03-26T11:27:15Z</reversalDateTime>
  </chargebackReversalData>
</callback>

Transaction Data

Note: For conditional fields, please refer to the corresponding adapter specific documentation.

Customer Data

The customer element can be one of two different customer types:

• Customer: This is the base type, containing all basic data
• IbanCustomer: Extends the base type with fields for IBAN, BIC, SEPA Mandate ID and Date

For details, refer to the Transaction XML definition

3D-Secure 2.0 Data

As explained in 3D Secure 2.0 Authentication you should provide as many data as you have to apply for the 3D Secure 2.0 frictionless flow.

Any data field listed shall be provided within an extraData element.

3D-Secure 2.0 Device Data

For 3DS v2, the device data below are mandatory. Transaction will not succeed if either all browser or all SDK parameters are provided.

Browser Data

The following fields are filled automatically by the Gateway if you are using hosted payment pages or payment.js integration. For any other integration flow you will need to provide them:

SDK Data

Status Request

<!-- Status Request with the UUID -->
<?xml version="1.0" encoding="utf-8"?>
<status xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Status">
  <username>YOUR_USERNAME</username>
  <password>SHA1 HASHED PASSWORD</password>
  <transactionUuid>aa85fdb3c5f2048bd77f</transactionUuid>
</status>

<!-- Status Request with the merchantTransactionId -->
<?xml version="1.0" encoding="utf-8"?>
<status xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Status">
  <username>YOUR_USERNAME</username>
  <password>SHA1 HASHED PASSWORD</password>
  <merchantTransactionId>20181127103341</merchantTransactionId>
</status>

<!-- Status Result -->
<?xml version="1.0" encoding="utf-8"?>
<statusResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/StatusResult">
  <operationSuccess>true</operationSuccess>
  <transactionStatus>SUCCESS</transactionStatus>
  <transactionUuid>aa85fdb3c5f2048bd77f</transactionUuid>
  <merchantTransactionId>20181127103341</merchantTransactionId>
  <purchaseId>20181127-aa85fdb3c5f2048bd77f</purchaseId>
  <transactionType>DEBIT</transactionType>
  <paymentMethod>Bitcoin</paymentMethod>
  <amount>9.99</amount>
  <currency>EUR</currency>
  <customerData>
    <firstName>Max</firstName>
    <lastName>Mustermann</lastName>
    <company>Test Company</company>
    <email>[email protected]</email>
    <emailVerified>false</emailVerified>
    <ipAddress>127.0.0.1</ipAddress>
  </customerData>
</statusResult>

<!-- Status Result with Error -->
<?xml version="1.0" encoding="utf-8"?>
<statusResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/StatusResult">
  <operationSuccess>false</operationSuccess>
  <errors>
    <error>
      <message>Transaction not found</message>
      <code>8001</code>
    </error>
  </errors>
</statusResult>

$username = 'Your Username';
$password = 'Your password';
$apiKey = 'Connector API Key';
$sharedSecret = 'Connector Shared Secret';

// see more detailed Status-API example here:
// https://github.com/dimocopayments/php-Client/blob/master/examples/status.php

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);
$statusRequestData = new \PaymentGateway\Client\StatusApi\StatusRequestData();

// use either the UUID or your merchantTransactionId but not both
// $statusRequestData->setTransactionUuid($transactionUuid);
$statusRequestData->setMerchantTransactionId($merchantTransactionId);

$statusResult = $client->sendStatusRequest($statusRequestData);

The Status Request expects (similar to the Transaction Request) an HTTP POST request with XML Payload and the Authentication header (see Signing Requests below).

The destination URL is: https://gateway.dimoco-payments.eu/status

In addition to the Generic Error Codes please consider the Specific Error Codes for the Status API Call.

Scheduler Request

The Schedule Gateway API expects (similar to the Transaction API) an HTTP POST request with XML Payload and an Authentication header containing a Hash HMAC signature (see Signing Requests below).

The destination URL is: https://gateway.dimoco-payments.eu/schedule

Please read the general Scheduler documentation first, to get an understanding of the different actions and states.

In addition to the Generic Error Codes please consider the Specific Error Codes for the Scheduler API Call.

startSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <startSchedule>
    <registrationId>theReferenceTransactionIdFromYourRegister</registrationId>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <periodLength>1</periodLength>
    <periodUnit>MONTH</periodUnit>
    <startDateTime>2018-06-05 14:26:11 UTC</startDateTime>
  </startSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>SC-B747-8636-D03F-1DB2-18F8-A4F1</scheduleId>
  <oldStatus>NON-EXISTING</oldStatus>
  <newStatus>ACTIVE</newStatus>
  <scheduledAt>2019-07-05 16:11:21 UTC</scheduledAt>
</scheduleResult>

// see https://github.com/dimocopayments/php-Client/blob/master/README.md
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setAmount(5.99);
$scheduleData->setCurrency('EUR');
$scheduleData->setPeriodLength(1);
$scheduleData->setPeriodUnit('MONTH');
$startDateTime = new \DateTime('+ 1 month');
$scheduleData->setStartDateTime($startDateTime);

$scheduleResult = $client->startSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess() && $scheduleResult->getNewStatus() == ScheduleResult::STATUS_ACTIVE) {
    //operation was successful
    $scheduleId = $scheduleResult->getScheduleId();
} else {
    $errors = $scheduleResult->getErrors();
}

Starting a schedule via Schedule API requires the registrationId of an existing transaction from type Register (or Debit-with-register or Preauthorize-with-register).

If the customer is not already registered, please use the Transaction Request API, where you can start a schedule on the fly (see Debit with starting a schedule).

updateSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <updateSchedule>
    <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
    <registrationId>theReferenceTransactionIdFromYourRegister</registrationId>
    <amount>4.99</amount>
    <currency>EUR</currency>
    <periodLength>1</periodLength>
    <periodUnit>MONTH</periodUnit>
    <startDateTime>2018-06-05 14:26:11 UTC</startDateTime>
  </updateSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>SC-B747-8636-D03F-1DB2-18F8-A4F1</scheduleId>
  <oldStatus>ACTIVE</oldStatus>
  <newStatus>ACTIVE</newStatus>
  <scheduledAt>2019-07-05 16:11:21 UTC</scheduledAt>
</scheduleResult>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setScheduleId($scheduleId); // the scheduleId you have received in the Result of the startSchedule - Call
$scheduleData->setAmount(5.99);
$scheduleData->setCurrency('EUR');
$scheduleData->setPeriodLength(1);
$scheduleData->setPeriodUnit('MONTH');
$startDateTime = new \DateTime('+ 1 month');
$scheduleData->setStartDateTime($startDateTime);

$scheduleResult = $client->startSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess() && $scheduleResult->getNewStatus() == ScheduleResult::STATUS_ACTIVE) {
    //operation was successful
    $scheduleId = $scheduleResult->getScheduleId();
} else {
    $errors = $scheduleResult->getErrors();
}

You can update the information of a schedule.

Note: Only the fields you submit will be updated. So if you're not sending e.g. amount and currency, the amount will stay the same, only the next due date and the interval will be changed.

showSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <showSchedule>
    <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  </showSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  <oldStatus>ACTIVE</oldStatus>
  <newStatus>ACTIVE</newStatus>
  <scheduledAt>2019-07-05 16:11:21 UTC</scheduledAt>
</scheduleResult>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setScheduleId($scheduleId); // the scheduleId you have received in the Result of the startSchedule - Call

$scheduleResult = $client->showSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess()) {
    $currentStatus = $scheduleResult->getNewStatus();
} else {
    $errors = $scheduleResult->getErrors();
}

You can retrieve status information about the requested Schedule.

pauseSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <pauseSchedule>
    <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  </pauseSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  <oldStatus>ACTIVE</oldStatus>
  <newStatus>PAUSED</newStatus>
</scheduleResult>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setScheduleId($scheduleId); // the scheduleId you have received in the Result of the startSchedule - Call

$scheduleResult = $client->pauseSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess() && $scheduleResult->getNewStatus() == ScheduleResult::STATUS_PAUSED) {
    //operation was successful
} else {
    $errors = $scheduleResult->getErrors();
}

You can pause an active Schedule. A paused Schedule does not perform payments until you continue the schedule.

continueSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <continueSchedule>
    <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
    <continueDateTime>2019-06-05 14:26:11 UTC</continueDateTime>
  </continueSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  <oldStatus>PAUSED</oldStatus>
  <newStatus>ACTIVE</newStatus>
  <scheduledAt>2019-07-05 16:11:21 UTC</scheduledAt>
</scheduleResult>

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setScheduleId($scheduleId); // the scheduleId you have received in the Result of the startSchedule - Call
$continueDateTime = new \DateTime('+ 10 days');
$scheduleData->setContinueDateTime($continueDateTime);

$scheduleResult = $client->continueSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess() && $scheduleResult->getNewStatus() == ScheduleResult::STATUS_ACTIVE) {
    //operation was successful
} else {
    $errors = $scheduleResult->getErrors();
}

You can continue a paused Schedule.

cancelSchedule

<!-- Request -->
<?xml version="1.0" encoding="utf-8"?>
<schedule xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Schedule">
  <username>API_USER</username>
  <password>5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8</password>
  <cancelSchedule>
    <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  </cancelSchedule>
</schedule>

<!-- Response -->
<?xml version="1.0" encoding="utf-8"?>
<scheduleResult xmlns="https://gateway.dimoco-payments.eu/Schema/V2/ScheduleResult">
  <operationSuccess>true</operationSuccess>
  <scheduleId>theScheduleIdYouHaveReceivedInTheStartScheduleResult</scheduleId>
  <oldStatus>ACTIVE</oldStatus>
  <newStatus>CANCELLED</newStatus>
</scheduleResult>

// see https://github.com/dimocopayments/php-Client/blob/master/README.md
$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$scheduleData = new  \PaymentGateway\Client\Schedule\ScheduleData();

$scheduleData->setScheduleId($scheduleId); // the scheduleId you have received in the Result of the startSchedule - Call

$scheduleResult = $client->cancelSchedule($scheduleData);

if ($scheduleResult->getOperationSuccess() && $scheduleResult->getNewStatus() == ScheduleResult::STATUS_CANCELLED) {
    //operation was successful
} else {
    $errors = $scheduleResult->getErrors();
}

You can cancel a Schedule.

Options Request

Some adapters can provide additional information for your payment integration, for example a bank list for EPS transactions. This allows you to show the bank selection already on your shop checkout site.

See the adapter specific page for additional information about available Options request methods.

Request

An Options request is generated analogue to a normal transaction request, i.e. it needs the same credentials and request signing method.

The destination URL is: https://gateway.dimoco-payments.eu/options

<?xml version="1.0" encoding="utf-8"?>
<options xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Options">
  <username>API_USERNAME</username>
  <password>API_PASSWORD (SHA1 HASHED)</password>
  <request>
    <identifier>epsBankList</identifier>
  </request>
</options>

$username = 'Your Username';
$password = 'Your password';
$apiKey = 'Connector API Key';
$sharedSecret = 'Connector Shared Secret';

$client = new \PaymentGateway\Client\Client($username, $password, $apiKey, $sharedSecret);

$bankList = $client->getOptions('epsBankList');

Response

If successful the response contains a list of parameter elements with key/value pairs.

<?xml version="1.0" encoding="utf-8"?>
<options xmlns="https://gateway.dimoco-payments.eu/Schema/V2/Options">
  <response>
    <success>true</success>
    <parameter name="HAABAT2KXXX">Austrian Anadi Bank AG</parameter>
    <parameter name="VRBKAT21XXX">VR-Bank Braunau</parameter>
    <parameter name="VKBLAT2LXXX">Volkskreditbank AG</parameter>
    <parameter name="SPADATW1XXX">Sparda Bank Wien</parameter>
    <!-- ... -->
  </response>
</options>

$bankList = $client->getOptions('epsBankList');
print_r($bankList);
/*
  Array
  (
    [HAABAT2KXXX] => Austrian Anadi Bank AG
    [VRBKAT21XXX] => VR-Bank Braunau
    [VKBLAT2LXXX] => Volkskreditbank AG
    [SPADATW1XXX] => Sparda Bank Wien
    ...
  )
*/

Authentication (Password Hashing)

Within the transaction request XML you pass username and password given by your integration engineer.

The plaintext password must be hashed with SHA1 hashing algorithm. The result shall be passed in lower case letters.

$password = 'myPassword';
$password = sha1($password);

var pass = "myPassword";
var sha1 = SHA1.Create();
var hash = sha1.ComputeHash(System.Text.Encoding.ASCII.GetBytes(pass));
pass = this.ByteToString(hash).ToLower(); //see function below

protected string ByteToString(byte[] buff)
{
  StringBuilder sb = new StringBuilder();
  for (int i = 0; i < buff.Length; i++)
  {
    sb.Append(buff[i].ToString("X2"));
  }
  return sb.ToString();
}

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

String password = 'myPassword';

MessageDigest md;
try {
  md = MessageDigest.getInstance("SHA-1");
} catch( NoSuchAlgorithmException e ) {
  // should never happen since MessageDigest doc says SHA-1 must be on every JVM
  throw new RuntimeException("couldn't get SHA-1 digest", e);
}
byte[] digest = password.getBytes(StandardCharsets.UTF_8);
md.reset();
digest = Hex.hex(md.digest(digest)).getBytes(StandardCharsets.UTF_8);

password = new String(digest, StandardCharsets.UTF_8);

Signing Requests

Generating the Signature

Every request to the Transaction API must be signed with your shared secret.

The signature is generated via Hash HMAC method, using SHA2-512 as hashing algorithm and is expected to be BASE64 encoded.

$method = 'POST';
$xml = '...'; //see Transaction Request chapter
$contentType = 'text/xml; charset=utf-8';
$date = new \DateTime('now', new \DateTimeZone('UTC'));
$timestamp = $date->format('D, d M Y H:i:s T');
$additionals = '';
$requestUri = '/transaction';

$signatureMessage = join("\n", [$method, hash("sha512", $xml), $contentType, $timestamp, $additionals, $requestUri]);

$digest = hash_hmac('sha512', $signatureMessage, 'THE_SHARED_SECRET', true);
$signature = base64_encode($digest);

var sharedSecret = "SHARED_SECRET";
var method = "POST";
var bodySHA512 = MakeSHA512Hash(transactionXml);
var contentType = "text/xml; charset=utf-8";
var date = new DateTime();
var timestamp = date.ToUniversalTime().ToString("r");
var additionals = "";
var requestUri = "/transaction";

var signatureMessage = method + "\n" + bodySHA512 + "\n" + contentType + "\n" + timestamp + "\n" + additionals + "\n" + requestUri;

var hmacSha512 = new HMACSHA512(Encoding.UTF8.GetBytes(sharedSecret));
var hash = hmacSha512.ComputeHash(Encoding.UTF8.GetBytes(signatureMessage));

var signature = System.Convert.ToBase64String(hash); //this is what we need now

public string MakeSHA512Hash(string content) {
  SHA512 sha512 = new SHA512Managed();
  byte[] inputBytes = System.Text.Encoding.UTF8.GetBytes(input);
  byte[] hash = sha512.ComputeHash(inputBytes);

  StringBuilder sb = new StringBuilder();
  for (int i = 0; i < hash.Length; i++) {
    sb.Append(hash[i].ToString("X2"));
  }
  return sb.ToString();
}

// No Java example yet

The signature message is built by concatenating the following data with a line break \n

• HTTP Method ("POST")
• SHA512 hash of payload (the XML itself) - Note: In previous versions this is MD5 instead.
• Content-Type header (e.g. "text/xml; charset=utf-8")
• Timestamp as sent in Date header
• Additional custom headers (usually empty)
• Request URI string (usually "/transaction")

Afterwards you build the HMAC digest with SHA512 of this message with the shared secret as key. The digest should be generated in binary (not hexadecimal) and then base64 encoded.

Passing the Signature

curl \
-d "PUT_XML_HERE" \
-H "Authorization: Gateway THE_API_KEY:Signature" \
-H "Content-Type: text/xml" \
"https://gateway.dimoco-payments.eu/transaction"

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Authorization: Gateway THE_API_KEY:'.$signature,
  'Date: '.$timestamp, //from above
  'Content-Type: '.$contentType
);

var apiKey = 'YOUR_API_KEY';
var request = (HttpWebRequest)WebRequest.Create("https://gateway.dimoco-payments.eu/transaction");

//values from above
request.Method = method;
request.ContentType = contentType;
request.ContentLength = transactionXml.Length;

request.Date = now;
request.Headers.Add("Authorization: Gateway " + apiKey + ":" + signature);

// No Java example yet

The generated signature must be passed in the request header Authorization, alongside with the application name ("Gateway") and your API key for the desired connector.

E.g.: Authorization: Gateway API_KEY:generatedSignature

(Replace "API_KEY" and "generatedSignature" with the appropriate values)

Now you can send the request.

Signature Testing Tool

Use this tool to verify the correctness of your signature generation.

Signature parameters
API-Key
Shared Secret
Method
Content
Content-Type
Timestamp (format)
Endpoint
Generate signature

Signature output
Expected -Hash of payload
Method
Content-Type
Timestamp
Request-URI
Hash HMAC Input (based on your request) Do note the line breaks!
Expected signature = data hashed using HMAC (SHA512), and the resulting binary encoded using Base64
Expected headers