NAV Navbar
java php
  • Introduction
  • Getting started
  • Implementation Details
  • API
  • SecureFields
  • Data Structures
  • Additional services
  • Additional resources
  • Introduction

    Intended Audience

    This documentation is for merchants and developers who want to implement the CrefoPay payment system. Help us improve this guide by contacting us and pointing out errors, misspellings or unclear sections at service@crefopay.de.

    Getting started

    CrefoPay offers an easy interface for web-shops to integrate with a variety of payment options by performing just a single integration with the CrefoPay system. Integration with CrefoPay spans into the various shop processes and systems from web-shop to warehouse to accounting.

    The CrefoPay interface is suitable for both immediate fulfilment – for example, for transactions involving electronic services or goods that are delivered immediately after the checkout took place – or delayed fulfilment – transactions involving goods ́ delivery (order delivery) to users after a time, possible days from checkout.

    So CrefoPay allows the shop to focus on the best shopping experience for its users without having to deal with the hassle of providing a variety of payment options and multiple integrations. The implementation of the multitude of payment options can be realized with just one simple integration. During checkout, CrefoPay ’s payment system is optimized to select the most convenient payment options for the shop’s customer and at the same time satisfy the shop’s needs for secure payments.

    Integration options

    The CrefoPay platform offers great flexibility for the integration into the web shop's checkout process. In general, there are two types of integration for two versions each. This allows E-commerce merchants with any sales volume to choose the ideal integration type for their requirements.

    Identifier Type Description Benefit
    API API The CrefoPay System is integrated as pure API solution without using Hosted Page. To transfer credit card data the merchant has to be PCI compliant. Full Design Control, seamless page tracking
    SecureFields API with using secure fields The CrefoPay system is integrated as pure API solution without using Hosted Page but by using the CrefoPay secure fields to transfer credit card data. Full Design Control, Seamless page tracking, for all Non PCI compliant shops
    HostedPageBefore PRE-integrated Hosted Page The Hosted Page, which shows all payment methods /instruments is integrated before the confirmation page of the merchant's shop is shown. The hosted page allows the user the select a payment method and enter payment instruments like credit card and bank account. Easy and quick integration, no hassle with PCI compliance and error handling
    HostedPageAfter POST-integrated Hosted Page The Hosted Page, which shows all payment methods /instruments is integrated after the confirmation page of the merchant's shop is shown. The hosted page allows the user the select a payment method and enter payment instruments like credit card and bank account. Easy and quick integration, no hassle with PCI compliance and error handling
    HostedPageAfter Pay By Link via API The CrefoPay System creates a payment link which redirects the customer to a hosted payment page to complete the payment. Easy and quick integration, no hassle with PCI compliance and error handling. No integration into the shop front-end required.

    API integration

    When using complete/self-sufficient API integration, the E-commerce merchant has maximum flexibility when designing and integrating the payment page, but in return he has to fulfil the high security requirements imposed by e.g. PCI-compliance guidelines issued by credit card companies. This integration type is therefore more suited to large companies which want to retain full design and process control.

    API integration with secure fields

    The API integration with secure fields corresponds to the aforementioned version, however, with the difference that the secure fields library is made available to the E-commerce merchant via the CrefoPay platform. This Bridge is used to handover credit card and bank details in a secured environment outside of the shop sovereignty and avoids that the E-commerce merchant has to independently fulfil the PCI-compliance guidelines issued by the credit card companies. This integration type therefore tends to be more suited for large companies which want to retain full design and process control yet avoid the PCI-requirements.

    Integration as Hosted Page (Before / After)

    CrefoPay delivers a complete payment page with the easy and above all fast "Hosted Pages" integration type. It is a complete payment page for all payment types for the E-commerce merchant's shop and ensures that no safety relevant data is stored on the retailer's website. Therefore, the E-commerce merchant fulfils automatically the applicable high safety standards e.g. PCI-compliance imposed by credit card companies thanks to CrefoPay.

    The standard Hosted Page design is responsive, i.e. depending on the end customer’s terminal (e.g. PC, smartphone or tablet) the payment page is optimised for the terminal's display. A special feature is the easy customisability of the Hosted Page: It can be configured independently by the E-commerce merchant which allows him to retain in parts control over the page design. Changes can be checked with the preview function and set to "live" with one click. In addition to visual design of the payment page, the E-commerce merchant can also make content changes. This allows shops to provide individual, multi-lingual texts for every payment method (e.g. as explanatory note or to promote individual payment methods) and to save individual fees or discounts per payment type. This also enables the retailers to have significantly more control with regard to directing the end customer to certain payment methods.

    The E-commerce merchant can also specify the point at which the payment page should be opened during the entire checkout process. There is a choice of "before" or "after" purchase confirmation, referred to as the pre-integration (3) or post integration version (4). Therefore, the Hosted Page can be ideally integrated into the checkout process according to the needs and preference of the E-commerce merchant.

    Pay By Link via API allows the creation of payment links directly from the merchant's system. These links can be used/delivered in any way to allow customers to pay in an fast and easy fashion. Optionally the CrefoPay system can be instructed to automatically send these payment links in an email to the customer, which further reduces the implementation effort. The payment link redirects the customer to a payment page which is based on the 'Hosted Page After'. Pay By Link transactions require a minimal amount of parameters to be initiated compared to other integration options. Should solvency checks be performed for payment methods such as bill payment and direct debit, the necessary data for the check will be collected on the payment page directly from the customer. This integration type is not meant to be used in a shop checkout, but as an alternative way to collect payments independent of any shop. Possible use cases include, but are not limited to, mail and telephone orders, or offering alternative payment methods on the bill for a customer.

    Process description

    To understand the CrefoPay system some terms and correlations need to be explained. The following graphic illustrates the relation between transactions and captures

    Transaction Capture

    Transactions

    If a user initiates the payment process within the checkout process, the merchant’s shop system performs a createTransaction call on the CrefoPay system and transfers all relevant data. A transaction can be referred later on by the shop system (or an ERP system) with the unique identifier orderID. This could be the reference number of the order or an invoice number or anything else, but is has to be unique for the shop. After receiving all necessary data, the CrefoPay system creates a transaction with the status New. The transaction will then pass through different states which are represented by the transaction status.

    Transaction Status

    Status Description
    New Internal status. Means that a transaction has been created within the CrefoPay system after receiving the user and basket data from the shop system during checkout
    AcknowledgePending Internal status. The user has confirmed the purchase during checkout by pressing button "Buy" and in case of redirect payment methods CrefoPay is waiting for the response from the shop which contains the success-URL.
    FraudPending This status indicates, that the transaction is suspect due to fraud suspicions and needs to be checked manually.
    MerchantPending The transaction was successful. CrefoPay is waiting for the merchant to capture the transaction when delivering the order or immediately after checkout process.
    CIAPending The transaction was created successfully and CrefoPay is waiting for money to arrive in the merchant funds account. Relevant for cash in advance and PayPal with IPN.
    Expired The transaction was not completed by the user within the duration of the basket-validity.
    Cancelled The transaction was cancelled by the merchant
    FraudCancelled The transaction was cancelled because of fraud suspicion by CrefoPay’s fraud team.
    Done The transaction has been completed. A transaction will change into this status if all of its captures have the status paid.

    The transaction status can be affected by the user, the system, the fraud team, the shop or the capture status.

    The transaction status remains as New until a reservation is made. This usually happens when the customer clicks the "Buy" button on the web-shop. After confirmation of the purchase the transaction status changes to AcknowledgePending.

    The resultCode of a reservation is 0 in case of a successful reservation, but it can also equal 1 regarding of the payment method. This signals that the user needs to be redirected to a payment page of a third party payment supplier (e.g. PayPal or SOFORT). The URL to which they should be redirected is provided by CrefoPay in the response to the reserve call.

    After the reservation has been confirmed, the status of the transaction is set to MerchantPending or in the case where the user has selected to pay via cash in advance to CIAPending first. After the user has sent the money, the transaction status also changes to MerchantPending and the next section "captures" becomes relevant.

    If the shop/ERP system cancels the transaction via cancel call, the status of the transaction is set to Cancelled. If the transaction is already paid, the CrefoPay system will automatically initiate a refund of the transaction sum.

    Captures

    All transactions with status MerchantPending wait to be captured by the shop/ERPsystem. A capture can be referred later on by the shop/ERP system by passing the unique identifier captureID via capture call. So whereas the creation of a transaction is triggered by the user during checkout process, the creation of an capture is initiated by the shop/ERP system.

    Capture Status

    Status Description
    PayPending The capture or part-capture is waiting to be paid.
    Paid The capture or part-capture was paid successfully. Alternatively the open amount could have been reduced to 0 using a refund on bill and direct debit transactions.
    PaymentFailed This status indicates that the payment is suspect due to fraud suspicions and needs to be checked manually.
    Cleared The capture or part-capture was booked successfully and cleared.
    Chargeback A chargeback was reported on the capture.
    InDunning This status can only occur if the dunning and collection service has been enabled at CrefoPay. Customer of the capture is in the dunning process.
    InCollection This status can only occur if the dunning and collection service has been enabled at CrefoPay. Customer of the capture is in the collection process.

    The point of time when a capture should be done, depends on the business model and is a decision of the merchant:

    CrefoPay also supports the ability to perform more than one capture e.g for the case of partial delivery.

    After a successful capture the status of a transaction is set to

    The transaction status is therefore dependent on the action of the shop/ERP system up to a certain time point. As soon as the shop/ERP system confirms a transaction via the capture, the transaction status will be directly affected by the status of the captures.

    Example: If a capture was booked to a transaction and the capture was marked as Paid, the transaction status is Done as the capture status is Paid. If a chargeback is reported by the bank or credit card company, the capture status changes from Paid to Chargeback and therefore the transaction status changes back from Done to InProgress. It is possible for the Transaction status to move in either direction.

    If the merchant does not want to capture the full amount, e. g. because some goods can not be delivered, the finish call should be used to close the transaction. This will refund the overpaid amount to the user in case the transaction was paid in advance.

    User

    Users will automatically be created at CrefoPay when createTransaction is called with a new userID. Alternatively registerUser can be used to create users without starting a transaction each time. The userID is the unique identifier of an user for a specific store. If a returning user for a store is identified by CrefoPay with the userID any payment instruments used in the past will be displayed when using the hosted pages integration type. This allows returning customers to re-use cards/bank accounts without the need to re-enter all data. Due to the sensitive nature of this data (card and bank data) the merchant has to make sure that no userID can be shared between users.

    Hosted Pages description

    Types of Hosted Payment integration

    Hosted Pages Options

    There are two ways to integrate Hosted Pages. The payment page can be shown before or after the shops order confirmation page. Which option fits better depends on the used web-shop or module.

    Hosted Pages Before

    Hosted Pages Before

    1. With the API call createTransaction the shop passes all relevant data to the CrefoPay
    2. The CrefoPay system returns an URL, which refers to the hosted payment selection page. The shop displays the hosted payment selection page to the user and CrefoPay performs the 1st risk check before displaying the selectable payment methods.
    3. The user selects a payment method on the payment selection page, and enters the payment instrument data if necessary.
    4. In case of an error the CrefoPay system shows the error message on the payment selection page
    5. The CrefoPay system redirects the customer to the confirmation URL configured for this shop and informs the shop about the selected payment method. See: callback
    6. The shop calculates the final order amount and displays the purchase confirmation page to the user. After the user confirmed the purchase, the merchant reserves the final order amount with the reserve call
    7. In case of an error the CrefoPay system returns a new URL in its response with the proper error message and the shop redirects the user back to the updated payment method
    8. In case of a successful risk check the processing of the payment can start

    Hosted Pages After

    Hosted Pages After

    1. With the API call createTransaction the shop passes all relevant data to the CrefoPay
    2. In case of an error the CrefoPay system shows the error message on the payment selection page
    3. The CrefoPay system returns an URL, which refers to the hosted payment selection page. The shop displays the hosted payment selection page to the user and CrefoPay performs the 1st risk check before displaying the selectable payment methods.
    4. The user selects a payment method on the payment selection page. CrefoPay now validates the data and performs the second risk check.
    5. In case of an error the CrefoPay system shows the error message on the payment selection page.
    6. In case of an decline due to a failed 2nd risk check the CrefoPay system shows an error message on the payment selection page.
    7. After a successful risk check, CrefoPay automatically reserves the full transaction amount. The merchant does not need to perform the reserve call himself.

    Supported Payment Methods

    Name General notes
    Bill After checkout, the shop has to generate a invoice including the account information and payment reference provided by CrefoPay. The account information and the payment reference are provided in the response to the reserve. Alternatively they can be retrieved by the shop from CrefoPay using the getTransactionStatus call.
    Cash in Advance After checkout, the shop can only deliver the order after payment has been received from the user. Incoming payments are reported to the shop by the Merchant Notification Service.
    Cash on Delivery After checkout, the user makes payment only once he has received the product. This payment is not made via CrefoPay checkout. So CrefoPay cannot process any payment here. As a result, the merchant will have to process ‘Cash on Delivery’ payments separately.
    Credit Card After checkout, the reservation or authorization is processed immediately. The shop receives the outcome of the payment as result of the reserve call
    Credit Card with 3D-Secure If a credit card holder is registered with the 3D Secure process via one of the registration methods, then once the purchase is confirmed, the customer is forwarded to an entry page of his bank where he can enter his password. Payment is carried out only after the correct password is entered. The password is only known to the customer and his bank. For MasterCard this solution is called “MasterCard Secure Code”, for Visa “Verified by Visa”.
    Direct Debit Direct Debit has to be processed by the bank system once it has been transferred to the bank gateway. This can take several days. The order status is PayPending during this period. As a result of the reconciliation process the bank system provides feedback which will be considered automatically within the CrefoPay system: in case of a positive feedback, the status of the order will be set to Paid; in case of a negative return it gets status PaymentFailed.Sometimes the CrefoPay does not receive any feedback from the bank. For this rare case the CrefoPay system waits until a so said grace period has been passed. If the CrefoPay system has not received a negative feedback within this grace period the status of the order will be set to Paid. The CrefoPay system sets a so-called grace period, since the bank system only provides feedback if the direct debit is rejected. The order status changes to Paid once the CrefoPay system has not received negative feedback from the bank system after this grace period.
    PayPal During checkout, the users will be required to login into their PayPal accounts. CrefoPay redirects the user to PayPal to login using his credentials. After a successful authentication or cancellation, PayPal informs CrefoPay about the outcome, CrefoPay performs a callback and redirects the user back to the shop.
    Sofort (Online Remittance) After confirmation, the user is forwarded during checkout to the SOFORTBank website where he can select his bank. This takes him to the entry page of his bank where he has to authenticate himself with his access data. He then triggers an online bank transfer from this environment. Similar to PayPal, SofortÜberweisung will inform CrefoPay about the outcome, CrefoPay performs a callback and redirects the user back to the shop.
    Other Payment methods From time to time CrefoPay may add payment methods. Consult your CrefoPay representative.

    Risk Management

    The integrated risk management platform uses a combination of machine learning, sector specific data and fully adjustable criteria in order to decide in real time whether transactions are accepted or rejected, if the end customer only gets offered secure payment methods or if the transaction has to be checked manually. Buyers shopping with online retailers can pay for their goods, services and digital contents using a range of payment methods such as credit cards, PayPal, direct debit, prepayment etc. The payment methods vary in cost and risk (with regards to non-payment risk) for the online retailer on the one hand and with regard to popularity with the customers on the other. If a preferred payment method is missing, then it may lead to an increased rate of purchase cancellations and reduce the so-called retailer conversion rate.

    The risk management integrated in the CrefoPay platform controls the payment types for E-commerce retailers actively and dynamically during checkout based on different check algorithms and criteria based on select parameters.

    Dynamic control is carried out based on a two-step risk assessment. In advance, it is coordinated with the merchant which payment methods should be available in general and which of those are offered for certain risk assessments.

    Risk Management

    As seen in the graphic above, the process starts with the merchant initiating a createTransaction request when the customer enters the payment section of the checkout. Using this request the merchant can already decide how to treat the customer based on his own experience. This allows the merchant to:

    Furthermore, the merchant is able to provide risk classes for basket items as well. Similar to the first level risk assessment done by CrefoPay, these will only apply if the transaction risk class is medium. See the following table on how the combination of customer and basket items risk class affect the transaction risk class:

    Risk Matrix

    Dunning and collection

    Every German and Austrian shop has the option to use the professional dunning and collection service of our partner accredis.

    All orders will automatically be passed to accredis for processing

    All orders, which have been passed to accredis, go into status inDunning. Also the user/debtor gets this status.

    If a user is in status inDunning, he is not able to pay with insecure payment methods like direct debit or bill until he has paid the outstanding amount.

    If the dunning process was successful or the accredis file gets closed, the CrefoPay system gets a notification about it.

    In this case the status of the order will be set to paid even if the debt claim was not fully paid. A file can be closed if the user was not able to pay or just paid a partial amount of the debt claim.

    If the dunning process process finished without the file being closed as mentioned above the collection process starts. Accredis notifies CrefoPay about the start of the collection process which triggers the order and the user status to change to inCollection. Similar to inDunning customers with status inCollection will not be able to use insecure payment methods. The order will only switch to paid if the file is closed manually, or an incoming payment is registered.

    All orders with status paid will be passed to the clearing, so that the shop gets all payments which have been collected during dunning/collection.

    To effectively use this service accredis at least requires the invoice number of the order created by the merchant. The invoice number can either be passed to CrefoPay and therefore accredis by providing it in the field captureID when performing a capture, or alternatively it can be passed after capturing by using the updateInvoice.

    Implementation Details

    General Rules

    Data Types

    Following data types are used in this documentation:

    Type Description Comments Sample
    AN (length Alpha-Numeric Sequence of characters (UTF-8 encoded) with maximum length Test
    N (length) Numeric Sequence of numbers with maximum length 12356
    V Fixed Value The possible values can be found in the comments CC
    J (type) JSON-Object JSON object of a special type { 'id': 'xyz' }
    JA (type) JSON-Array Array of JSON objects of a special type ['abc', 'xyz']
    B Boolean value true
    • true
    • false
    D (format) DATE Date with a specified Format YYYY-MM-DD

    Security and signing of requests

    In order to ensure the security of the calls made to the CrefoPay interface, there are certain rules that have to be followed.

    In order to prevent any tampering with the parameters of the request, all calls have to be signed with what is known as a Message Authentication Code (MAC).

    The MAC has to be calculated by the caller and passed along as a further parameter in the request. The algorithm used for this is HMAC (RFC 2104). The HMAC algorithm needs to be a shared secret between parties in order to validate the authenticity of the message. All responses from CrefoPay contain a MAC in the response header which can be used for validation.

    Status codes

    Successful responses have HTTP status 200 (OK). If there is a problem with the content of the request the http status is 400 (Bad Request). In case of validation errors there is a http status 401 (Unauthorized) returned. Possible causes are:

    Merchant credentials

    MAC calculation

    The Message Authentication Code (MAC) is used to ensure data integrity and therefore includes the request parameters with further calculations performed.

    The MAC is included in both the request and response.

    Request

    In requests the MAC is sent as POST parameter

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    X-Payco-HMAC: 289740cfda1c7f1df1c2ce9562930350e6bcb0a6
    Transfer-Encoding: chunked
    

    In the response the mac is part of the HTTP header as X-Payco-HMAC

    There are cases where the CrefoPay system can not generate a MAC. For example if the merchantID is missing in the request and the merchant can not be identified. In this case there will be no MAC in the header. This will only happen for error-messages (resultcode 101). Responses for successful calls will always include a MAC

    Calculation

    The MAC should be computed as follows:

    Generate an HMAC-SHA1 key using the merchant's private key. The key can be computed once and stored if the private key is unchanged.

    Request

    Create the datastring. Build a string containing the calls parameter values alphabetically ordered (a - z). To order the parameters the key is used and not the value. The parameter "mac" is the only one that is not included in the calculation.

    Compute the MAC using the HMAC-SHA1 calculation together with the private key on the datastring.

    Response

    In the response the whole body is the datastring as it contains all the payload, but the process is exactly the same as outlined in the previous paragraph. Keep in mind to remove the parameter 'mac' from the response before calculating and verifying its MAC.

    To validate notifications sent from CrefoPay to the merchant, the process is basically the same as described above.

    Example

    <?php
    function getMac($request) {
        global $privateKey;
    
        // Sort parameters alphabetically by key for MAC calculation
        ksort($request);
    
        // Create a string from the parameter values for MAC calculation
        $macstring = implode("", $request);
    
        // Calculate MAC
        return (hash_hmac('sha1', str_replace(array(" ","\t","\s","\r","\n",' '), "", $macstring), $privateKey));
    }
    ?>
    
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class MACCalculator {
    
      public String calculateMAC(String input, String secret) {
        // generate MAC Secret Key (Step a)
        Mac mac = null;
    
        try {
          SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(), "HmacSHA1");
          mac = Mac.getInstance("HmacSHA1");
          mac.init(signingKey);
        } catch (Exception e) {  /* handle exception*/}
        return hmac(input, mac);
      }
    
      // method that applies mac key to the parameters string
      private String hmac(String input, Mac mac) {
        input = input.replaceAll("\\s", "");
    
        final byte[] hmac = mac.doFinal(input.getBytes());
    
        final StringBuilder hex = new StringBuilder(2 * hmac.length);
    
        for (final byte b : hmac) {
          // b & 0xff converts e.g. 0xffffff81 to 0x81
          String hexString = Integer.toHexString(b & 0xff);
    
          if (hexString.length() < 2) {
            hex.append("0");
          }
          hex.append(hexString);
        }
        return hex.toString();
      }
    
      public String calculateAndGetMAC(MultiValueMap<String, String> map, final String merchantPassword) {
        StringBuilder macInput = new StringBuilder();
        SortedSet<String> keys = new TreeSet<>(map.keySet());
        for (String key : keys) {
          String value = map.toSingleValueMap().get(key);
          macInput.append(value);
        }
        return calculateMAC(macInput.toString(), merchantPassword);
      }
    
      /*
      * Main method only includes a simulation to a MAC Calculator client
      */
      public static void main(String[] args) {
        String merchantPassword = "8A!v#6qPc3?+G1on";
    
        // The input variable below should include the call parameters in alphabetic order
        String input = "123testOrdertestStore";
    
        MACCalculator macCalculator = new MACCalculator();
        System.out.println((macCalculator.calculateMAC(input, merchantPassword)));
      }
    }
    

    To verify if the MAC calculation is implemented properly, please find following sample strings and the respective correctly calculated MAC value:

    Assume merchant private key value here is: 8A!v#6qPc3?+G1on

    The request is a cancel call with following parameters:

    key value
    merchantID 123
    storeID test Store
    orderID testTransaction

    Ordered alphabetically:

    key value
    merchantID 123
    orderID testTransaction
    storeID test Store

    Remove special delimiters:

    key value
    merchantID 123
    orderID testTransaction
    storeID testStore

    The concatenated parameter string is:

    123testTransactiontestStore

    The resulting calculated MAC should be:

    7aea4cc6313b2814053488079563375bf15446631

    Callback

    Callbacks are redirects of the customer back to the shop performed by the CrefoPay system to the URLs configured for the merchants shop. For each shop one confirmation, success and error URL can be defined.

    The following GET parameters can be added to the URLs:

    Field Type Mandatory Comments
    MERCHANTID N 16 yes This is the merchant ID assigned by CrefoPay.
    STOREID AN 60 yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    ORDERID AN 30 yes This is a unique identifier for a transaction which is created by the shop.
    MERCHANTREF AN no Reference, that additionally can be set by the shop. This parameter is sent back with every call from CrefoPay to the shop
    PAYMENTMETHOD V yes The identifier of the payment method. See PaymentMethods
    LOCALE V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    PI AN 20 no The unique ID of the payment instrument. This ID is created by CrefoPay.

    Confirmation

    After a customer selected his payment method on the hosted page he will be redirected to the confirmation URL. This allows the merchant to display the selected payment method on his order confirmation page and change the final order amount accordingly if required.

    Example of a confirmation URL: https://www.example.com/testshop/confirm?merchantID=-MERCHANTID-&storeID=-STOREID-&orderID=-ORDERID-&paymentMethod=-PAYMENTMETHOD-&paymentInstrumentID=-PI-

    Successfull payment

    For all payment methods which redirect the user to a different web-page like PayPal, credit card 3D secure or Sofort the CrefoPay system redirects the customer to the success URL of the shop, in case of a successful payment. For integration type HostedPageAfter this redirection will take place for all payment methods. The available GET parameters for the success URL are identical to those of the confirmation URL.

    Example of a success URL: https://www.example.com/testshop/success?merchantID=-MERCHANTID-&storeID=-STOREID-&orderID=-ORDERID-&paymentReference=-PAYMENTREFERENCE-&merchantReference=-MERCHANTREF-

    Failed payment

    If a customer fails to complete the payment process after he was already redirected to an external payment provider, he will be redirected to the failure URL configured for the shop. This also happens if a negative response or any other error code is returned by the external payment provider. Additionally to the GET parameters available to the success and confirmation URLs, the failure URL receives a link to the hosted payment page as possible parameter. This allows the shop to redirect the customer back to the hosted payment page after he cancelled the payment process or failed to authorize the payment.

    Field Type Mandatory Comments
    PIURL V yes URL of the hosted payment page

    Notification Call

    The Merchant Notification System (MNS) is a push notification service for merchants who have integrated one of the payment systems. The MNS allows the merchant to receive a multitude of notifications asynchronously in order to decouple the merchant system from CrefoPay’s payment systems. Integrating the merchant notification system allows the merchant to react to any kind of change in the payment status of transactions that were processed

    The notification calls will be targeted at the notification-URL that is configured for the shop. Multiple notification-URLs may be configured for a single shop. This allows merchants to inform more than one system, for example shop system and ERP system

    The use of the Merchant Notification System is required to complete the checkout process. The merchant has three options on which notifications to receive:

    Request

    Field Type Mandatory Comments
    merchantID N 16 yes This is the merchant ID assigned by CrefoPay.
    storeID AN 60 yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN 30 yes This is a unique identifier for a transaction which is created by the shop.
    subscriptionID AN 30 no This is a unique identifier for a subscription which is created by the shop. This value is only set, if the transaction is related to a subscription.
    captureID AN 30 no The confirmation ID of the capture. This parameter is only sent for notifications that belong to captures.
    merchantReference AN 30 no Optional/additional reference for the transaction. This parameter is returned with every call from CrefoPay to the shop.
    paymentReference AN no The reference text to which the user needs to refer within his remittance so that CrefoPay can link the incoming payments with the outstanding amounts of a transaction.
    userID AN 50 yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    amount N 16 yes This is either the amount of an incoming payment from the end-user, the amount that is ready to be captured, or “0” in case of status changes not bound to any end-user payments coming in.
    currency AN 3 yes 3 characters, Currency code according to ISO4217. This value always matches the currency of the original transaction and is provided when the field "amount" is greater than 0.
    transactionStatus V no Current status of the transaction. Possible values:
    • NEW
    • ACKNOWLEDGEPENDING
    • FRAUDPENDING
    • FRAUDCANCELLED
    • CIAPENDING
    • MERCHANTPENDING
    • CANCELLED
    • EXPIRED
    • INPROGRESS
    • DONE
    orderStatus V no Current status of the order. Possible values:
    • PAYPENDING
    • PAID
    • CLEARED
    • PAYMENTFAILED
    • CHARGEBACK
    • INDUNNING
    • IN_COLLECTION
    additionalData J no Possible keys: accredisStatusCode
    timestamp N yes The time when the status change happened in milliseconds since 1970-01-01 (Unix timestamp in milliseconds)
    version AN yes notification version (currently 2.1)
    mac AN 40 yes Message Authentication Code see MAC calculation

    Response

    Every notification request should be answered by the merchant's system with an HTTP response of status 200. The content is not relevant and will be ignored. If there's no such response from the merchant, the merchant notification system uses a retry mechanism in order to ensure the delivery of notifications to the merchant. The merchant notification system will try to deliver the notifications:

    In cases where the notification fails to be delivered successfully after the above tries, the Notification Service will stop any further notifications. The merchant can reactivate the MNS-Service in the 'Merchant Service Area': https://service.crefopay.de in the section Settings -> Shop data and then clicking the 'Reactivate' button. Also the last error message or reason why the notifications stopped is listed there.

    API

    addPayment

    The addPayment call allows the merchant to add funds to a transaction, thereby informing CrefoPay about incoming payments. This should generally be done in case a payment was received on an account or by other means to which CrefoPay has no access and therefore cannot match the payment to a transaction.

    If it should be possible to perform a refund on this payment later on, then it is mandatory that the bank data of the account from which the payment originated from is provided.

    Payments can only be added to transaction in the following states: CIAPending, MerchantPending, InProgress, Done, Cancelled or FraudCancelled. Additionally for direct debit transactions, the transaction has to have at least one capture in the status Chargeback, InDunning or InCollection.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/addPayment

    Live: https://api.crefopay.de/2.0/addPayment

    public CrefoPayResult addPayment() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "500")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-130");
        map.add("captureID", "capture-129");
        map.add("amount", getAmount());
        map.add("valutaDate", "2019-01-15");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"d5813e5feb22b47d"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    captureID AN (30) see description This is the unique reference of a capture or a partial capture (e.g. the invoice number). Only mandatory for direct debit transactions.
    amount J (Amount) yes The amount of the received payment.
    valutaDate D (YYYY-MM-DD) yes Date on which the payment was received.
    iban AN (34) no IBAN of the bank account from which the payment was received. Required if a refund is to be performed on this payment.
    accountHolder AN (50) no The account holder of the bank account from which the payment was received. Required if a refund is to be performed on this payment later on.
    message AN (255) no Payment description
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    cancel

    The cancel call allows the merchant to cancel an transaction where no capture has been processed yet.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/cancel

    Live: https://api.crefopay.de/2.0/cancel

    <?php
    function cancel($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully cancelled the order {$orderID}.\n\r";
            return true;
        } else {
            echo "We failed to cancel the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult cancel() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-130");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"d5813e5feb22b47d"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    capture

    The capture call allows the merchant to create orders or part-orders for already started transactions

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/capture

    Live: https://api.crefopay.de/2.0/capture

    <?php
    function capture($orderID, $captureID, $transactionAmount) {
        global $requestUrl, $merchantID, $storeID;
    
        $amount = json_encode(array('amount' => $transactionAmount));
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'captureID' => $captureID,
            'amount' => $amount
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully captured the order {$orderID}. Amount: {$transactionAmount}\n\r";
            return true;
        } else {
            echo "We failed to capture the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult capture() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("captureID", "capture-129");
        map.add("amount", getAmount());
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map; 
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"39e01bcfcc9eabb1",
        "status":"PAYPENDING"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    captureID AN (30) yes This is the unique reference of a capture or a partial capture (e.g. the invoice number).
    amount J (Amount) yes Amount in the smallest possible denomination (e.g. 12399 for 123.99 Eur).
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    status AN The status of the order. PAID, PAYPENDING or PAYMENTFAILED
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    createSubscription

    The createSubscription call creates a subscription in the CrefoPay System and evaluates which paymentMethods are possible for the given user and basket data under consideration of various risk management aspects. A subscription will charge a customer in defined intervals. If a trial period is set the customer will be charged afterwards. A subscription always has a reference to an existing plan, which sets the default rate, trial period and payment interval. Though the trial period and amount can be overwritten for an individual subscription. Plans are created in the merchant service area.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/createSubscription

    Live: https://api.crefopay.de/2.0/createSubscription

    <?php
    function createSubscription($subscriptionID, $userID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters for creating a transaction here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'subscriptionID' => $subscriptionID,
            'userID' => $userID,
            'planReference => 'daily basic subscription',
            'integrationType' => 'API',
            'autoCapture' => 'false',
            'context' => 'ONLINE',
            'userType' => 'PRIVATE',
            'userRiskClass' => '0',
            'amount' => json_encode(
                array(
                    'amount' => '100',
                )
            ),
            'basketItems' => json_encode(
                array(
                    array(
                        'basketItemText' => 'User Registration Item',
                        'basketItemCount' => '1',
                        'basketItemAmount' => array(
                            'amount' => '100',
                        ),
                    ),
                )
            ),
            'locale' => 'DE'
        );
    ​
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully created the subscription {$subscriptionID}. Amount: {$transactionAmount}\n\r";
            return true;
        } else {
            echo "We failed to created the subscription: {$subscriptionID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult createSubscription() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getUserData() {
        return Json.createObjectBuilder()
                .add("name", "Max")
                .add("surname", "Mustermann")
                .add("dateOfBirth", "1978-08-15")
                .add("email", "max@mustermann.de")
                .build()
                .toString();
    }
    
    private String getBillingAddress() {
        return Json.createObjectBuilder()
                .add("street", "Hauptstraße")
                .add("no", "1")
                .add("zip", "10827")
                .add("city", "Berlin")
                .add("country", "DE")
                .build()
                .toString();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private String getBasketItems() {
        JsonArrayBuilder builder = Json.createArrayBuilder();
        builder.add(Json.createObjectBuilder().add("basketItemText", "Item1").add("basketItemCount", "1").add("basketItemAmount", Json.createObjectBuilder()
                .add("amount", "12399")).build());
        builder.add(Json.createObjectBuilder().add("basketItemText", "Item2").add("basketItemCount", "3").add("basketItemAmount", Json.createObjectBuilder()
                .add("amount", "12399")).build());
        return builder.build().toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("subscriptionID", "subscription-132");
        map.add("userID", "user-127");
        map.add("planReference", "daily basic subscription");
        map.add("context", "ONLINE");
        map.add("userType", "PRIVATE");
        map.add("userRiskClass", "0");
        map.add("userData", getUserData());
        map.add("billingAddress", getBillingAddress());
        map.add("amount", getAmount());
        map.add("basketItems", getBasketItems());
        map.add("locale", "DE");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"d9d59524d630930d",
       "userData":{  
          "name":"Max",
          "surname":"Mustermann",
          "dateOfBirth":"1978-08-15",
          "email":"max@mustermann.de"
       },
       "billingAddress":{  
          "street":"Hauptstraße",
          "no":"1",
          "zip":"10827",
          "city":"Berlin",
          "country":"DE"
       },
       "allowedPaymentMethods":[  
          "DD"
       ],
       "allowedPaymentInstruments":[  
    
       ],
       "additionalInformation":[  
          {  
             "paymentMethodType":"DD",
             "issuer":[  
    
             ],
             "logos":[  
    
             ],
             "customTranslations":{  
    
             },
             "sepaPaymentType":"RCUR",
             "mandateReference":"535357",
             "creditorId":"DE39ZZZ00001385300",
             "merchantName":"DEMO",
             "date":"13.08.2018"
          }
       ]
    }
    
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    subscriptionID AN (30) yes This is a unique identifier for a subscription which is created by the shop.
    planReference AN (15) yes ID of the plan that the subscription will be based upon.
    trialPeriod N (3) no Trial period in days. Range from 1 to 366
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    merchantReference AN (30) no Optional/additional reference for the transaction. This parameter is returned with every call from CrefoPay to the shop.
    userType V yes This parameter defines business or private customers. This value cannot be changed after user creation.. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    userRiskClass N (1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the userRiskClass or the basketItemRiskClass in the basket items has to be set.
    userIpAddress AN (15) no The IP address of the customer
    companyData J (Company) see comment Contact data of the user's company. This field is mandatory if the userType is BUSINESS and the userID was not registered before
    userData J (Person) see comment Contact data of the user. This field is mandatory if the userType is PRIVATE and the userID was not registered before
    billingRecipient AN (80) no Recipient for the Bill.
    billingAddress J (Address) see comment The user's billing address. This field is mandatory if if user was not registered before with this userID
    shippingRecipient AN (80) no Recipient for shipping
    shippingAddress J (Address) no The customers shipping address
    amount J (Amount) yes The amount of the subscription
    basketItems JA (Basket Item) yes A detailed list of all basket items
    basketValidity AN (4) no m -> minutes, h -> hours, d -> days; Example: one hour: 1h, ten minutes: 10m, two days: 2d - only one unit of time can be provided
    locale V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    • 0 -> OK
    • 1 -> redirect
    • any other code -> see errorcodes
    message AN This parameter contains details about an error, otherwise it will left as empty.
    userData J (Person) Data of the user
    billingAddress J (Address) Address of the user
    companyData J (Company) Data of the company
    allowedPaymentMethods JA (PaymentMethods) List of payment methods that are allowed for this user
    allowedPaymentInstruments JA (PaymentInstrument) List of valid payment instruments that are registered for this user
    redirectUrl AN (1024) The URL of the page that should be shown to the user. This is only set if the resultCode is 1
    additionalInformation JA (PaymentMethodInformation) List of additional information for presenting the payment instruments to the customer.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    createTransaction

    This call starts a transaction in the CrefoPay system. The workflow depends on the integrationType. For more information refer to Integration options. Further, this call can act both as registerUser and updateUser call if an unknown/known userID is provided, often making the implementation of these calls unnecessary

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/createTransaction

    Live: https://api.crefopay.de/2.0/createTransaction

    <?php
    function createTransaction($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters for creating a transaction here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'userID' => $userID,
            'integrationType' => 'API',
            'autoCapture' => 'false',
            'context' => 'ONLINE',
            'userType' => 'PRIVATE',
            'userRiskClass' => '0',
            'amount' => json_encode(
                array(
                    'amount' => '100',
                )
            ),
            'basketItems' => json_encode(
                array(
                    array(
                        'basketItemText' => 'User Registration Item',
                        'basketItemCount' => '1',
                        'basketItemAmount' => array(
                            'amount' => '100',
                        ),
                    ),
                )
            ),
            'locale' => 'DE'
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully created the order {$orderID}. Amount: {$transactionAmount}\n\r";
            return true;
        } else {
            echo "We failed to created the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    
    public CrefoPayResult createTransaction() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getUserData() {
        return Json.createObjectBuilder()
                .add("name", "Max")
                .add("surname", "Mustermann")
                .add("dateOfBirth", "1978-08-15")
                .add("email", "max@mustermann.de")
                .build()
                .toString();
    }
    
    private String getBillingAddress() {
        return Json.createObjectBuilder()
                .add("street", "Hauptstraße")
                .add("no", "1")
                .add("zip", "10827")
                .add("city", "Berlin")
                .add("country", "DE")
                .build()
                .toString();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private String getBasketItems() {
        JsonArrayBuilder builder = Json.createArrayBuilder();
        builder.add(Json.createObjectBuilder().add("basketItemText", "Item1").add("basketItemCount", "1").add("basketItemAmount", Json.createObjectBuilder()
                .add("amount", "12399")).build());
        builder.add(Json.createObjectBuilder().add("basketItemText", "Item2").add("basketItemCount", "3").add("basketItemAmount", Json.createObjectBuilder()
                .add("amount", "12399")).build());
        return builder.build().toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-124");
        map.add("userID", "user-127");
        map.add("context", "ONLINE");
        map.add("userType", "PRIVATE");
        map.add("userRiskClass", "0");
        map.add("userData", getUserData());
        map.add("billingAddress", getBillingAddress());
        map.add("amount", getAmount());
        map.add("basketItems", getBasketItems());
        map.add("locale", "DE");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"d9f7268bb493e51b",
       "userData":{  
          "name":"Max",
          "surname":"Mustermann",
          "dateOfBirth":"1978-08-15",
          "email":"max@mustermann.de"
       },
       "billingAddress":{  
          "street":"Hauptstraße",
          "no":"1",
          "zip":"10827",
          "city":"Berlin",
          "country":"DE"
       },
       "allowedPaymentMethods":[  
          "CC",
          "PAYPAL",
          "BILL"
       ],
       "allowedPaymentInstruments":[  
          {  
             "paymentInstrumentID":"Aqc9O5SSJuQTDHC9KXFE0Q",
             "paymentInstrumentType":"CREDITCARD",
             "accountHolder":"Max Mustarmann",
             "number":"************1111",
             "validity":"2025-01",
             "issuer":"VISA",
             "mandatoryReserveFields":[  
                "cvv"
             ]
          }
       ],
       "additionalInformation":[  
          {  
             "paymentMethodType":"CC",
             "issuer":[  
                "VISA",
                "MC"
             ],
             "logos":[  
                "VISA",
                "MC"
             ],
             "customTranslations":{  
    
             }
          },
          {  
             "paymentMethodType":"PAYPAL",
             "issuer":[  
    
             ],
             "logos":[  
    
             ],
             "customTranslations":{  
    
             }
          },
          {  
             "paymentMethodType":"BILL",
             "issuer":[  
    
             ],
             "logos":[  
    
             ],
             "customTranslations":{  
    
             }
          }
       ]
    }
    
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    integrationType V no The type of integration in the web shop. Possible Values:
    • API (default)
    • SecureFields
    • HostedPageBefore
    • HostedPageAfter
    autoCapture B no Enable automatic capture directly after the successful reservation, if the parameter is not set, the default is "false"
    merchantReference AN (30) no Optional/additional reference for the transaction. This parameter is returned with every call from CrefoPay to the shop.
    context V no Determines if the transaction was initiated during online-checkout process or offline where no direct user interaction happens. Will be set to ONLINE by default if not provided. Possible Values:
    • ONLINE
    • MAIL_ORDER
    • TELEPHONE_ORDER
    • PAY_BY_LINK
    userType V yes This parameter defines business or private customers. This value cannot be changed after user creation. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    userRiskClass N (1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the userRiskClass or the basketItemRiskClass in the basket items has to be set.
    userIpAddress AN (39) no The IP address of the customer. Supported formats are IPv4 and IPv6
    companyData J (Company) see comment Contact data of the user's company. This field is mandatory if the userType is BUSINESS and the userID was not registered before
    userData J (Person) see comment Contact data of the user. This field is mandatory if the userType is PRIVATE and the userID was not registered before
    creditLimit J (Amount) no If this field is provided then the value is saved as specific credit limit for this customer only. Any previously saved credit limit will be overwritten.
    billingRecipient AN (80) no Recipient for the Bill.
    billingAddress J (Address) see comment The user's billing address. This field is mandatory if if user was not registered before with this userID
    shippingRecipient AN (80) no Recipient for shipping
    shippingAddress J (Address) no The customers shipping address
    amount J (Amount) yes The amount of the basket
    basketItems JA (Basket Item) yes A detailed list of all basket items
    basketValidity AN (4) no m -> minutes, h -> hours, d -> days; Example: one hour: 1h, ten minutes: 10m, two days: 2d - only one unit of time can be provided
    hostedPagesTexts JA (HostedPages text) no A list of texts for the hosted page in for different languages for different payment methods
    locale V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    additionalPaymentOptions J (Payment options) no additional options
    solvencyCheckInformation J (Solvency check information) no result of a solvency check done by the merchant.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    • 0 -> OK
    • 1 -> redirect
    • any other code -> see errorcodes
    message AN This parameter contains details about an error, otherwise it will left as empty.
    userData J (Person) Data of the user
    billingAddress J (Address) Address of the user
    companyData J (Company) Data of the company
    allowedPaymentMethods JA (PaymentMethods) List of payment methods that are allowed for this user
    allowedPaymentInstruments JA (PaymentInstrument) List of valid payment instruments that are registered for this user
    redirectUrl AN (1024) The URL of the page that should be shown to the user. This is only set if the resultCode is 1
    additionalInformation JA (PaymentMethodInformation) List of additional informations for presenting the payment instruments to the customer.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    Handling of Packstation addresses

    deleteUserPaymentInstrument

    The deleteUserPaymentInstrument call adds the functionality to delete a payment instrument from a user.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/deleteUserPaymentInstrument

    Live: https://api.crefopay.de/2.0/deleteUserPaymentInstrument

    <?php
    function deleteUserPaymentInstrument($paymentInstrumentID) {
        global $requestUrl, $merchantID;
    
        $param = array(
            'merchantID' => $merchantID,
            'paymentInstrumentID' => $paymentInstrumentID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully deleted the paymentinstrument {$paymentInstrumentID}\n\r";
            return true;
        } else {
            echo "We failed to delete the paymentinstrument: {$paymentInstrumentID}\n\r Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult deleteUserPaymentInstrument() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("paymentInstrumentID", "b2z4aogwDQJbvH144Kwt8g");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"951733fa7ecc7a7e"
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    paymentInstrumentID AN (20) yes The unique identifier of the payment instrument
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response:

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    finish

    The finish call allows the merchant to finish an transaction where at least one capture has been created. All overpaid amounts are paid back to the user, but also all open captures are voided.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/finish

    Live: https://api.crefopay.de/2.0/finish

    <?php
    function finish($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully finished the order {$orderID}.\n\r";
            return true;
        } else {
            echo "We failed to finish the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult finish() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"39b83acd3064a20b"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getCaptureStatus

    This call returns the status of a captured order.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getCaptureStatus

    Live: https://api.crefopay.de/2.0/getCaptureStatus

    <?php
    function getCaptureStatus($orderID, $captureID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'captureID' => $captureID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the status for the capture: {$captureID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the status for capture: {$captureID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getCaptureStatus() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("captureID", "capture-129");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"761493d8ca3ef46c",
       "captureStatus":"PAID",
       "additionalData":{  
          "transactionAmount":12399,
          "capturedAmount":12399,
          "paidAmount":12276,
          "creditAmount":123,
          "reducedAmount":0,
          "guaranteedAmount":0,
          "returnedGuaranteeAmount":0,
          "feeAmount":0,
          "openAmount":0,
          "transactionCurrency":"EUR"
       }
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    captureID AN (30) yes This is the unique reference of a capture or a partial capture (e.g. the invoice number).
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    captureStatus V The status of a capture. Possible values: see capture process
    additionalData J (CaptureStatusDetail) Additional information to the capture
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getClearingFileList

    getClearingFileList allows to enter a time frame. As response you’ll get a list with the ID of clearing files, which have been created in this period.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getClearingFileList

    Live: https://api.crefopay.de/2.0/getClearingFileList

    <?php
    function getClearingFileList($orderID, $from, $to) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'from' => $from,
            'to' => $to
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the clearingFileList.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the clearingFileList\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getClearingFileList() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("from", "2017-09-01");
        map.add("to", "2017-11-01");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"f1b1c0bd7d6c0fe2",
       "clearingFiles":[  
          {  
             "clearingID":"2028",
             "from":"2017-10-18",
             "to":"2017-10-19"
          },
          {  
             "clearingID":"2013",
             "from":"2017-10-03",
             "to":"2017-10-04"
          },
          {  
             "clearingID":"2005",
             "from":"2017-09-25",
             "to":"2017-09-26"
          },
          {  
             "clearingID":"2002",
             "from":"2017-09-22",
             "to":"2017-09-23"
          }
       ]
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    from D (YYYY-MM-DD) yes The from date is including
    to D (YYYY-MM-DD) no The to date is excluding
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    clearingFiles J (ClearingFile) List of clearing file IDs and their respective time frames, which are contained in the initially provided time frame
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getClearingFiles

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getClearingFiles

    Live: https://api.crefopay.de/2.0/getClearingFiles

    public String getClearingFiles() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<byte[]> response = restTemplateService.sendFileDownloadPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK) {
            throw new RuntimeException(response.getStatusCode().toString());
        }
        return new String(response.getBody());
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("clearingFileID", "2028");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    clearingFileID AN (100) yes The ID of the clearing file to download
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    The response will be a zipped version of one ore more csv-files that contain the clearing information. The files are split after 16000 lines The response has the MIME type application/octet-stream. If the file is not found, http code 404 will be returned

    getSubscriptionPlans

    The getSubscriptionPlans call provides details of all subscription plans created in the CrefoPay system. The result can be filtered using parameters. This call can be used to dynamically display subscription plans in a shop front-end or to receive a specific plan ID for use in the createSubscription call.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getSubscriptionPlans

    Live: https://api.crefopay.de/2.0/getSubscriptionPlans

    <?php
    function getSubscriptionPlans() {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the plans for store: {$storeID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the plans for store: {$storeID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getSubscriptionPlans() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"d53159b2fc5118e1",
       "pageNumber":2,
       "pageSize":100,
       "totalEntries":11,
       "subscriptionPlans":[  
          {  
             "planReference":"bas",
             "name":"basic",
             "description":"daily basic subscription",
             "interval":"DAILY",
             "hasSubscribers":true,
             "amount":{  
                "amount":499
             }
          },
          {  
             "planReference":"pre",
             "name":"premium",
             "description":"daily premium subscription",
             "interval":"DAILY",
             "hasSubscribers":true,
             "amount":{  
                "amount":999
             }
          }
       ]
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    interval V no Possible values are:
    • DAILY
    • WEEKLY
    • FORTNIGHTLY
    • FOUR_WEEKLY
    • MONTHLY
    • QUARTERLY
    • BIANNUALLY
    • YEARLY
    trialPeriodRange J no Range object of numeric type with values between 1 and 366 ( {minimum: number, maximum: number} )
    pageNumber N no Number of the page that should be returned.
    pageSize N (3) no Amount of results returned per page. (1-100)
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    pageNumber N Number of the page that was returned.
    pageSize N (3) Amount of results returned per page. (1-100)
    totalEntries N The total amount of results.
    subscriptionPlans JA (SubscriptionPlan) Contains information of all plans that fit the provided parameters.
    salt AN A random number to guarantee the uniqueness of the message.

    getTransactionPaymentInstruments

    This call gets a refreshed list of payment instruments. This is useful if the reserve call fails because of problems with a specific payment instrument or because of fraud rules. This call will only work in TransactionStatus 'NEW' The list of payment instruments returned by this call is the same or less like the list returned by create transaction.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getTransactionPaymentInstruments

    Live: https://api.crefopay.de/2.0/getTransactionPaymentInstruments

    <?php
    function getTransactionPaymentInstruments($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the paymentinstrument for order: {$orderID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the paymentinstrument for order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getTransactionPaymentInstruments() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-131");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"8d83157f738bca24",
       "userData":{  
          "name":"Max",
          "surname":"Mustermann",
          "dateOfBirth":"1978-08-15",
          "email":"max@mustermann.de"
       },
       "billingAddress":{  
          "street":"Hauptstraße",
          "no":"1",
          "zip":"10827",
          "city":"Berlin",
          "country":"DE"
       },
       "allowedPaymentMethods":[  
          "CC",
          "PAYPAL"
       ],
       "allowedPaymentInstruments":[  
    
       ],
       "additionalInformation":[  
          {  
             "paymentMethodType":"CC",
             "issuer":[  
                "VISA",
                "MC"
             ],
             "logos":[  
                "VISA",
                "MC"
             ],
             "customTranslations":{  
    
             }
          },
          {  
             "paymentMethodType":"PAYPAL",
             "issuer":[  
    
             ],
             "logos":[  
    
             ],
             "customTranslations":{  
    
             }
          },
       ],
       "billingRecipient":"Max Mustermann"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    userData J (Person) Data of the user
    billingAddress J (Address) Address of the user
    companyData J (Company) Data of the company
    allowedPaymentMethods JA (PaymentMethods) List of payment methods that are allowed for this user
    allowedPaymentInstruments JA (PaymentInstrument) List of valid payment instruments that are registered for this user
    redirectUrl AN (1024) The URL of the page that should be shown to the user. This is only set if the resultCode is 1
    additionalInformation JA (PaymentMethodInformation) List of additional informations for presenting the payment instruments to the customer.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getTransactionStatus

    This call returns the status of a transaction.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getTransactionStatus

    Live: https://api.crefopay.de/2.0/getTransactionStatus

    <?php
    function getTransactionetatus($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the status for order: {$orderID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the status for order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getTransactionetatus() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"9bbc1ca20347517d",
       "transactionStatus":"DONE",
       "additionalData":{  
          "paymentMethod":"BILL",
          "paymentReference":"PCB-0000668890",
          "accountHolder":"Max Mustermann",
          "iban":"DE06000000000023456789",
          "bankname":"Postbank",
          "bic":"SFRTDE20000",
          "customerEmail":"max@mustermann.de",
          "transactionAmount":12399,
          "transactionCurrency":"EUR"
       },
       "billingAddress": {
          "street": "Teststraße",
          "no": "123",
          "zip": "10961",
          "city": "Berlin",
          "country": "DE",
          "name": "Max Mustermann"
      },
       "shippingAddress": {
          "street": "Teststraße",
          "no": "123",
          "zip": "10961",
          "city": "Berlin",
          "country": "DE",
          "name": "Max Mustermann"
      }
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    returnRiskData B no Set to 'true' if solvency-check information should be returned in the response
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    transactionStatus V The status of the transaction referred by the order ID. Possible values: see Transaction process
    riskData J (RiskData) This array contains data of all solvency-checks that are connected to the transaction
    additionalData J (TransactionStatusDetail) Additional information to the transaction
    billingAddress J (Address) The customer's billing address
    shippingAddress J (Address) The customer's shipping address
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getUser

    The getUser call adds the functionality to get the data and the status of a user.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getUser

    Live: https://api.crefopay.de/2.0/getUser

    <?php
    function getUser($userID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'userID' => $userID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the user: {$userID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the user: {$userID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getUser() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-127");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"c1d5c2585402b44a",
       "userData":{  
          "name":"Max",
          "surname":"Mustermann",
          "dateOfBirth":"1978-08-15",
          "email":"max@mustermann.de"
       },
       "billingRecipient":"Max Mustermann",
       "billingAddress":{  
          "street":"Hauptstraße",
          "no":"1",
          "zip":"10827",
          "city":"Berlin",
          "country":"DE"
       },
       "shippingRecipient":"Max Mustermann",
       "shippingAddress":{  
          "street":"Hauptstraße",
          "no":"1",
          "zip":"10827",
          "city":"Berlin",
          "country":"DE"
       },
       "locale":"DE"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    returnRiskData B no Set to 'true' if solvency-check information should be returned in the response
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    companyData J (Company) Contact data of the user's company
    salutation V Possible values:
    • F -> Female
    • M -> Male
    name AN Person's name
    surname AN Person's surname
    dateOfBirth D (YYYY-MM-DD) Date of birth.
    email AN
    phoneNumber N Person's phone number with leading zero
    userData J (Person) Contact data of the user
    billingRecipient AN Recipient for the billing address
    billingAddress J (Address) The person's billing address
    shippingRecipient AN Recipient for shipping address
    shippingAddress J (Address) The person's shipping address
    lastUsedPaymentInstrumentID AN The ID of the payment instrument that was last used by the user
    userStatus V Possible values:
    • NEW
    • IN_DUNNING
    • IN_COLLECTION
    • NEGATIVE_PAYMENT_EXPERIENCE
    • SUCCESSFUL_DUNNING
    . This value will only be set if the merchant/shop uses the accredis dunning and collection interface.
    riskData J (RiskData) This array contains data of all solvency-checks that were requested for this user
    locale V yes
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    getUserPaymentInstrument

    The getUserPaymentInstrument call adds the functionality to get a user‘s PaymentInstruments.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/getUserPaymentInstrument

    Live: https://api.crefopay.de/2.0/getUserPaymentInstrument

    <?php
    function getUserPaymentInstrument($userID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'userID' => $userID
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully received the paymentinstruments for user: {$userID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the paymentinstruments for user: {$userID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getUserPaymentInstrument() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-127");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"140e15d63d36eba6",
       "paymentInstruments":[  
          {  
             "paymentInstrumentID":"Aqc9O5SSJuQTDHC9KXFE0Q",
             "paymentInstrumentType":"CREDITCARD",
             "accountHolder":"Max Mustarmann",
             "number":"************1111",
             "validity":"2025-01",
             "issuer":"VISA"
          }
       ]
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    mac AN 40 yes Message Authentication Code. See: MAC calculation

    Response:

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    paymentInstruments JA (PaymentInstrument) List of valid payment instruments that are registered for this user
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    The PayByLink via API solution allows the creation of payment links based on the provided parameters and to optionally send these automatically to the customer.

    Similar to other integration types the createTransaction call is used to initiate a transaction, with the main difference being that less parameters are required. After providing the data several risk checks are performed, which make decisions on which payment methods the customer will be able to select from. Depending on the amount of data provided some risk checks may not be performed.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/createTransaction

    Live: https://api.crefopay.de/2.0/createTransaction

    <?php
    function createTransactionPayByLink($orderID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters for creating a transaction here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'integrationType' => 'HostedPageAfter',
            'context' => 'PAY_BY_LINK',
            'amount' => json_encode(
                array(
                    'amount' => '100',
                )
            )
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully created the payByLink order {$orderID}. Amount: {$transactionAmount}\n\r";
            return true;
        } else {
            echo "We failed to created the payByLink order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult createTransactionPayByLink() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 1) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-133");
        map.add("integrationType", "HostedPageAfter");
        map.add("context", "PAY_BY_LINK");
        map.add("amount", getAmount());
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":1,
        "salt":"1647a342d1917ae3",
        "redirectUrl":"https://sandbox.crefopay.de/hosted-pages/5b719933bca0266009608be6"
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    sendPayByLinkEmail B no Decides whether to automatically send the payment link via email to the customer. If set to 'true', it is mandatory to provide an email address of the customer. If set to 'false', no mail delivery will be triggered and no email address is required. If the value is not provided it is set to 'false' by default.
    userID AN 50 no The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    integrationType V yes Possible Values:
    • HostedPageAfter
    A PayByLink transaction requires the integrationType to be set to 'HostedPageAfter'.
    autoCapture B no Enable automatic capture directly after the successful reservation, if the parameter is not set, the default is "false"
    merchantReference AN (30) no Optional/additional reference for the transaction. This parameter is returned with every call from CrefoPay to the shop.
    context V yes Determines if the transaction was initiated during online-checkout process or offline where no direct user interaction happens. Possible Values:
    • PAY_BY_LINK
    A PayByLink transaction requires the context to be set to 'PAY_BY_LINK'
    userType V no This parameter defines business or private customers. This value cannot be changed after user creation.. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    If no value is provided it defaults to PRIVATE
    userRiskClass N (1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the userRiskClass or the basketItemRiskClass in the basket items has to be set.
    userIpAddress AN (15) no The IP address of the customer
    companyData J (Company) no Contact data of the user's company. If automatic payment emails should be triggered at least the parameter 'email' has to be provided in the J (Company) object.
    userData J (Person) no Contact data of the user. If automatic payment emails should be triggered at least the parameter 'email' has to be provided in the J (Person) object. The field "date of birth" is not mandatory. It's needed for solvency checks and the payment method "bill secure". An absent "date of birth" could cause less payment methods to be offered to the user.
    billingRecipient AN (80) no Recipient for the billing address
    billingAddress J (Address) no The user's billing address. This field is mandatory if the user was not registered before with this userID
    shippingRecipient AN (80) no Recipient for the shipping address
    shippingAddress J (Address) no The user's shipping address
    amount J (Amount) yes The amount of the basket
    basketItems JA (Basket Item) no A detailed list of all basket items
    basketValidity AN (4) no m -> minutes, h -> hours, d -> days; Example: one hour: 1h, ten minutes: 10m, two days: 2d - only one unit of time can be provided
    hostedPagesTexts JA (HostedPages text) no A list of texts for the hosted page in for different languages for different payment methods
    locale V no The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    additionalPaymentOptions J (Payment options) no additional options
    solvencyCheckInformation J (Solvency check information) no result of a solvency check done by the merchant.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    • 0 -> OK
    • 1 -> redirect
    • any other code -> see errorcodes
    message AN This parameter contains details about an error, otherwise it will left as empty.
    redirectUrl AN The url of the hosted page that should be shown to the user. This is only set if the resultCode is 1
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    Handling of Packstation addresses

    refund

    The refund call allows the merchant to return money to the user. At least one capture on a transaction is required to perform a refund; therefore the call cannot be used on transactions in status NEW, ACKNOWLEDGEPENDING or MERCHANTPENDING.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/refund

    Live: https://api.crefopay.de/2.0/refund

    <?php
    function refund($orderID, $captureID, $transactionAmount, $refundDescription) {
        global $requestUrl, $merchantID, $storeID;
    
        $amount = json_encode(array('amount' => $transactionAmount));
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'captureID' => $captureID,
            'refundDescription' => $refundDescription,
            'amount' => $amount
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully refunded the order {$orderID}. Amount: {$transactionAmount}\n\r";
            return true;
        } else {
            echo "We failed to refund the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult refund() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("captureID", "capture-129");
        map.add("refundDescription", "refund");
        map.add("amount", getAmount());
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"b414f1f508e0d653"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    captureID AN (30) yes This is the unique reference of a capture or a partial capture (e.g. the invoice number).
    refundDescription AN (256) yes Description to be shown to the end user on the refund
    amount J (Amount) yes The amount of the refund
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    registerUser

    The registerUser call adds the functionality to register a new user.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/registerUser

    Live: https://api.crefopay.de/2.0/registerUser

    public CrefoPayResult registerUser() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getUserData() {
        return Json.createObjectBuilder()
                .add("name", "Max")
                .add("surname", "Mustermann")
                .add("dateOfBirth", "1978-08-15")
                .add("email", "max@mustermann.de")
                .build()
                .toString();
    }
    
    private String getBillingAddress() {
        return Json.createObjectBuilder()
                .add("street", "Hauptstraße")
                .add("no", "1")
                .add("zip", "10827")
                .add("city", "Berlin")
                .add("country", "DE")
                .build()
                .toString();
    }
    
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-123");
        map.add("userType", "PRIVATE");
        map.add("userRiskClass", "0");
        map.add("userData", getUserData());
        map.add("billingAddress", getBillingAddress());
        map.add("email", "max@mustermann.de");
        map.add("locale", "DE");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"029ebe3a1ea785e0"
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    userType V yes This parameter defines business or private customers. This value cannot be changed after user creation.. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    userRiskClass N (1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the userRiskClass or the basketItemRiskClass in the basket items has to be set.
    companyData J (Company) see comment Information about the user's company. This field is mandatory if the userType is BUSINESS and the userID was not registered before
    userData J (Person) see comment Information about the user. This field is mandatory if the userType is PRIVATE and the userID was not registered before
    creditLimit J (Amount) no If this field is provided then the value is saved as specific credit limit for this customer only.
    billingRecipient AN (80) no Recipient for the billing address.
    billingAddress J (Address) see comment The user's billing address. This field is mandatory if the user was not registered before with this userID
    shippingRecipient AN (80) no Recipient for the shipping address
    shippingAddress J (Address) no The user's shipping address
    locale V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    solvencyCheckInformation J (Solvency check information) no Result of a solvency check done by the merchant.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    registerUserPaymentInstrument

    The registerUserPaymentInstrument call adds the functionality to register a payment instrument to a user.

    Anyone involved with the processing, transmission, or storage of credit card data must comply with the Payment Card Industry Data Security Standards PCI DSS. If your system is not compliant please a different ingetration type, see: Integration options.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/registerUserPaymentInstrument

    Live: https://api.crefopay.de/2.0/registerUserPaymentInstrument

    public CrefoPayResult registerUserPaymentInstrument() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getPaymentInstrumentString() {
        return Json.createObjectBuilder()
                .add("paymentInstrumentType", "CREDITCARD")
                .add("accountHolder", "John Doe")
                .add("number", "4111111111111111")
                .add("validity", "2025-01")
                .add("issuer", "VISA")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-127");
        map.add("paymentInstrument", getPaymentInstrumentString());
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"17cb8cb80c38a7c8",
        "paymentInstrumentID":"Aqc9O5SSJuQTDHC9KXFE0Q"
    }
    
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    paymentInstrument J (PaymentInstrument) yes The payment instrument to register. The PaymentInstrumentID has to be empty
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response:

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    paymentInstrumentID AN 20 Unique ID for this payment instrument, to be used in the reserve API
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    reserve

    Please make sure that createTransaction was called successfully before calling the reserve call.

    If the option "autoCapture" was enabled within the createTransaction call, a capture call does not have to be performed afterwards; instead the CrefoPay system will instantly create a capture with the orderID as captureID.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/reserve

    Live: https://api.crefopay.de/2.0/reserve

    <?php
    function reserve($orderID, $paymentMethod) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'orderID' => $orderID,
            'paymentMethod' => $paymentMethod
        );
    
        // Add calculated MAC to params
        $param['mac'] = getMac($param);
    
        // Create POST body
        $postData = http_build_query($param);
        // Build your own communication function
        $responseBody = sendRequest($postData, $requestUrl); // Returns an object
        if($responseBody === false) {
            return false;
        }
    
        // Collect resultCode from response object
        $resultCode = $responseBody->resultCode;
    
        if ($resultCode === 0) {
            echo "We successfully reserved the order: {$orderID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to reserve the order: {$orderID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult reserve() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-125");
        map.add("paymentMethod", "BILL");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {  
       "resultCode":0,
       "salt":"cae2f36e6c251692",
       "additionalData":{  
          "bankname":"Postbank",
          "bic":"SFRTDE20000",
          "iban":"DE06000000000023456789",
          "bankAccountHolder":"Max Mustermann",
          "paymentReference":"PCB-0000668888"
       }
    }
    
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.. The subscriptionID of a subscription will be accepted as well.
    paymentMethod V yes The payment method that should be used. See: supported PaymentMethods
    paymentInstrumentID AN (20) no The unique ID of the payment instrument. This ID is created by CrefoPay. Required for payment method CC, CC3D, DD.
    additionalInformation J (ReserveInformationRequest) no Additional information needed for some payment methods
    amount J (Amount) no The amount of the basket. If this field is set, it will overwrite the amount that was set in the createTransaction call
    basketItems JA (Basket Item) no A detailed list of all basket items. If this field is set, it will overwrite the basketItems that were set in the createTransaction call
    cvv AN (4) no CVV for credit card transactions.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response:

    Field Type Comments
    resultCode N
    • 0 -> OK
    • 1 -> redirect
    • any other code -> see errorcodes
    message AN This parameter contains details about an error, otherwise it will left as empty.
    redirectUrl AN Will only be returned if the user has to be redirected to the website of a third party payment provider like CC3D, PAYPAL or SU (Sofort)
    additionalData J (ReserveInformationResponse) Additional information will be set only in case of PREPAID, BILL and BILL_SECURE Payments
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    For redirect payment methods CrefoPay will redirect the customer back to either the success or the failure URL configured for the shop after they either finished or failed payment authorization at the website of a third party provider. For more information about callbacks see: Callback

    solvencyCheck

    The solvencyCheck call allows the merchant to perform solvency checks on business customers independent of the transaction workflow.

    The response to the solvencyCheck call will contain a score that is returned based on the solvency check configuration in the CrefoPay system. If exact check report data is required, the results can be fetched using the getUser call. Similar to createTransaction, this call will act as registerUser or updateUser call if an unknown/known userID is provided.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/solvencyCheck

    Live: https://api.crefopay.de/2.0/solvencyCheck

    public CrefoPayResult solvencyCheck() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getUserData() {
        return Json.createObjectBuilder()
                .add("name", "Max")
                .add("surname", "Mustermann")
                .add("dateOfBirth", "1978-08-15")
                .add("email", "max@mustermann.de")
                .build()
                .toString();
    }
    
    private String getBillingAddress() {
        return Json.createObjectBuilder()
                .add("street", "Hauptstraße")
                .add("no", "1")
                .add("zip", "10827")
                .add("city", "Berlin")
                .add("country", "DE")
                .build()
                .toString();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-127");
        map.add("userType", "PRIVATE");
        map.add("userData", getUserData());
        map.add("billingAddress", getBillingAddress());
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "checkResult":0,
        "salt":"e59bb022501b780c",
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    userType V yes This parameter defines business or private customers. This value cannot be changed after user creation. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    companyData J (Company) see comment Contact data of the user's company. This field is mandatory if the userType is BUSINESS and the userID was not registered before
    userData J (Person) see comment Contact data of the user. This field is mandatory if the userType is PRIVATE and the userID was not registered before
    billingAddress J (Address) see comment The user's billing address. This field is mandatory if if user was not registered before with this userID
    billingRecipient AN (80) no Recipient for the Bill.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    checkResult N
    • 0 -> Low risk, accept user
    • 1 -> Medium risk, restrict user
    • 2 -> High risk, decline user
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    updateInvoice

    With updateInvoice, it is possible to send additional invoice information for an existing transaction, if e.g. the invoice data for a transaction is only generated by the ERP system after checkout. The provision of invoice date is necessary, if you also want to process dunning and debt collection via the CrefoPay partner, since the call centre of the debt collection agency requires this data for information provision purposes. Furthermore, you can also transmit the due date for account purchases and overwrite the preset due date individually for every transaction.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/updateInvoice

    Live: https://api.crefopay.de/2.0/updateInvoice

    public CrefoPayResult updateInvoice() {
        final LinkedMultiValueMap<String, Object> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendMultipartPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getAmount() {
        return Json.createObjectBuilder()
                .add("amount", "12399")
                .build()
                .toString();
    }
    
    private FileSystemResource getInvoice() {
        return new FileSystemResource("/tmp/file.pdf");
    }
    
    private LinkedMultiValueMap<String, Object> getRequestMap() {
        LinkedMultiValueMap<String, Object> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("captureID", "capture-129");
        map.add("invoiceNumber", "invoice-1");
        map.add("invoiceDate", "2018-01-01");
        map.add("originalInvoiceAmount", getAmount());
        map.add("dueDate", "2018-03-01");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
    
        //the invoicePDF is not part of the mac
        map.add("invoicePDF", getInvoice());
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"b3035fc8a72cb252"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    captureID AN (30) no This is the unique reference of a capture or a partial capture (e.g. the invoice number).
    invoiceNumber AN (50) yes The invoice number
    invoiceDate D (YYYY-MM-DD) yes The date when the in voice was created
    originalInvoiceAmount J (Amount) yes The original amount of the invoice. Please refer also to the information box below.
    dueDate D (YYYY-MM-DD) yes, if payment method is Bill Payment date of the invoice
    paymentTarget D (YYYY-MM-DD) no Only relevant, if payment method is Bill: payment target to pay the invoice. Please refer also to the information box below.
    shippingDate D (YYYY-MM-DD) no The sending date of the order
    trackingID AN (50) no The tracking ID of the sending
    remark AN (500) no Free text field to pass additional information like article numbers etc. so that the collection agency can see, which item is associated with the dunning process
    invoicePDF Multipart attachment no The original invoice as PDF. This parameter has to be ignored for the mac calculation
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    updateSubscription

    The updateSubscription call is used to update the charge rate or cancel an active subscription.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/updateSubscription

    Live: https://api.crefopay.de/2.0/updateSubscription

    
    public CrefoPayResult updateSubscription() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("subscriptionID", "subscription-134");
        map.add("action", "CHANGE_RATE");
        map.add("rate", "200");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"01ebbd8ccb51b8d9"
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    subscriptionID AN (30) yes This is a unique identifier for a subscription which is created by the shop.
    action V yes Possible Values:
    • CHANGE_RATE
    • CANCEL
    rate N (9) no Amount to which the subscription rate should be updated to. Only required if the action is CHANGE_RATE
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    updateTransactionData

    With updateTransactionData the merchantReference of a transaction can be set or updated. The merchantReference can be used as an alternative for automated payment matching if the paymentReference provided by CrefoPay can not be forwarded to customers. In this case it is advisable to update the merchantReference of the transaction to whatever value was given to the customer as payment reference for their bank transfer.

    This call may be extended in the future to allow further modification of transaction data.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/updateTransactionData

    Live: https://api.crefopay.de/2.0/updateTransactionData

    public CrefoPayResult updateTransactionData() {
        final LinkedMultiValueMap<String, Object> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendMultipartPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private LinkedMultiValueMap<String, Object> getRequestMap() {
        LinkedMultiValueMap<String, Object> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("orderID", "order-129");
        map.add("merchantReference", "bill-501234");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode": 0,
        "salt": "250ffaf62f444faa",
        "updatedData": {
            "merchantReference": {
                "oldValue": "oldMerchantReference",
                "newValue": "bill-501234"
            }
        }
    }
    

    Request:

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID AN (30) yes This is a unique identifier for a transaction which is created by the shop.
    merchantReference AN (30) no Optional/additional reference for the transaction. This parameter is returned with every call from CrefoPay to the shop.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    updatedData J (UpdatedData) Contains the fields that were updated, their new values (newValue), and the old values if any were overwritten (oldValue). Only set if any fields were updated.
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    updateUser

    The updateUser call adds the functionality to update a user's details like billing and or delivery address.

    URL:

    Sandbox: https://sandbox.crefopay.de/2.0/updateUser

    Live: https://api.crefopay.de/2.0/updateUser

    public CrefoPayResult updateUser() {
        final MultiValueMap<String, String> map = getRequestMap();
        ResponseEntity<CrefoPayResult> response = restTemplateService.sendPostRequest(url, map);
        if (response.getStatusCode() != HttpStatus.OK || response.getBody().getResultCode() > 0) {
            throw new RuntimeException(response.getBody().getMessage());
        }
        return response.getBody();
    }
    
    private String getBillingAddress() {
        return Json.createObjectBuilder()
                .add("street", "Hauptstraße")
                .add("no", "3")
                .add("zip", "10827")
                .add("city", "Berlin")
                .add("country", "DE")
                .build()
                .toString();
    }
    
    
    private MultiValueMap<String, String> getRequestMap() {
        MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
        map.add("merchantID", merchantID);
        map.add("storeID", storeID);
        map.add("userID", "user-127");
        map.add("userType", "PRIVATE");
        map.add("userRiskClass", "0");
        map.add("billingAddress", getBillingAddress());
        map.add("email", "max@mustermann.de");
        map.add("locale", "DE");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode":0,
        "salt":"d8bff4bbec235087"
    }
    

    Request

    Field Type Mandatory Comments
    merchantID N (16) yes This is the merchant ID assigned by CrefoPay.
    storeID AN (60) yes This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    userID AN (50) yes The unique user ID of the user assigned by the merchant. It should under no circumstances be shared between users, as payment instruments such as bank accounts and credit cards are saved and provided based on this ID.
    userType V yes This parameter defines business or private customers. This value cannot be changed after user creation.. This value cannot be changed after user creation. Possible Values:
    • PRIVATE
    • BUSINESS
    userRiskClass N (1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the userRiskClass or the basketItemRiskClass in the basket items has to be set.
    companyData J (Company) see comment Contact data of the user's company. This field is mandatory if the userType is BUSINESS and the userID was not registered before
    userData J (Person) see comment Contact data of the user. This field is mandatory if the userType is PRIVATE and the userID was not registered before
    creditLimit J (Amount) no If this field is provided then the value is saved as specific credit limit for this customer only. Any previously saved credit limit will be overwritten.
    billingRecipient AN (80) no Recipient for the billing address
    billingAddress J (Address) see comment The user's billing address. This field is mandatory if if user was not registered before with this userID
    shippingRecipient AN (80) no Recipient for the shipping address
    shippingAddress J (Address) no The user's shipping address
    locale V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages
    solvencyCheckInformation J (Solvency check information) no Result of a solvency check done by the merchant.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    message AN This parameter contains details about an error, otherwise it will left as empty.
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    SecureFields

    Prerequisites

    The SecureFields Solution requires the usage of jQuery in Version 1.6 and upwards. Keep in mind that the version of jQuery has to support AJAX requests, which is not given in the slim version of jQuery 3.x The JavaScript Library should be included in the page using the following snippet:

    <script src="https://libs.crefopay.de/3.0/secure-fields.js"></script>
    

    Process description.

    SecureFields FlowChart

    The SecureFields Solution can be used in with the Integration option "SecureFields". This includes the usual process of creating a transaction with the PaymentInstrument. After creating the transaction the SecureFields JavaScript Library needs to be initialized. This is usually done when the customer enters the payment selection page. As soon as the initialization of the library and the creation of a session for submitting credit card and bank data with the HostedFields is completed, you will receive a response in the registered callback function.

    Immediately after the customer selected the payment method the registerPayment function of the library should be called. It's not necessary to pass the selected payment method, because the library will recognize and transfer the selection based on the set data-attributes After selecting and registering the payment the API response contained in the callback function needs to be handled. As mentioned, the response of the API might not always be a successful message. In case of an error it will contain information about missing data or any other errors that may occur during payment method/instrument registration. In case of successful payment method selection the checkout process can be continued. Now the reserve call can be performed on the transaction, after the customer confirmed his purchase on the order confirmation page.

    Initialization

    To initialize the library, an instance of the SecureFieldsClient needs to be created. An example and a list of arguments for the initialization follow:

    var secureFieldsClientInstance = 
        new SecureFieldsClient(shopPublicKey, 
                               orderID, 
                               paymentRegisteredCallback, 
                               initializationCompleteCallback, 
                               configuration);
    
    Argument Description
    shopPublicKey Will be provided by CrefoPay
    orderID Reference to the transaction, set by the merchant in createTransaction. Alternatively the subscriptionID of a subscription, set in createSubscription, can be provided as well.
    paymentRegisteredCallback This function will be be called after registration of a payment method and receives the API response of CrefoPay as argument.
    initializationCompleteCallback This function will be called right after the secure fields initialization and receives the API response of CrefoPay as argument.
    configuration This argument may be used to provide placeholders for the secure fields or select a different endpoint for the requests. Details follow below (see Secure Fields Configuration)

    Data-attributes

    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="PREPAID">Cash in advance</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="BILL">Bill payment</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="DD">Direct debit</label><br>
      <label>Account holder: <input type="text" data-crefopay="paymentInstrument.bankAccountHolder" placeholder="John Doe"></label><br>
      <label>IBAN: <input type="text" data-crefopay="paymentInstrument.iban" placeholder="DE12 3456 7890 1112 1314"></label><br>
      <label>BIC: <input type="text" data-crefopay="paymentInstrument.bic" placeholder="SFRTDE20000"></label><br>
      <label><input type="radio" data-crefopay="paymentInstrument.id" value="Aqc9O5SSJuQTDHC9KXFE0Q">Registered bank account (IBAN: DE12 3456 7890 1112 1314)</label>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="CC">Creditcard</label><br>
      <span>Accountholder: </span>
      <div data-crefopay-placeholder="paymentInstrument.accountHolder"></div>
      <span>Number: </span>
      <div data-crefopay-placeholder="paymentInstrument.number"></div>
      <span>Validity: </span>
      <div data-crefopay-placeholder="paymentInstrument.validity"></div>
      <span>CVV: </span>
      <div data-crefopay-placeholder="paymentInstrument.cvv"></div>
      <label><input type="radio" data-crefopay="paymentInstrument.id" value="Aqc9O5SSJuQTDHC9KXFE0Q">Registered creditcard (Number: 12***********3456)</label>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="PAYPAL">PayPal</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="SU">Sofort</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="CC3D">Creditcard 3D-secure</label><br>
      <span>Accountholder: </span>
      <div data-crefopay-placeholder="paymentInstrument.accountHolder"></div>
      <span>Number: </span>
      <div data-crefopay-placeholder="paymentInstrument.number"></div>
      <span>Validity: </span>
      <div data-crefopay-placeholder="paymentInstrument.validity"></div>
      <span>CVV: </span>
      <div data-crefopay-placeholder="paymentInstrument.cvv"></div>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" value="COD">Cash on delivery</label><br>
    </div>
    

    For the secure fields library to find the selected payment method as well as the placeholders for the secure fields, several HTML-data-attributes have to be set. These should generally begin with data-crefopay. The following attributes can be set:

    data-crefopay

    Attribute value Description
    paymentMethod Marks PaymentMethods, should be used in combination with a radio button input or similar, as only one payment method can be selected.
    paymentInstrument.id Identifies an existing PaymentInstrument ( bank account / credit card ). Can be used to allow customers to re-use already registered payment instruments.
    paymentInstrument.bankAccountHolder Marks the field for the bank account holder.
    paymentInstrument.iban Marks the fields for the IBAN.
    paymentInstrument.bic Marks the field for the BIC.

    data-crefopay-placeholder

    Attribute value Description
    paymentInstrument.accountHolder Placeholder for the card-holder name.
    paymentInstrument.number Placeholder for the credit card number.
    paymentInstrument.validity Placeholder for the credit card validity date.
    paymentInstrument.cvv Placeholder for the CVV of the credit card.

    Registering the payment method

    After initialization of an instance of the SecureFieldsClient and successful session creation a payment method can be registered as follows:

    secureFieldsClientInstance.registerPayment();
    

    After executing this function the paymentRegisteredCallback function will be called automatically to process the CrefoPay API response. It's recommended to check the resultCode of the response first, to differentiate between failure and success:

    function paymentRegisteredCallback(response) {
        if (response.resultCode === 0) {
            // Successful registration, continue to next page using JavaScript
        } else {
            // Error during registration, check the response for more details and dynamically show a message for the customer
        }
    }
    

    Secure Fields Configuration

    The following values should be set in the configuration object for the SecureFileds:

    Value Information
    url API endpoint (If this value is not set, it will default to the CrefoPay production system.)
    placeholders Placeholders object. Contains values with which the placeholder fields will be pre-filled with. See below for object structure.

    URL

    Sandbox: https://sandbox.crefopay.de/secureFields/

    Live: https://api.crefopay.de/secureFields/

    Placeholders

    The placeholders object may contain the following values:

    Value Information
    accountHolder Pre-filled values for the cardholder name field
    number Pre-filled values for the credit card number field
    cvv Pre-filled values for the CVV field
    var configuration = {
        url: "https://sandbox.crefopay.de/secureFields/",
        placeholders: {
            accountHolder: "Your Name",
            number: "0123456789101112",
            cvv: "000"
        }
    }
    

    Error handling

    Errors or exceptions should be properly handled by the callback functions. The field resultCode is the main indicator used to recognize whether something went wrong. In general, if a resultCode higher than 0 is returned, it can be assumed that something went wrong. At errorcodes you may find general errors that may occur during payment method registration. In case of any error an error message will be provided to give more detailed information. Most errors will occur due to either validation or missing data-attributes. In those cases the user should be asked to check his inputs.

    Amazon Pay

    Process

    To be able to reserve a SecureFields transaction using Amazon Pay, the customer needs to log into the Amazon system and then select a delivery address and a payment method using the Amazon Pay widgets.

    SecureFields FlowChart

    To initialize the login button and the widgets, the data-crefopay attribute should be used:

    Attribute value Description
    paymentInstrument.amazon_login Loads an Amazon Pay login button, if the customer is not logged in yet.
    paymentInstrument.amazon_address Initializes the Amazon Pay delivery address widget. Can be set to read-only mode.
    paymentInstrument.amazon_wallet Initializes the Amazon Pay payment method selection widget.
    paymentInstrument.amazon_logout Loads an Amazon Pay logout button. Has to be styled by the merchant.
    // Initializing the library while providing Amazon Pay specific configuration
    new SecureFieldsClient(shopPublicKey, orderNo, function (data) {
    // selected payment response
    }, function (data) {
    // init session response
    }, {
        url: "https://sandbox.crefopay.de/secureFields/",
        amazonPay: {
            onChange: function (actionName) {
                console.log("Action was performed: " + actionName)
            },
            onError: function (error) {
                console.log("The following error occurred: " + error.getErrorCode() + ' - ' + error.getErrorMessage());
            },
            color: "DarkGray",
            size: "small"
        }
    });
    

    Generally these elements can all be initialized on the same page, or individually on pages in the checkout process. To do so the Secure Fields library has to be initialized on each page that should contain one or more of these fields.

    Only after a selection was made within the payment method widget can registerPayment be used to mark Amazon Pay as selected method.

    On order confirmation by the customer and reservation in the CrefoPay system it is required that the customer is redirected to the Amazon Pay system for further authentication.

    Customization

    By providing an amazonPay object when the Secure Fields library is initialized, the color and size of the login button can be customized. Additionally the address and payment selection widget can be loaded in a read-only mode. When loaded in read-only, the user can just see the current selection of addess/payment instrument, but not modify it.

    amazonPay: {
        color: ('Gold', 'LightGray', 'DarkGray'),
        size: ('small', 'medium', 'large', 'x-large'),
        addressWidgetReadonly: (true, false),  // optional
        paymentsWidgetReadonly: (true, false), // optional
        onError: function(errorMessage) {},
        onChange: function(eventName) {}
    }
    

    Events

    To handle error scenarios a function "onError" should be passed in the amazonPay object. For a complete list of possible error codes passed in "errorMessage" see Widget error handling.

    To progress the checkout process the "onChange" function should be used. It is triggered for the following events:

    eventName Description
    authenticated Triggered after the customer successfully authenticated using the Amazon Pay login button.
    address_selected Triggered after the customer successfully selected a delivery address in the address widget.
    payment_selected Triggered after the customer successfully selected a payment instrument in the wallet widget.
    logout Triggered after the customer successfully logged out using the logout button.

    Before registerPayment() of the Secure Fields library can be called the merchants needs to make sure that both an address and a payment instrument have been selected. This can be achieved by only enabling the "Continue" or "Confirm payment method" button after payment_selected was triggered for example.

    // Example of a response after successful payment method selection with registerPayment():
    {
        "resultCode": 0,
        "salt": "0659829e538f470a",
        "orderNo": "1560262063184",
        "paymentMethod": "AMAZON_PAY",
        "additionalInformation": {
            "amazonOrderReference": "S02-2383502-8123475"
        }
    }
    

    Receiving the billing and delivery address

    The delivery address the customer selects in the address widget might be different from the one provided in createTransaction. It is necessary to recalculate the shipping costs to this address. The recalculated transaction amount can then be provided in the reserve call.

    To allow for that, the billing and shipping address of the customer can be fetched right after registerPayment() was used to select Amazon Pay as payment method. This can be done by using the getTransactionStatus call.

    After registerPayment() was called for Amazon Pay, the addresses are stored temporarily on the CrefoPay transaction. Only on successful reservation are they saved permanently. If registerPayment() is used on a different payment method afterwards, the addresses revert back to the ones provided in createTransaction.

    Reservation

    After recalculating the shipping costs and performing a reserve call, Amazon Pay may perform a multi factor authentication, to confirm the identity of the customer. In any case the response to a reserve call using Amazon Pay will always contain a redirectUrl, to which the customer needs to be redirected to.

    If any issues occur during authentication or authorization, the customer will be redirected to the failureUrl configured for your shop. See Callback

    Data Structures

    Address

    The address object only contains the street address. It can be used in combination with a person or company to send a complete address.

    Field Type Mandatory Comments
    street AN (80) yes street
    no AN (32) no house number
    additional AN (80) no additional information
    zip AN (16) yes zip
    city AN (80) yes city
    state AN (80) no state, e.g. NRW
    country AN (2) yes 2 letter country code according ISO 3166

    Amount

    Field Type Mandatory Comments
    amount N (16) yes Amount in the smallest possible denomination (e.g. 12399 for 123.99 Eur).
    vatAmount N (16) no Amount in the smallest possible denomination (e.g. 12399 for 123.99 Eur).
    vatRate N (2.2) no floating point number with two decimals, e.g (19.00 or 32.75)

    Basket Item

    Field Type Mandatory Comments
    basketItemText AN (500) yes Description of the basket item
    basketItemID AN (20) no Unique ID for a single article of the basket
    basketItemCount N (5) yes Number of basket items of this kind
    basketItemAmount J (Amount) yes The subtotal of the basket item (basketItemCount x pricePerItem). This amount must always be a positive amount, even for the type COUPON
    basketItemRiskClass V no Risk class of this basket item. Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    Either the useRiskClass or the basketItemRiskClass in the basket items has to be set.
    basketItemType V no Possible values are:
    • DEFAULT
    • SHIPPINGCOSTS
    • COUPON

    Boniversum

    Field Type Mandatory Comments
    requestDate D (YYYY-MM-DD) yes Date of the original request
    identification V yes One of the following constants:
    • PERSON_HOUSEHOLD_NOT_IDENTIFIED
    • PERSON_HOUSEHOLD_IDENTIFIED
    • PERSON_IDENTIFIED
    • HOUSEHOLD_IDENTIFIED
    • PERSON_NOT_IDENTIFIED
    • BUILDING_IDENTIFIED
    • PERSON_DECEASED
    addressValidationStatus V yes One of the following constants:
    • SUCESSFULLY_VALIDATED
    • CORRECTED_AND_VALIDATED
    • NOT_CORRECTED_OR_VALIDATED
    trafficLightColor V yes One of the following constants:
    • NONE
    • RED
    • YELLOW
    • GREEN
    score N yes Score value

    CaptureStatusDetail

    Field Type Comments
    transactionAmount N The amount which has been confirmed by the user during the checkout process
    capturedAmount N The capturedAmount delivers the captured value for this specific (partial) order. If no reference number has been passed capturedAmount contains the sum of all captured amounts for all orders of the transaction
    paidAmount N The paidAmount delivers the paid value for this specific (partial) order. If no reference number has been passed paidAmount contains the sum of all paid amounts for all orders of the transaction.
    creditAmount N The creditAmount delivers the refunded value for this specific (partial) order. If no reference number has been passed creditAmount contains the sum of all refunds for all orders of the transaction
    reducedAmount N Describes how much of the openAmount was reduced via the refund call.
    guaranteedAmount N Describes how much was paid out to the merchant from payment guarantee.
    returnedGuaranteedAmount N Describes the amount of paid out payment guarantee that was refunded.
    feeAmount N Set in case of chargeback. Describes the fees issued by banks or service providers.
    openAmount N Describes the incoming amount which the CrefoPay system expects for this order.
    transactionCurrency AN Currency code according to ISO4217

    ClearingFile

    Field Type Mandatory Comments
    clearingID AN yes ID of the clearing file
    from D (YYYY-MM-DD) yes Date of the first entry
    to D (YYYY-MM-DD) yes Date of the last entry

    Company

    Field Type Mandatory Comments
    companyName AN (100) yes The name of the company
    email AN (254) yes Company e-mail address
    companyRegisterType V no The register type of the company. A list of valid values can be found in the section Company register type
    companyRegistrationID AN (30) no The registration number
    companyVatID AN (30) no The VAT id of the company
    companyTaxID AN (30) no The tax id of the company

    Crediconnect

    Field Type Mandatory Comments
    requestDate D (YYYY-MM-DD) yes Date of the original request
    trafficLightColor V yes One of the following constants:
    • NONE
    • RED
    • YELLOW
    • GREEN

    Creditreform

    Field Type Mandatory Comments
    requestDate D (YYYY-MM-DD) yes Date of the original request
    crefoProductName V yes One of the following constants:
    • IDENTIFICATION
    • RISK_CHECK
    • TRAFFIC_LIGHT_REPORT
    • COMPACT_REPORT
    blackWhiteResult B no Result of the black/white check:
    • true -> black
    • false -> white
    trafficLightResult V no Result of the traffic light check:
    • NONE
    • RED
    • YELLOW
    • GREEN
    compactScore N no Result of a compact report: score between 1 - 600.
    dateOfFoundation V no Result of a compact report: company foundation date
    legalForm V no Result of a compact report: company legal form
    lineOfBusiness V no Result of a compact report: company line of business
    companyEmail V no Result of a compact report: company email address

    ErrorDetails

    Field Type Mandatory Comments
    message V yes Key for failure reason (e.g. "field.invalid", "fieldName.invalid")
    field AN yes Name of the invalid field. This is exactly the name of the field in the interface. (e.g. userData.dateOfBirth). This value can be used to mark the invalid field in the user interface.
    number N yes Error number
    description AN yes Human readable message in english

    HostedPages text

    Field Type Mandatory Comments
    paymentMethodType V yes The identifier of the payment method. See PaymentMethods
    fee N (16) no The fee of a payment method in smallest possible denomination e.g. 199 for 1.99 Eur. The fee will be displayed next to the payment method on the Hosted Page, where the user selects his payment method.
    description AN (255) yes Additional text/explanation of a payment method. This text will be displayed next to the payment method on the Hosted Page, where the user selects his payment method
    locale V yes The locale determines the user's communication language e.g. for e-mails which will be send to the user or for payment pages. See Languages

    Payment options

    Field Type Mandatory Comments
    recurringCustomer B no True if the customer is known to the merchant. Depending on shop configuration this can influence security checks.
    recurringTransactionType V no Possible values:
    • FIRST
    • RECURRING
    This parameter can be used to control recurring transactions without using the CrefoPay subscription module. If an initial transaction is created with recurringTransactionType 'FIRST' it is possible to start a second transaction with type 'RECURRING'. In case of direct debit, the second transaction will use the same mandate as the initial transaction and in case of credit card it does not need a cvv to be processed. This option is only available if the initial transaction is processed with direct debit or credit card at the moment. If type RECURRING is used for direct debit transactions and no valid mandate can be found because no initial transaction was triggered, an error will be returned

    PaymentInstrumentRequest

    Field Type Comments Mandatory for credit card Mandatory for bank account
    paymentInstrumentType V Possible values:
    • BANKACCOUNT
    • CREDITCARD
    yes yes
    accountHolder AN (50) The account holder of the payment instrument yes yes
    number AN (16) Credit card number yes no
    validity D (YYYY-MM) Validity date of the credit card yes no
    issuer V Possible values:
    • VISA
    • MC
    yes no
    iban AN (34) Bank account number no yes
    bic AN (11) Bank identifier no yes

    PaymentInstrumentResponse

    Field Type Comments Provided for credit card Provided for bank account
    paymentInstrumentID AN (20) The unique ID of the payment instrument. This ID is created by CrefoPay. yes yes
    paymentInstrumentType V Possible values:
    • BANKACCOUNT
    • CREDITCARD
    yes yes
    accountHolder AN (50) The account holder of the payment instrument yes yes
    number AN (16) Masked credit card number yes no
    validity D (YYYY-MM) Validity date of the credit card yes no
    issuer V Credit card issuer. Possible values:
    • VISA
    • MC
    yes no
    iban AN (34) Masked bank account number no yes
    unmaskedIban AN (34) Unmasked bank account number. Only provided in response to createTransaction. no yes
    bic AN (11) Bank identifier no yes
    mandatoryReserveFields J(AN) Array of parameters that are required for the reserve call, such as CVV. Only provided in response to createTransaction. if required if required

    Person

    Field Type Mandatory Comments
    salutation V no Possible values:
    • F -> Female
    • M -> Male
    The field salutation is not mandatory, but it is required to perform solvency checks for the payment methods direct debit and bill payment. If no salutation is provided the available payment methods may be restricted.
    name AN (50) yes Person's name
    surname AN (50) yes Person's surname
    dateOfBirth D (YYYY-MM-DD) no Date of birth. The field 'dateOfBirth' is not mandatory, but it is required to perform solvency checks for the payment methods direct debit and bill payment. If no date of birth is provided the available payment methods may be restricted.
    email AN (254) yes Person's e-mail address
    phoneNumber N (30) no Person's phone number with leading zero
    faxNumber N (30) no Person's fax number with leading zero

    PaymentMethodInformation

    Field Type Mandatory Payment methods Comments
    paymentMethodType AN yes all Name payment method
    issuer V no CC, CC3D List of supported issuers. Possible values:
    • VISA
    • MC
    logos V no CC, CC3D, BILL_SECURE List of possible logos for presenting the payment method or payment instrument.
    mandatoryReserveFields Array of AN no Array of fields the reserve call is expecting for this payment method
    mandateReference AN no DD Information for displaying SEPA mandate reference
    creditorId AN no DD The creditor ID of the merchant
    merchantName AN no DD The merchant's name
    date AN no DD Date when the SEPA mandate was created

    ReserveInformationRequest

    Field Type Mandatory Comments
    salutation V no Possible values:
    • F -> Female
    • M -> Male
    The field 'salutation' is not mandatory, but it is required to perform solvency checks for the payment methods direct debit and bill payment. If no gender is provided the available payment methods may be restricted.
    dateOfBirth D (YYYY-MM-DD) no Date of birth. The field dateOfBirth is not mandatory, but it is required to perform solvency checks for the payment methods direct debit and BILL payment. If no date of birth is provided the available payment methods may be restricted.

    ReserveInformationResponse

    Field Type Comments
    bankname AN Bankname of the bankaccount the customer has to transfer the money to
    bic AN BIC of the bank account to which the user should remit the money. For bill payments with payment guarantee it is the BIC of their bank account.
    iban AN IBAN of the bank account to which the user should remit the money. For bill payments with payment guarantee it is the IBAN of their bank account.
    bankAccountHolder AN Name of the bank account holder to whom the user should remit the money.
    paymentReference AN The reference text to which the user needs to refer within his remittance so that CrefoPay can link the incoming payments with the outstanding amounts of a transaction.

    RiskData

    Field Type Comments
    solvencyData JA(SolvencyData) Information about different solvency checks

    SubscriptionPlan

    Field Type Mandatory Comments
    planReference AN (15) yes Plan reference/identification. Used in createSubscription.
    name AN (25) yes Subscription plan name
    description AN (100) yes Subscription plan description provided on plan creation
    amount J (Amount) yes Default subscription rate of the plan
    interval V yes Possible values are:
    • DAILY
    • WEEKLY
    • FORTNIGHTLY
    • FOUR_WEEKLY
    • MONTHLY
    • QUARTERLY
    • BIANNUALLY
    • YEARLY
    trialPeriod N (3) no Trial period set on plan creation. Possible values: 1 to 366
    basicPaymentsCount N (3) no Total amount of subscription payments to be done. Possible values: 1 to 999. Unlimited payments if not set.
    contactDetails AN (100) no Contact details set on plan creation
    hasSubscribers B yes Shows whether the plan has subscriptions associated with it

    SolvencyData

    Field Type Mandatory Comments
    solvencyInterface V yes Possible values are:
    • BONIMA
    • BUERGEL
    • CREDICONNECT
    • CREDITREFORM
    • CUBE
    • FLEXCONNECT
    • VERITA
    lastRequestDate D (yyyy-MM-dd'T'HH:mm:ss'Z') yes Date of last request to the third party provider
    checkDate D (yyyy-MM-dd'T'HH:mm:ss'Z') yes Date of the last solvency check request. As the third party provider is not called every time the solvency check is called, this date can differ from the lastRequestDate
    checkType V yes Possible values are:
    • FIRST_LEVEL_CHECK
    • SECOND_LEVEL_CHECK
    paymentMethod V no The identifier of the payment method. See PaymentMethods. Only set for checkType SECOND_LEVEL_CHECK
    actions JA(V) yes All actions that were triggered by the CrefoPay system because of this check. Possible values are:
    • DECLINED
    • HIGH
    • RESTRICTION
    • RESTRICTION_AND_MANUAL_CHECK
    • MANUAL_CHECK
    • NONE
    thirdPartyRequested B yes Indicates if the SolvencyCheck information has been refreshed at the third party provider or if it is historical data.
    orderID AN no Only in the response to getUser. The order which was the trigger for the solvency check
    score N no The score of this solvency check. Different number formats will be returned for different providers
    trafficLight V no Optional for solvencyInterface except BUERGEL, not set for BUERGEL. Possible values are:
    • GREEN
    • YELLOW
    • RED
    • NONE
    identification V no Only optional for solvencyInterface BONIMA and VERITA, not set for all other types. Possible values are:
    • PERSON_HOUSEHOLD_NOT_IDENTIFIED
    • PERSON_HOUSEHOLD_IDENTIFIED
    • PERSON_IDENTIFIED
    • HOUSEHOLD_IDENTIFIED
    • PERSON_NOT_IDENTIFIED
    • BUILDING_IDENTIFIED
    • PERSON_DECEASED
    addressValidation V no Only optional for solvencyInterface BONIMA and VERITA, not set for all other types. Possible values are:
    • SUCCESSFULLY_VALIDATED
    • CORRECTED_AND_VALIDATED
    • NOT_CORRECTED_OR_VALIDATED
    correctedAddress AN no Only optional for solvencyInterface BONIMA, CUBE, and VERITA, not set for all other types. Structure: <street> <houseNo>, <zip> <city>, <countryCode>
    addressOrigin AN no Only set optional solvencyInterface BUERGEL, not set for all other types
    addressOriginCode N no Only optional for solvencyInterface BUERGEL, not set for all other types
    decisionMessage AN no Only optional for solvencyInterface BUERGEL, not set for all other types
    statusCode AN no Only optional for solvencyInterface CREDICONNECT, not set for all other types
    productName V no Only optional for solvencyInterface CREDITREFORM, not set for all other types. Possible values are:
    • IDENTIFICATION
    • RISK_CHECK
    • TRAFFIC_LIGHT_REPORT
    • E_CREFO
    • BRIEF_REPORT
    • COMPACT_REPORT
    checkResult V no Only optional for solvencyInterface CREDITREFORM, not set for all other types. Possible values are:
    • BLACK
    • WHITE
    identificationNumber AN no Only optional for solvencyInterface CREDITREFORM, not set for all other types
    negativeIndicator B no Only optional for solvencyInterface CUBE, not set for all other types
    status V no Only optional for solvencyInterface CUBE, not set for all other types Possible values are:
    • ACTIVE
    • INSOLVENCY
    • STOP_DISTRIBUTION
    • UNKNOWN
    • UNDER_DISABILITY
    • DEAD
    specialAddress V no Only optional for solvencyInterface VERITA , not set for all other types. Possible values are:
    • S1
    • S2
    • S3
    • S4
    • S5
    • S6
    • S7
    • S8

    SolvencyCheckInformation

    Field Type Mandatory Comments
    boniversumResult J (Boniversum) no Data coming from solvency check provider Boniversum
    crediConnectResult J (Crediconnect) no Data coming from solvency check credi connect
    crefoResult J (Creditreform) no Data coming from solvency check provider Creditreform

    TransactionStatusDetail

    Field Type Only cash in advance or bill Only direct debit Comments
    transactionAmount N No No The amount which has been confirmed by the user during the checkout process
    transactionCurrency AN No No Currency code according to ISO4217
    paymentMethod AN No No The identifier of the payment method. See PaymentMethods
    bankname AN Yes No Name of the bank where the user should remit the money.
    bic AN Yes No BIC of the bank to which the user should remit the money.
    iban AN Yes No IBAN of the bank to which the user should remit the money.
    accountHolder AN Yes No Name of the bank account holder to whom the user should remit the money.
    paymentReference AN Yes No The reference text to which the user needs to refer within his remittance so that CrefoPay can link the incoming payments with the outstanding amounts of a transaction.
    sepaMandate AN No Yes Reference Number of the SEPA Mandate, only available if Payment method was DD
    debitAccountHolder AN Yes Yes Name of the accountholder of the bankaccount that will be debited
    debitIban AN No Yes IBAN of the bankaccount that will be debited
    debitBic AN No Yes BIC of the bankaccount that will be debited

    UpdatedData

    Field Type Mandatory Comments
    merchantReference J (OldNewValuePair) No Contains the updated merchantReference and the previous merchantReference if any value was overwritten. Only set if the merchantReference was updated.

    OldNewValuePair

    Field Type Mandatory Comments
    newValue Same type as updated field Yes Contains the updated field value.
    oldValue Same type as updated field No Contains the overwritten field value. Not set if no value was overwritten.

    Additional services

    SmartSignup

    The Smart Sign-Up JavaScript library is designed to help your business customers complete the checkout process far quicker, and make sure you always have accurate data about your business customers, which greatly enhances the chances of a successful B2B solvency check. The data returned by Smart Sign-Up comes from Creditreform databases for business information reports. The Creditreform data is collected decentralised by 130 German branch offices.

    User flow

    After your business customer types the first three letters of his business name, we call the 'Firmenwissen' Smart Sign-Up API to query the Creditreform database.The user will see a drop-down with possible selection options displayed based on his input. A new query is performed after the user changes his input and pauses for 300 milliseconds.

    SmartSignup suggestions

    After the user selects his company from the drop-down list, the address fields (street, number, ZIP, county and country) are automatically populated. We can also return the CrefoNummer, which you can store in your ERP or database for later use.

    SmartSignup result

    To understand the user flow better, have a look at the 'Firmenwissen' Smart Sign-Up website https://www.firmenwissen.de/index.html.

    SmartSignup Prerequisites

    Before you can use Smart Sign-Up you need to add this option to your contract with CrefoPay. If you did not register for this option yet just contact the support team at service@crefopay.de. You will need a public key to initialize the library. Smart Sign-Up requires the usage of jQuery in Version 1.6 and upwards. Keep in mind that the version of jQuery has to support AJAX requests, which is not given in the slim version of jQuery 3.x Furthermore the library depends on the autocomplete widget of jQuery UI. The JavaScript Library should be included in the page using the following snippet:

     <script src="https://libs.crefopay.de/3.0/smart-sign-up.js"></script>
    

    URL:

    Sandbox: https://sandbox.crefopay.de/autocomplete/

    Live: https://api.crefopay.de/autocomplete/

    SmartSignup Configuration

    let configuration = {
        "url": "https://sandbox.crefopay.de/autocomplete/",
        "itemCount": 10,
        "suggestion": {"zip": true, "city": true, "county": true, "country": true}
    };
    

    The following values can be set in the configuration object for the SmartSignup client:

    Field Type Mandatory Comments
    url AN no API endpoint (If this value is not set, it will default to the CrefoPay production system.)
    itemCount N yes Number of suggestions that are shown in the drop-down
    suggestion J no configuration of the content that is shown in the suggestion drop-down. As a default only the company name is shown in the droptown. To add additional information following parameter can be added to this Json object:
    • zip
    • city
    • county
    • country
    and set to 'true'. Example: {"city": true, "country": true }

    SmartSignup Initialization

    To initialize the library, an instance of the SecureFieldsClient needs to be created.

    function SmartSignUpClient(shopPublicToken, onInit, configuration)

    new SmartSignUpClient("6bebbcabf03b937c05d1db9f0af98b29363880ba903fab10c4f5d4d96d58193f", function (data) {
        $("#result-content").html('');
        if (data.resultCode === 0) {
            $("#result-content").append('<p>Successfully initialized</p>');
        }
        $("#result-content").append(JSON.stringify(data, null, 4));
    }, configuration);
    
    Field Type Mandatory Comments
    shopPublicToken AN yes The key you get from the support team after successfully registering with SmartSignup
    onInit JS function yes This function will be called right after the SmartSignup initialization and receives the API response of CrefoPay as argument.
    configuration JS object yes The configuration object for the SmartSignup client
    <div>
        <label for="companyName">Company Name</label>
        <input data-crefopay-placeholder="address.name" type="text" name="companyName"/>
    </div>
    <div>
        <label for="street">streetWithNumber</label>
        <input data-crefopay-placeholder="address.street" type="text" name="street"/>
    </div>
    <div>
        <label for="zip">Zip</label>
        <input data-crefopay-placeholder="address.zip" type="text" name="zip"/>
    </div>
    <div>
        <label for="city">City</label>
        <input data-crefopay-placeholder="address.city" type="text" name="city"/>
    </div>
    <div>
        <label for="country">Country</label>
        <input data-crefopay-placeholder="address.country" type="text" name="country"/>
    </div>
    <div>
        <label for="crefoNo">Crefo No</label>
        <input data-crefopay-placeholder="crefoNo" type="text" name="crefoNo"/>
    </div>
    

    The attribute data-crefopay-placeholder is used in all input input that should be used be autocompleted by SmartSignup. Following values can be used:

    Value Description
    address.name Company name. The input field with this tag is parsed by the SmartSignup client library to present suggestions. After at least 3 letters have been typed, the client library starts to show suggestions
    address.street Street name
    address.streetNo Street number
    address.streetWithNumber Street name with number
    address.zip ZIP code
    address.city City name
    address.state State of county
    address.country 2 letter country code according ISO 3166
    crefoNo The crefo number of the company

    SmartSignup Example

    This example shows a minimal HTML page that uses SmartSignup to autocomplete all address-fields and show the result of the initialization of the initialization of the client library.

    <!DOCTYPE html>
    <html>
    <head>
        <script src="https://code.jquery.com/jquery-3.3.1.min.js"
                integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=" crossorigin="anonymous"></script>
        <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
                integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU=" crossorigin="anonymous"></script>
        <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">
        <script src="https://libs.crefopay.de/3.0/smart-sign-up.js"></script>
    </head>
    
    <body onload="configureSmartSignup()" >
    
    <h1>Smart SignUp</h1>
    <div>
        <label for="companyName">Company Name</label>
        <input data-crefopay-placeholder="address.name" type="text" name="companyName"/>
    </div>
    <div>
        <label for="street">Street</label>
        <input data-crefopay-placeholder="address.street" type="text" name="street"/>
    </div>
    <div>
        <label for="streetNo">Street No</label>
        <input data-crefopay-placeholder="address.streetNo"  type="text" name="streetNo"/>
    </div>
    <div>
        <label for="zip">Zip</label>
        <input data-crefopay-placeholder="address.zip" type="text" name="zip"/>
    </div>
    <div>
        <label for="city">City</label>
        <input data-crefopay-placeholder="address.city" type="text" name="city"/>
    </div>
    <div>
        <label for="state">State</label>
        <input data-crefopay-placeholder="address.state" type="text" name="state"/>
    </div>
    <div>
        <label for="country">Country</label>
        <input data-crefopay-placeholder="address.country" type="text" name="country"/>
    </div>
    <div>
        <label for="crefoNo">Crefo No</label>
        <input data-crefopay-placeholder="crefoNo" type="hidden" name="crefoNo"/>
    </div>
    
    
    <div id="result-container">
        <h1>Result</h1>
        <div id="result-content" class="result form"></div>
    </div>
    
    
    <script>
        function configureSmartSignup() {
    
            let configuration = {
                "url": "https://sandbox.crefopay.de/autocomplete/",
                "itemCount": 20,
                "suggestion": {"city": true, "country": true, "zip": true, "county": true}
            };
    
            new SmartSignUpClient("abcdefghijkjmnopqrstuvwxyz", function (data) {
                $("#result-content").html('');
                if (data.resultCode === 0) {
                    $("#result-content").append('<p>Successfully initialized</p>');
                }
                $("#result-content").append(JSON.stringify(data, null, 4));
    
            }, configuration);
        }
    </script>
    </body>
    </html>
    

    Additional resources

    Company register type

    Value Description
    UNKNOWN Not specified
    HRA German trade register department A
    HRB German trade register department B
    PARTR German partnership register
    GENR German cooperative society register
    VERR German register of associations
    FN Austrian commercial register
    LUA Luxembourg trade registry A
    LUB Luxembourg trade registry B
    LUC Luxembourg trade registry C
    LUD Luxembourg trade registry D
    LUE Luxembourg trade registry E
    LUF Luxembourg trade registry F
    LUG Luxembourg trade registry G

    Currency codes

    Supported ISO 4217 currency codes

    Code Name
    EUR Euros
    USD United States Dollar
    GBP United Kingdom Pound
    CHF Switzerland Franc
    SEK Sweden Krona
    NOK Norway Krone
    CZK Czech Republic Koruna
    DKK Denmark Krone
    HRK Croatian kuna
    HUF Hungarian forint
    ISK Icelandic króna
    PLN Polish złoty
    RUB Russian ruble
    AUD Australian dollar
    BRL Brazilian real
    CAD Canadian dollar
    MXN Mexican peso
    ARS Argentine peso
    ILS Israeli new shekel
    INR Indian rupee
    JPY Japanese yen
    KRW South Korean won
    SGD Singapore dollar
    ZAR South African rand
    HKD Hong Kong dollar

    Errors

    Successful call

    Code Description
    0...999 See documentation of request methods for more information. These codes are reserved for different uses

    Technical or interface errors

    Code Description
    1000 An unknown error occurred, please contact the CrefoPay Support to find out details.
    1001 The calculated MAC is invalid.
    1002 The request is invalid. Please refer to the message for further explanation of the cause.

    Status codes for rejected requests

    Code Description
    2000 The payment method is not available. Please use another payment method.
    2001 The payment has been rejected. Please use another payment method.
    2002 Method call is not allowed in this state of transaction.
    2003 The transaction is expired.
    2004 The requested order number does not exists.
    2005 Method call already in process for this transaction.
    2006 No shop found with this shopID.
    2007 Shop is not activated.
    2008 Order ID already exist:
    2010 The credit card is expired.
    2011 The credit card number does not match the issuer.
    2012 The credit card is already stored for this user.
    2013 The bank account is already stored for this user.
    2014 The user already exist.
    2015 The user does not exist.
    2016 Refund amount must not be greater than capture amount.
    2017 Payment declined by fraud check. Please use another payment method.
    2018 Refund failed.
    2019 The provided captureID is unknown.
    2020 Reduce/Refund failed partially.
    2021 The MSA user already exists.
    2022 The Shop already exists.
    2023 Transaction is already finished.
    2024 Invalid token,
    2025 Merchant doesn't have the right to do this call.
    2026 The provided paymentInstrumentID is unknown.
    2027 No payment method available due to configuration.
    2028 This order was already captured.
    2029 This order was already captured with different Amount.
    2030 Capture is not allowed in this state of transaction.
    2031 "Payment Instrument is not a Bank Account." or "Payment Instrument is not a Credit Card."
    2032 Merchant notification failed.
    2033 The payment instrument is invalid.
    2034 The payment instrument does not support SEPA direct debit.
    2035 Bank account or routing number do not match.
    2036 Non PCI compliant merchant is not allowed to send CVV.
    2037 Capture rejected.
    2038 Multiple captures not allowed.
    2039 Issuer is not supported by the shop. Please try another one.
    2040 The issuer of the credit card could not be detected. Please use another card.
    2041 The credit card number is empty. Please enter a credit card number.
    2042 The validity month of the credit card is empty. Please enter a validity month.
    2043 The validity year of the credit card is empty. Please enter a validity year.
    2044 The name of the credit card holder is empty. Please enter an account holder.
    2045 Error in sending email.
    2046 Invalid card number.
    2047 No active dunning configuration for transaction.
    2048 No plan found with this planReference.
    2049 Transaction type not allowed.
    2050 Subscription ID already exists.

    Additional status codes for notification callbacks

    Code Description
    6001 parameter or format error
    6002 unknown
    6003 transaction or payment method not allowed
    6004 system error, no response, time-out
    6005 cancelled by user
    6006 authentication failed
    6007 expired, blocked, stolen, declined with no specific reason
    6008 no JavaScript in user's browser
    6009 overload, merchant busy, processing temporarily not possible
    6010 invalid amount
    6011 fraud
    6012 communication error
    6013 reservation outdated
    6014 configuration error
    6015 partial capture not allowed
    6016 third party gateway returned an error or declined transaction, details will be in the error description
    6017 no funds
    6018 partial refund failed
    6025 Invalid Amazon Pay payment method

    Languages

    CrefoPay support the following languages within the checkout process

    Code Name
    EN English
    DE German
    ES Spanish
    FR French
    IT Italian
    NL Dutch

    PaymentMethods

    Identifier Name Comments
    DD Direct debit
    CC Credit card
    CC3D Credit card 3D-Secure
    PREPAID Cash in advance
    PAYPAL PayPal
    SU Sofort
    BILL Bill payment Bill payment without payment Guarantee
    COD Cash on delivery
    DUMMY Dummy This value is used for transactions that do not need a payment, e. g. if a coupon is bigger than the actual amount