NAV Navbar
java php
  • Introduction
  • Getting started
  • Implementation Details
  • API
  • SecureFields
  • Express Checkout
  • 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 due to fraud. This can occur if they were in status FraudPending and then declined by the merchant or CrefoPay, or if the merchant reported the user as fraudulent in the MSA or using the reportFraudUser API.
    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/ERP system. 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

    Extended Risk Classes

    Instead of only providing the main three risk classes low(0), medium(1) and high(2), it is also possible to provide user risk classes with a decimal point from 0-2. This way merchants gain access to a more finely grained risk management of customers in the checkout process based on their past experiences with them.

    By default all risk and solvency checks are performed in the risk class range from 0.1 - 1.9. Specifically for limit, velocity, open debt rules and all solvency checks it is possible to define risk class thresholds, which define at which risk class a rule or check becomes active. This means that multiple rules or checks with different thresholds can be configured, whereas the rule/check with the highest threshold that is reached will be applied.

    The extended risk classes allow: * Application of different limit, velocity and open debt rules depending on the customer risk class * More control over the offered payment methods for each risk class * Usage of different solvency check products depending on the risk class * Different solvency check result interpretation depending on the risk class

    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 or false true
    D (format) DATE Date with a specified Format like YYYY-MM-DD 2020-02-22

    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:

    7aea4cc6313b2814053488079563375bf1544663

    API Throttling

    To prevent abuse of the API and ensure stability there are restrictions in place which limit the rate of requests per timeframe that can be performed to the CrefoPay system.

    Any given API endpoint has an assigned request pool which represents the amount of requests which can be made before the API rejects any further requests. This request pool refills with a set rate and therefore allows for a short burst of multiple requests at once, but limits the overall requests that can be made over longer periods of time.

    The size of the request pool and the refill rate may depend on the specific API endpoint and the system which is called. Request pools and the refill rate are independent for each individual API endpoint. For example, even if the limit for the getTransactionStatus API is reached, the createTransaction API would remain unaffected.

    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 status of transactions that were processed.

    The MNS can provide two types of notifications: status notifications and payment notifications. Details for each type of request are listed below.

    The status notification calls will be directed at the Status Notification Target URL that is configured for the shop, while payment notification calls will target the Payment Notification Target URL. 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. It is possible to configure different Status Notification Target URL/s for individual shops, in case the merchant uses multiple shops in the CrefoPay system. By contrast, the Payment Notification Target URL/s must always be identical in all shops. If this URL is modified in one shop, the configuration is automatically applied for all other shops of the merchant. This is done because bank accounts are configured on a merchant-level and multiple shops of a merchant may use the same bank account.

    Status Notification Request

    Status notifications are sent by the CrefoPay system whenever the status of a transaction or capture in the CrefoPay system changes, and they include general transaction or capture related information, such as the transaction/capture status, transaction balance, the amount ready to be captured, or payment and merchant references.

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

    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
    captureStatus V no Current status of the capture. Possible values:
    • PAYPENDING
    • PAID
    • CLEARED
    • PAYMENTFAILED
    • CHARGEBACK
    • INDUNNING
    • IN_COLLECTION
    transactionBalance N No The sum of all received payments minus the sum of all captured amounts plus all reductions. This value is negative when still waiting for payments, positive in case a transaction was overpaid, and zero when the debt is paid exactly or no capture was performed yet.
    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
    mac AN 40 yes Message Authentication Code see MAC calculation

    Payment Notification Request

    Payment notifications are specific to bank based payment methods and serve to inform the merchant if payments or refunds, which were registered in their bank account, were processed. The different types of payment notifications are specified below. These notifications contain detailed information about the bank statement related to a payment. They can be used if the merchant wants to keep track of all incoming/outgoing payments and whether they were successfully matched to CrefoPay transactions.

    The use of payment notifications is completely optional and has no impact on the checkout or payment process.

    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 no This is a unique identifier for a transaction which is created by the shop. This value is only set if the payment was associated to a CrefoPay transaction.
    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 payment was associated to a CrefoPay subscription.
    merchantReference AN 30 no Optional/additional reference for the transaction, as provided by the merchant.
    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. This value is only set if the payment was associated to a CrefoPay transaction.
    notificationType AN yes Describes in which context this notification was triggered. For a description of each option, see the table below. Possible values:
    • FAILED
    • IGNORED
    • MATCHED
    • REFUNDED
    • SENTTOACCREDIS
    • MATCHEDBYACCREDIS
    • ACCREDISFEE
    gvc N 3 yes Transaction code from the bank statement (Geschäftsvorfall-Code) which describes the type of payment.
    gvcText AN no Transaction description from the bank statement which describes the type of payment.
    accountNo AN yes IBAN from/to which the payment is sent.
    sortCode AN yes Bank identifier/SWIFT code
    owner AN yes Name of the account holder.
    usage AN no Customer reference as provided by the customer in case of incoming payments. Set by CrefoPay in case of refunds.
    merchantIBAN AN yes The bank account for which the payment notification was sent.
    statementNumber AN yes Sequential number of the associated bank statement.
    debitCreditMarker AN yes Indicates whether it is a debit or credit payment. Possible values: C (credit) and D (debit)
    valueDate AN yes Value date of the payment in milliseconds since 1970-01-01 (Unix timestamp in milliseconds)
    bookingDate N yes Booking date in milliseconds since 1970-01-01 (Unix timestamp in milliseconds)
    currency AN 3 yes 3 characters, Currency code according to ISO4217. Currency of the payment.
    amount N 16 yes Balance of the payment.
    timestamp N yes The time when the payment notification was triggered in milliseconds since 1970-01-01 (Unix timestamp in milliseconds)
    version AN yes Notification version
    mac AN 40 yes Message Authentication Code see MAC calculation

    Notification types

    Type Description
    FAILED The automatic payment matching failed and the payment could therefore not be associated to a CrefoPay transaction.
    IGNORED The payment was automatically or manually ignored and is therefore not associated to a CrefoPay transaction.
    MATCHED The payment was matched to a CrefoPay transaction.
    REFUNDED The payment was manually refunded before it was associated to a CrefoPay transaction.
    SENTTOACCREDIS The payment was associated to a CrefoPay transaction for which a dunning or collection process is active. The dunning provider was informed about the payment.
    MATCHEDBYACCREDIS The dunning provider processed a payment for which they were previously notified and matched the payment to a CrefoPay transaction.
    ACCREDISFEE Notification about dunning or collection fees raised by the dunning provider.

    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

    addressCheck

    This API can be used to validate or correct a customers address. Both the mandatory fields in the request and the response to this call may vary depending on the product that is configured to perform the address check.

    URL:

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

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

    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.
    address J (Address) yes The address to be checked. While th address object in the request itself is mandatory, the exact fields which it should contain differ depending on the service that will be used. Independent of which service is used the field "country" is always mandatory.
    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.
    checkReferenceId N Unique reference to the performed check
    responseData J Contains the raw response data of the address check provider in JSON format
    errorDetails JA (ErrorDetails) Structured information about any invalid request values
    salt AN A random number to guarantee the uniqueness of the message.

    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 (70) 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.
    startDate D(YYYY-MM-DD) no Defines a future date on which the subscription will become active and trigger the first payment. If a trial period is defined, then the trial period will begin on the start date. If no start date is provided the subscription will start immediately upon user confirmation.
    trialPeriod N (3) no Trial period in days. Range from 1 to 366. The trial period begins when the subscription becomes active, and the first payment will be triggered when the trial period ends.
    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
    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) / D (1.1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    • Decimal value between 0.0 and 2.0, eg. 1.3
    Defaults to 1.0 if neither userRiskClass nor basketItemRiskClass were set. If basketItemRiskClass is set, userRiskClass will default to that value instead.
    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) / D (1.1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    • Decimal value between 0.0 and 2.0, eg. 1.3
    Defaults to 1.0 if neither userRiskClass nor basketItemRiskClass were set. If basketItemRiskClass is set, userRiskClass will default to that value instead.
    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.

    getSubscriptionStatus

    This call returns the status of a subscription.

    URL:

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

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

    <?php
    function getSubscriptionStatus($subscriptionID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'subscriptionID' => $subscriptionID
        );
    
        // 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 subscription: {$subscriptionID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the status for subscription: {$subscriptionID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getSubscriptionStatus() {
        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", "S-100002");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode": 0,
        "salt": "520e21131977c584",
        "userType": "PRIVATE",
        "planReference": "subscrPlan1",
        "nextPayment": {
            "transactionAmount": {
                "amount": 500
            },
            "paymentDate": "2021-03-04"
        },
        "subscriptionStatus": "ACTIVE",
        "subscriptionID": "S-100002",
        "userID": "subscriptionUser1",
        "subscriptionCreationDate": "2021-02-04",
        "subscriptionAmount": {
            "amount": 500
        }
    }
    

    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.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    salt AN A random number to guarantee the uniqueness of the message.
    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
    subscriptionStatus V The status of the subscription referred by the subscription ID. Possible values:
    • NEW
    • USER_PENDING
    • START_PENDING
    • PAUSED
    • CANCELLED
    • ACTIVE
    • DONE
    merchantReference AN (30) Optional/additional reference for the subscription.
    userID AN (50) 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 This parameter defines business or private customers. This value cannot be changed after user creation. Type of the subscribed customer. Possible Values:
    • PRIVATE
    • BUSINESS
    subscriptionAmount J (Amount) Current amount to be charged regularly.
    subscriptionCreationDate D (YYYY-MM-DD) The date when the in subscription was created
    subscriptionStartDate D (YYYY-MM-DD) The date when the subscription is scheduled to start. Only returned if the subscription is scheduled to start in the future. Will not be returned in status NEW or USER_PENDING.
    firstPaymentDate D (YYYY-MM-DD) The date when the first subscription payment was performed, or will be performed. Will not be returned in status NEW or USER_PENDING.
    trialPeriod N (3) Trial period set for the subscription in days.
    planReference AN (15) Reference of the subscription plan used to create the subscription.
    nextPayment J (nextPayment) Returns the amount and the payment date of the next scheduled payment for the subscription.
    Subscription status Description
    NEW The subscription was created.
    USER_PENDING The subscription was created and the customer received an email with a link to complete the subscription.
    START_PENDING The subscription was confirmed by the user, and it is set to trigger the first payment at a future start date.
    ACTIVE The subscription was confirmed by the customer and it is now actively triggering payments in the scheduled interval.
    PAUSED The subscription was paused by the merchant. The regular payment cycle will continue once it was reactivated.
    CANCELLED The subscription was cancelled by the merchant. No further payments will be triggered.
    DONE All scheduled payments for the subscription were performed. Subscriptions with an endless payment cycle will never reach this status.

    getSubscriptionTransactions

    This call returns a list of all transactions related to a subscription and their status.

    URL:

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

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

    <?php
    function getSubscriptionTransactions($subscriptionID) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'subscriptionID' => $subscriptionID
        );
    
        // 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 transactions for subscription: {$subscriptionID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to get the transactions for subscription: {$subscriptionID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult getSubscriptionTransactions() {
        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", "1606830285083");
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode": 0,
        "salt": "b5f617e981c4571b",
        "transactions": [
            {
                "orderID": "S-103819",
                "transactionStatus": "DONE",
                "creationDate": "2021-01-26",
                "lastStatusChange": "2021-01-26",
                "transactionAmount": {
                    "amount": 500
                }
            },
            {
                "orderID": "S-103786",
                "transactionStatus": "DONE",
                "creationDate": "2020-12-29",
                "lastStatusChange": "2020-12-29",
                "transactionAmount": {
                    "amount": 500
                }
            },
            {
                "orderID": "1606830285083",
                "transactionStatus": "DONE",
                "creationDate": "2020-12-01",
                "lastStatusChange": "2020-12-01",
                "transactionAmount": {
                    "amount": 500
                }
            }
        ]
    }
    

    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.
    mac AN (40) yes Message Authentication Code. See: MAC calculation

    Response

    Field Type Comments
    resultCode N
    salt AN A random number to guarantee the uniqueness of the message.
    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
    transactionStatus V The status of the transaction referred by the order ID. Possible values: see Transaction process
    transactionAmount J (Amount) The total transaction amount
    creationDate D (YYYY-MM-DD) The date when the in transaction was created
    lastStatusChange D (YYYY-MM-DD) The date of the last status change of the transaction

    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 getTransactionStatus($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 getTransactionStatus() {
        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",
          "transactionBalance":0
       },
       "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. Only set after the transaction was reserved.
    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
    • V -> Various
    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.

    identificationCheck

    This API can be used to identify and validate customer data. Both the mandatory fields in the request and the response to this call may vary depending on the product that is configured to perform the identification check.

    URL:

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

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

    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.
    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
    userData J (Person) see comment Data of a PRIVATE customer. This field is mandatory if the userType is PRIVATE.
    companyData J (Company) see comment Data of a BUSINESS customer. This field is mandatory if the userType is BUSINESS.
    address J (Address) yes The address to be checked. While th address object in the request itself is mandatory, the exact fields which it should contain differ depending on the service that will be used. Independent of which service is used the field "country" is always mandatory.
    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.
    checkReferenceId N Unique reference to the performed check
    responseData J Contains the raw response data of the address check provider in JSON format
    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) / D (1.1) no Possible values are:
    • 0 -> trusted user
    • 1 -> default risk user
    • 2 -> high risk user
    • Decimal value between 0.0 and 2.0, eg. 1.3
    Defaults to 1.0 if the parameter was not provided and also no basketItemRiskClass is 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
    Defaults to 1.0 if neither userRiskClass nor basketItemRiskClass were set. If basketItemRiskClass is set, userRiskClass will default to that value instead.
    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.

    reportFraudUser

    The reportFraudUser call reports a customer as fraudulent. This will set their status to "FRAUD" and prevent them and all users that can be associated to them to complete any further purchases. Optionally you may chose to close all open transactions of this customer. If this is done, then all open or pending transactions of this customer will be closed, and all dunning and collection processes will be stopped. All transactions in status CIAPENDING, MERCHANTPENDING or INPROGRESS are considered open transactions.

    For transactions which have an open dunning or collection file at Accredis, the closure of the transaction and the dunning/collection file will be pending and may take up to 2 business days.

    URL:

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

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

    <?php
    function reportFraudUser($userID, $closeTransactions) {
        global $requestUrl, $merchantID, $storeID;
    
        // Enter all mandatory parameters here
        $param = array(
            'merchantID' => $merchantID,
            'storeID' => $storeID,
            'userID' => $userID,
            'closeTransactions' => $closeTransactions
        );
    
        // 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 reported the user: {$userID}.\n\r";
            return responseBody;
        } else {
            echo "We failed to report the user: {$userID}\n\rCrefoPay Errormessage: {$responseBody->message}\n\r";
            return false;
        }
    }
    ?>
    
    public CrefoPayResult reportFraudUser() {
        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", "exampleUser111");
        map.add("closeTransactions", true);
        map.add("mac", macCalculator.calculateAndGetMAC(map, merchantPassword));
        return map;
    }
    
    Response:
    {
        "resultCode": 0,
        "salt": "0b466141b307ec76",
        "closedTransactions": [
            {
                "orderId": "1612465866966",
                "closureStatus": "SUCCESS",
                "previousTransactionStatus": "INPROGRESS",
                "newTransactionStatus": "FRAUDCANCELLED",
                "creationDate": "2021-02-04",
                "transactionAmount": {
                    "amount": 0
                }
            },
            {
                "orderId": "1612465852295",
                "closureStatus": "SUCCESS",
                "previousTransactionStatus": "CIAPENDING",
                "newTransactionStatus": "FRAUDCANCELLED",
                "creationDate": "2021-02-04",
                "transactionAmount": {
                    "amount": 500
                }
            },
            {
                "orderId": "1612465761342",
                "closureStatus": "SUCCESS",
                "previousTransactionStatus": "MERCHANTPENDING",
                "newTransactionStatus": "FRAUDCANCELLED",
                "creationDate": "2021-02-04",
                "transactionAmount": {
                    "amount": 500
                }
            }
        ]
    }
    

    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.
    closeTransactions B no Set to 'true' if all open transactions of the user should be closed. Default value: false
    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.
    closedTransactions J (closedTransactions) Contains basic information about all closed transactions related to the customer. Only provided if transactions were closed

    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.

    If a reserve call failed due to the resultCode not being 0 or 1, then it is required to call getTransactionPaymentInstruments if another purchase attempt is to be made using the same transaction. This returns an updated list of the available payment methods and payment instruments of the transaction.

    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. The due date cannot be smaller or equal to the invoice date.
    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, cancel an active subscription or request the customer to change their payment method.

    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
    • UPDATE_PAYMENT_EMAIL
    • UPDATE_PAYMENT_LINK
    • UPDATE_PAYMENT_SECURE_FIELDS
    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
    redirectUrl AN Only returned for action UPDATE_PAYMENT_LINK.
    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.

    Changing the payment method

    To change the payment method of an active subscription it is required that the customer selects and confirms their new payment method. To this end three different actions can be triggered, which allow the customer to do so in different ways. With all three methods a new 0-amount transaction is automatically created in the CrefoPay system which serves to register and authorize the new payment method or payment instrument.

    UPDATE_PAYMENT_EMAIL

    This action will trigger an email to the customer associated with the subscription. In this email the customer will receive a link that can be used to change the payment method of the subscription. No further action is required by the merchant.

    This action will return a link to a payment page directly in the response to the updateSubscription call. This link is identical to the link provided in the email triggered by the action UPDATE_PAYMENT_EMAIL. It should be provided to the customer to select and confirm their new payment method. This could be done by either delivering the link through a messaging service or by loading the link within an iFrame inside the shop.

    
    Example response for action UPDATE_PAYMENT_SECUREFIELDS:
    {
        "resultCode": 0,
        "salt": "196cfb042e979ba9",
        "orderID": "S-100002",
        "userData": {
            "salutation": "M",
            "name": "Max",
            "surname": "Mustermann",
            "email": "mustermann@crefopay.de"
        },
        "billingAddress": {
            "street": "Schloßstr.",
            "no": "20",
            "zip": "12163",
            "city": "Berlin",
            "country": "DE"
        },
        "allowedPaymentMethods": [
            "PAYPAL",
            "CC3D",
            "DD"
        ],
        "allowedPaymentInstruments": [],
        "additionalInformation": [
            {
                "paymentMethodType": "PAYPAL"
            },
            {
                "paymentMethodType": "CC3D",
                "issuer": [
                    "VISA",
                    "MC"
                ],
                "logos": [
                    "VISA",
                    "MC"
                ]
            },
            {
                "paymentMethodType": "DD",
                "sepaPaymentType": "RCUR",
                "mandateReference": "10",
                "creditorId": "DE98ZZZ09999999999",
                "merchantName": "TestMerchant",
                "date": "May 17, 2021"
            }
        ],
        "billingRecipient": "Max Mustermann"
    }
    

    UPDATE_PAYMENT_SECUREFIELDS

    This action will cause the updateSubscription response to return transaction details similar to the createTransaction API, including an orderID, allowed payment methods and allowed payment instruments. The returned orderID should be used to initialize the SecureFields library in a shop frontend. After the customer selected their preferred payment method or payment instrument using the SecureFields, the transaction needs to be reserved using the reserve API, similar to a regular CrefoPay transaction.

    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
    Defaults to 1.0 if neither userRiskClass nor basketItemRiskClass were set. If basketItemRiskClass is set, userRiskClass will default to that value instead.
    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 must be included in the page using the following snippet:

    //For use on the production environment
    <script src="https://api.crefopay.de/libs/3.0/secure-fields.js"></script>
    
    //For use on the sandbox environment
    <script src="https://sandbox.crefopay.de/libs/3.0/secure-fields.js"></script>
    
    //For use on the production environment (deprecated)
    <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 actively 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 a 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" name="paymentMethodSelect" value="PREPAID">Cash in advance</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" value="BILL">Bill payment</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" 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" name="savedPaymentInstrumentSelect" value="Aqc9O5SSJuQTDHC9KXFE0Q">Registered bank account (IBAN: DE12 3456 7890 1112 1314)</label>
      <label><input type="radio" data-crefopay="paymentInstrument.id" name="savedPaymentInstrumentSelect" value="y6hijnZJt38FeNPUFM2E6g">Registered bank account (IBAN: DE65 4321 4131 2111 5432)</label>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" 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" name="savedPaymentInstrumentSelect" value="lt-vfbxBlSffx0e6QQ_hpg">Registered creditcard (Number: 12***********3456)</label>
      <label><input type="radio" data-crefopay="paymentInstrument.id" name="savedPaymentInstrumentSelect" value="t_QOm8SvkGWaChoYeI0rrg">Registered creditcard (Number: 65***********4321)</label>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" value="PAYPAL">PayPal</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" value="SU">Sofort</label><br>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" 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" name="paymentMethodSelect" value="COD">Cash on delivery</label><br>
    </div>
    

    For the SecureFields 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();
    

    Upon calling the registerPayment function the SecureFields library will scan the page for any elements with the data-crefopay attribute set to "paymentMethod". If more than one element can be found, it will only recognize the "checked" element. Therefore it should be ensured that only one element with the attribute data-crefopay="paymentMethod" can be selected at any time. If only one element can be found, it does not need to be "checked"/selected.

    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 or perform other actions
        }
    }
    

    Display and selection of already registered credit cards and bank accounts

    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" 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" name="savedPaymentInstrumentSelect" value="Aqc9O5SSJuQTDHC9KXFE0Q">Registered bank account (IBAN: DE12 3456 7890 1112 1314)</label>
      <label><input type="radio" data-crefopay="paymentInstrument.id" name="savedPaymentInstrumentSelect" value="y6hijnZJt38FeNPUFM2E6g">Registered bank account (IBAN: DE65 4321 4131 2111 5432)</label>
    </div>
    <div>
      <label><input type="radio" data-crefopay="paymentMethod" name="paymentMethodSelect" 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" name="savedPaymentInstrumentSelect" value="lt-vfbxBlSffx0e6QQ_hpg">Registered creditcard (Number: 12***********3456)</label>
      <label><input type="radio" data-crefopay="paymentInstrument.id" name="savedPaymentInstrumentSelect" value="t_QOm8SvkGWaChoYeI0rrg">Registered creditcard (Number: 65***********4321)</label>
    </div>
    

    For a better checkout experience it is recommended to display already registered payment instruments such as credit cards and bank accounts, so that customers do not have to repeatedly enter their data. To submit existing payment instruments the attribute data-crefopay="paymentInstrumentId" should be set, with the value being the paymentInstrumentId of the registered card or bank account.

    Upon calling the registerPayment function the SecureFields library will scan the page for any elements with the data-crefopay attribute set to "paymentMethod" and "paymentInstrument.id". Specifically for "paymentMethod" and "paymentInstrument.id" it will only recognize those elements that are "checked", therefore it is recommended to keep all payment methods and payment instruments in separate radio-button groups. This will ensure that only one payment method and one payment instrument can be selected at any given time. The separation can be achieved by giving the form elements different name attributes.

    Inclusion of multiple CVV fields

    For any transaction for which the the payment method credit card "CC" is offered, either by registering a new payment instrument or using an existing payment instrument, it is required to also provide a CVV. The CVV field is a hosted field which is designated by the attribute data-crefopay-placeholder="paymentInstrument.cvv". Compared to the other fields which use the attribute data-crefopay-placeholder, the CVV field can be included multiple times on one page, but only one of them should be visible at any give time. This allows the shop to display the field right next to either the input fields for a new credit card, or alternatively to already registered cards.

    It is sufficient if a parent element of the element containing the CVV field is hidden, to make it unrecognizable for the SecureFields library.

    Secure Fields Configuration

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

    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.

    If a reserve call failed due to the resultCode not being 0 or 1, then it is required to call getTransactionPaymentInstruments if another purchase attempt is to be made using the same transaction. This returns an updated list of the available payment methods and payment instruments of the transaction.

    Billie

    To be able to reserve a SecureFields transaction using Billie as payment method, the customer needs to go through an identification process using the Billie widget. Generally this payment method is treated as a secure payment method by CrefoPay, as Billie perform their own risk checks for each transaction/customer. As such CrefoPay risk checks will not influence whether Billie can be offered as a payment method or not.

    Billie Widget

    The Billie widget will be automatically initialized in the customer browser, when registerPayment() of the SecureFields library is called and Billie was selected as payment method. This requires that the latest version of the SecureFields library is used within the shop. Billie specifically uses the payment method BILL_SECURE, which can be offered using radio buttons, just like any other payment method.

    <input type="radio" data-crefopay="paymentMethod" value="BILL_SECURE">Billie</label>
    

    Billie success case handling

    If the registerPayment() function returned resultCode=0 then the identification process was successful and the checkout can continue.

    {
        "resultCode": 0,
        "salt": "8ad7ea63c2fecd63",
        "orderNo": "1603709147671",
        "paymentMethod": "BILL_SECURE"
    }
    

    During the identification process in the Billie-widget, the customer may provide a company/billing address that can differ from the billing address that was originally provided in the shop environment. To make sure that the address in the shop is correct, the billing address with which Billie successfully identified the merchant should be used within the shop.

    Billie Widget

    It is recommended to call the getTransactionStatus API after every registerPayment() execution using BILL_SECURE that returned resultCode=0, and to compare the returned billing address to the address stored in the shop. If these differ, then the shop should update the billing address of the order before redirecting the customer to the order confirmation page.

    After successful identification with the Billie widget, the transaction can be [reserved]{#reserve} like any other regular SecureFields transaction.

    Billie failure case handling

    If the response to registerPayment() is anything else but resultCode=0, then the checkout process should not continue, and the user should remain on the payment selection page.

    Specifically for Billie, the following resultCodes can be returned:

    {
        "resultCode": 3005,
        "message": "Financing limit of debtor currently exceeded."
    }
    
    resultCode Message Hard decline
    3001 Debtor address or name mismatch. no
    3002 Debtor could not be identified with the information given. no
    3003 Risk decline. yes
    3004 Not enough data available to make a decision. no
    3005 Financing limit of debtor currently exceeded. yes
    3006 User rejected suggested company. no
    3099 Unknown decline: (variable reason) no

    The resultCodes 3003 and 3005 represent so called "hard declines". If either of those resultCodes is returned, then Bille should not be offered as an available payment method, as the customer was identified and not accepted by Billie. Optimally this would result in the payment method BILL_SECURE being hidden for this specific order.

    Express Checkout

    Amazon Pay

    Payment Process

    Amazon Pay should be integrated into shops as an express payment method. This means compared to conventional payment methods, it is not offered on the payment method selection page, but on different pages before that. Compared to other payment methods offered by CrefoPay, using Amazon Pay does not require the merchant to create a CrefoPay transaction upfront.

    Amazon Pay Process

    Given that the payment method can be offered on the product pages or the basket page in the shop, the customer may not yet have provided any customer data with which a CrefoPay transaction can be created. To create and process a CrefoPay transaction with 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 button.

    After successful authentication with Amazon Pay, the customer would then be redirected back to the shop, where the shop has the chance to request all relevant customer data from CrefoPay and display the order confirmation page of the shop. On order confirmation by the customer, the transaction should be reserved using the CrefoPay reserve API, which finalizes the payment.

    Prerequisites

    //CrefoPay library
    //For use on the production environment
    <script src="https://api.crefopay.de/libs/3.0/amazon-client.js"></script>
    
    //For use on the sandbox environment
    <script src="https://sandbox.crefopay.de/libs/3.0/amazon-client.js"></script>
    
    //Amazon Pay library
    //For use on any environment (EU)
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    

    To render the Amazon Pay button for a CrefoPay transaction, the CrefoPay amazon client JavaScript library and the Amazon checkout JavaScript library need to be included in the header of any given page.

    Rendering the Amazon Pay button

    <script type="text/javascript" charset="utf-8">
      amazonClient = new AmazonClient(
      shopPublicKey,
      configuration,
      initializationCompleteCallback,
      onButtonClickCallback
      );
    amazonClient.createButton();
    </script>
    

    To render the button, an instance of the AmazonClient needs to be created first. This is done by providing the public key of your shop, provided by CrefoPay, a configuration object and two callback functions. Afterwards the createButton function of the AmazonClient instance can be used, to insert the button on the page.

    <div data-crefopay="amazonPayButton"></div>
    

    This function will search for a placeholder field on the entire page, and render the button inside it. The placeholder should be a simple DIV-element with the attribute data-crefopay=”amazonPayButton”.

    Argument Description
    shopPublicKey Will be provided by CrefoPay
    configuration This argument should be used to provide transaction information required for processing. Details follow below (see Configuration options)
    initializationCompleteCallback This function will be called right after the client initialization and receives the API response of CrefoPay as argument.
    onButtonClickCallback This function will be called right after the customer clicked the Amazon Pay button and receives the name of the placeholder element as argument.

    Rendering multiple buttons on one page

    In certain cases it may be required to render multiple Amazon Pay buttons on a single page in a shop. This can be relevant in case the button should be displayed next to multiple products which are displayed on the same page.

    <script type="text/javascript" charset="utf-8">
      //Rendering 3 buttons simultaneous
      amazonClient.createButton("button1","button2","button3");
    </script>
    
    //Placeholder elements for the 3 buttons
    <div data-crefopay="button1"></div>
    <div data-crefopay="button2"></div>
    <div data-crefopay="button3"></div>
    

    To render multiple buttons at once, the createButton function can be while providing the names of the placeholder elements. By doing so the amazon-client will scan the page for elements for which the data-crefopay attribute are set to the provided names, and render the buttons inside them.

    <script type="text/javascript" charset="utf-8">
      function onButtonClickCallback(button) {
        switch(button){
          case "button1":
            //action for button 1
            break;
          case "button2":
            //action for button 2
            break;
          case "button3":
            //action for button 3
            break;
        }
      }
    </script>
    

    When one of the buttons was clicked, the name of the placeholder in which the button was rendered will be provided to the onButtonClickCallback function as an argument. With this it is possible to perform different actions, depending on which of the buttons was clicked.

    Configuration options

    The configuration object maybe contain the following fields:

    Value Information
    url Base URL of the CrefoPay system for which the transaction should be created. Set to Sandbox if not provided. Possible values:
    • Sandbox: https://sandbox.crefopay.de/secureFields/
    • Production: https://api.crefopay.de/secureFields/
    buttonColor Sets the color of the Amazon Pay button. Set to "Gold" per if not provided. Possible values:
    • Gold
    • LightGray
    • DarkGray
    placement Informs Amazon Pay about the location in which the button is displayed. Set to "Cart" if not provided. Possible values:
    • Home
    • Product
    • Cart
    • Checkout
    • Other
    checkoutLangage Sets the preferred language displayed on the Amazon Pay page. Set to English if not provided. Possible values:
    • en_GB
    • de_DE
    • fr_FR
    • it_IT
    • es_ES
    sandbox Decides if test transactions or real transactions are created in the Amazon Pay system. For transactions performed on any CrefoPay test/staging sytem, this should be set to "true". Only set this to "false" when you use the CrefoPay production system to perform real payments. Set to "false" if not provided. Possible values:
    • true
    • false
    autoCapture Indicates whether the CrefoPay system should automatically capture all funds immediately after successful authorization with Amazon Pay.
    deliverySpecifications Specifies which addresses the customer is allowed to select at Amazon Pay. Details follow below (see Delivery address restrictions)
    orderId Unique reference to the CrefoPay transaction that will be created if the user clicks on the button and authorizes with Amazon Pay. CrefoPay will generate a rando orderID if none was provided. A maximum of 30 characters are allowed. Not mandatory.
    userId Unique reference to the customer in the CrefoPay system. Providing this field is useful to improve risk detection by the CrefoPay risk engine. CrefoPay will generate a random userID if none was provided. A maximum of 50 characters are allowed. Not mandatory.

    Initialization callback

    The provided callback function initializationCompleteCallback will be called once the createButton function was executed, and the result will be provided to it. When resultCode=0 is returned then one or multiple buttons were successfully rendered. For any other resultCode the rendering failed, and a message and further error details are provided.

    Relevant fields for result processing:

    Field Description
    resultCode
    • resultCode = 0 -> The Amazon Pay button was successfully rendered.
    • resultCode > 0 -> see errorcodes
    salt A random number to guarantee the uniqueness of the message.
    message If an error occurs, this field contains details about that error. Not set if resultCode = 0.
    errorDetails Structured information about any invalid request values.

    Button click callback

    The provided callback function onButtonClickCallback will be called immediately after the customer clicked on a rendered Amazon Pay button. This function can be used to prepare the basket of the customer in the shop by adding new basket items, or to store other relevant data in the customer session. After execution of the function the customer will be redirected to Amazon Pay to authenticate.

    Delivery address specifications

    //Example: restrict packstation addresses
    {
      "specialRestrictions": ["RestrictPackstations"]
    }
    
    //Example: only allow delivery to Austria and Germany
    {
      "addressRestrictions": {
        "type": "Allowed",
        "restrictions": {
          "AT":{},
          "DE":{}
          }
        }
    }
    
    //Example: specifically disallow delivery to France
    {
      "addressRestrictions": {
        "type": "NotAllowed",
        "restrictions": {
          "FR":{}
          }
        }
    }
    
    //Example: only allow delivery to a certain zip code in Germany and restrict packstation addresses
    {
      "specialRestrictions": ["RestrictPackstations"],
      "addressRestrictions": {
        "type": "Allowed",
        "restrictions": {
          "DE":{
            "zipCodes": ["10317"]
            }
          }
        }
    }
    

    As the customer selects their delivery address on the Amazon Pay page, it needs to be ensured that they are not able to select addresses in locations/countries which are not supported by the shop. For this the deliverySpecifications field in the configuration should be set accordingly. The field can be used to restrict delivery addresses to specific, zones, countries, zip codes and even disallow PO boxes and packstation addresses.

    The see official Amazon Pay documentation on how the deliverySpecifications can be set.

    Fetching customer data & order confirmation page

    After the customer successfully logged in with Amazon Pay and authenticated the order, they are redirected to the “checkout review URL”. Using the GET-parameters provided in this redirection, the shop should now fetch the relevant user data, such as customer name and address, so that the order in the shop can be updated accordingly.

    The following GET-parameters can be provided:

    Parameter Information
    merchantID This is the merchant ID assigned by CrefoPay.
    storeID This is the store ID of a merchant assigned by CrefoPay as a merchant can have more than one store.
    orderID This is a unique identifier for a CrefoPay transaction. Will be set to the value provided in the configuration when initializing the Amazon Pay button. Otherwise it is automatically generated.
    paymentMethod The payment method selected by the customer. This will always be AMAZON_PAY in case of a redirection from Amazon Pay to the shop.
    sessionID Amazon Pay session ID. This ID can be used to render buttons which allow the customer to change their address on the order confirmation page.

    Afterwards the user should be redirected to the order confirmation page of the shop, if they were not redirected there immediately. The order confirmation page should contain a summary of the order, with all relevant user and transaction data being displayed, the same as for any other payment method in the shop.

    Changing the address

    Customers should have the option to change the address on the order confirmation page. As the customer initially selected these addresses on the Amazon Pay page, they must be redirected back to the page to change it again. This can be done by binding click events to HTML elements on the order confirmation page using the Amazon Pay library.

    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    Then the action can be bound to elements on the page:
    <script type="text/javascript" charset="utf-8">
      amazon.Pay.bindChangeAction('#changeButton1', {
        amazonCheckoutSessionId: 'xxxx',
        changeAction: 'changeAddress'
      });
    </script>
    

    First, same as for displaying the Amazon Pay button, the Amazon Pay JavaScript library needs to be included in the header of the order confirmation page.

    Upon triggering the event, the customer will then be redirected back to the Amazon Pay page, where they will be able to modify their address.

    After the customer selected their new address they will be redirected back to the “checkout review URL”, same as they were initially. Upon re-entry, the customer data should be fetched again from CrefoPay to update the order in the shop.

    Finalizing the transaction

    When the customer confirms their purchase on the order confirmation page of the shop, the CrefoPay reserve API should be called, same as for any other payment method using CrefoPay. On success, the response will contain resultCode=1, which signifies that the customer should be redirected to a specific url, which is provided in the field redirectUrl. This redirection is required by Amazon to perform last risk checks to authorize the payment. Depending on the outcome, the user will then be redirected back to the configured success URL of the shop, or on failure to the configured failure URL of the shop. This is identical behavior to all other payment methods that require a redirection on the CrefoPay platform.

    Transaction management

    After successful reservation of the Amazon Pay transaction, the transaction may be in one of two states. If Amazon Pay notified that the authorization for the payment is still pending, then the transaction will be in status CIAPending. At this stage, the transaction cannot be captured yet, but it may be cancelled. When Amazon Pay confirmed that the authorization is successful, the CrefoPay transaction will be in status MerchantPending. This signifies that the funds are ready to be captured.

    Generally an Amazon Pay transaction in the CrefoPay system can be managed identically to any other payment method in the system, in that captures and refunds can be created, and that they can be cancelled.

    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
    name AN (153) no Full name (PRIVATE user) or company name (BUSINESS user) of the customer. Can be set using the fields billingRecipient and shippingRecipient in createTransaction or createSubscription. Only returned in getTransactionStatus.

    Amount

    Field Type Mandatory Comments
    amount N (16) yes Amount in the smallest possible denomination (e.g. 12399 for 123.99 Eur). (including taxes)
    netAmount N (16) no Amount in the smallest possible denomination (e.g. 12399 for 123.99 Eur). (excluding taxes)

    Amount (deprecated, do not use)

    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

    ClosedTransactions

    Field Type Mandatory Comments
    orderID AN yes Unique identifier of the transaction
    closureStatus V yes Shows if the closure of the transaction was successful, failed or is still pending. Possible values:
    • SUCCESS
    • PENDING
    • FAILURE
    previousTransactionStatus V yes The status of the transaction before closure was triggered. Possible values: see Transaction process
    newTransactionStatus V yes The status of the transaction after the closure was triggered. Possible values: see Transaction process
    transactionAmount J (Amount) yes The total amount of the transaction
    creationDate D (YYYY-MM-DD) yes Date on which the transaction was created

    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

    nextPayment

    Field Type Mandatory Comments
    transactionAmount J (Amount) yes Total amount of the next payment that will be tiggered for the subscription.
    paymentDate D (YYYY-MM-DD) yes Date on which the next payment for the subscription will be triggered.

    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 (70) 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 (70) 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
    • V -> Various
    The field 'salutation' is not mandatory, but it is required to perform most 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 most 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
    • V -> Various
    The field 'salutation' is not mandatory, but it is required to perform most 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 most 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.
    referenceOrderId AN (30) no Only mandatory for recurring/subscription transactions (recurringTransactionType=RECURRING) using PayPal. Order ID of the initial transaction (recurringTransactionType=FIRST) with which the payment agreement was created.

    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
    transactionBalance N No No The sum of all received payments minus the sum of all captured amounts plus all reductions. This value is negative when still waiting for payments, positive in case a transaction was overpaid, and zero when the debt is paid exactly or no capture was performed yet.
    transactionCurrency AN No No Currency code according to ISO4217
    customerEmail AN No No E-mail address of the customer related to the transaction.
    paymentDescriptor AN No No Description of the payment method selected by a customer at Amazon Pay
    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.
    2051 The provided subscription id is unknown.
    2052 Method call is not allowed in this state of subscription.
    2053 No changes were performed. Please provide at least one optional parameter.
    2054 Refund not allowed.
    2055 The payment has been rejected. Please use another payment method.
    2056 The provided paymentInstrumentID incorrect.
    2057 The credit card is expiring soon.
    2058 Solvency checks are not configured.
    2059 Add Payment Failed.
    2060 An external payment provider is not available.
    2063 Non PCI compliant merchant is not allowed to register credit cards.

    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

    Testdata

    Direct Debit:

    Account owner Any name
    IBAN DE06000000000023456789
    BIC SFRTDE20000

    Credit Card:

    Owner Any name
    Card Number 4321123443211234
    CVV Any three digit number
    Expiration Date Any valid date in the future

    Paypal:

    Username testing@crefopay.de
    Password #vaS7Rjt

    Sofort:

    Bankname 88888888
    Bank Routing Number 88888888
    PIN 8888

    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 by CrefoPay
    BILL_SECURE Bill payment Bill payment with payment guarantee though a third party provider
    AMAZON_PAY Amazon Pay Express checkout via Amazon Pay
    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

    Cookies

    The Cookies that are set by different CrefoPay products can be found in the table below:

    Merchant Service Area

    Name Domain Patn Expires Description
    JSESSIONID service.crefopay.de / Session ID to identify the user during the session
    language service.crefopay.de /msa3 Session Stores the language of the user
    locale service.crefopay.de /msa3 Session Stores the locale of the user

    HostedPages

    No Cookies are set

    SecureFields

    No Cookies are set