Skip to content

    Payengine Public

    Documentation for Payengine API v1.0

    Scroll down for code samples, example requests and responses.
    Select a language for code samples from the tabs or the mobile navigation menu.

    Tokenize payment instrument

    POST /payment-instruments

    Endpoint to create a new payment instrument. The service will store the payment credentials and return a paymentInstrumentId which can be used as a token for referencing the credentials for any payment operation.

    The storage complies with the latest PCI standards and regulations.

    A payment instrument can be created either explicitly (e.g. for credit card & sepa) or implicitly as part of a preauth or debit transaction. Payment instruments can be used for recurring payments, if the flag "recurring" is set to true.

    Parameters

    • Authorizationstringrequired

      Authentication for all client to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Bearer merchantId

    Tokenize payment instrument

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • typestringrequired

      The product which is represented by a paymentinstrument.

    • merchantPaymentInstrumentIdstringoptional

      The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

    • paymentobjectoptional
      • cardNumberstringoptional

        The Creditcard PAN used to proceed. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)

      • countrystringoptional

        The country which is used. (mandatory for klarna)

      • currencystringoptional

        The currency which is used. (mandatory for klarna)

      • localestringoptional

        The locale which is used. (mandatory for klarna)

      • verificationstringoptional

        The verification number of the creditcard. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)

      • expiryMonthstringoptional

        The expiry month of the creditcard. Format: 01 -> january, 02 -> February, etc. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)

      • expiryYearstringoptional

        The expiry year of the creditcard. Format: 01 -> 2001, 02 -> 2002, etc. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)

      • cardHolderstringoptional

        The full name of the cardholder.

      • bankNamestringoptional

        The name of the bank of the SEPA account.

      • ibanstringoptional

        IBAN of the SEPA account. (mandatory for sepa, optional if a sepa paymentInstrumentId was passed)

      • bicstringoptional

        BIC of the bank account. (mandatory for sepa payments with a non german iban, optional if a sepa paymentInstrumentId was passed optional for ideal and sofort-collecting)

      • accountHolderstringoptional

        The account holders name of the bank account. (Optional parameter for PPRO payments methods The maxLength value only for PPRO payment methods is 100.

      • customerstringoptional

        ID of the customer

      • mandateobjectoptional

        SEPA mandate (only mandatory for SEPA orders)

        • mandateIdstringoptional

          The mandateId assigned to the SEPA mandate (optional, payengine will generate the id if not present) The id needs to follow the following pattern '^[a-zA-Z0-9-]{1,35}'

        • createdDateTimenumber (date-time)optional

          Timestamp for mandate creation (mandatory)

        • mandateTextstringoptional

          Mandate text displayed to the customer (mandatory)

        • directDebitTypestringoptional

          The current mandate type of the direct debit type. The mandate type can be one of the following. FIRST: It's the first execution of the mandate SINGLE: It's used only for one execution of the mandate RECURRING: It's used for recurring mandate usage FINAL: It's the last execution of the recurring mandate

      • basketobjectoptional

        Basket of the customer (only mandatory for Klarna Orders)

        • namestringoptional

          name of the article

        • articleTypestringoptional

          This is the type of the article. Required for Klarna and optional for all other payment methods.

        • articleUrlstringoptional

          This is the url of the item in the basket

        • imageUrlstringoptional

          The image url of the item in the basket

        • quantitynumberoptional

          Quantity of the article

        • unitPricenumberoptional

          Unit price of the article

        • totalPricenumberoptional

          Total price of the article

        • discountnumberoptional

          It is negative value between -999999999999999998 and -1

      • returnUrlstringoptional

        Only for PayPal (mandatory) - The URL to which to redirect the customer when he or she accepts an agreement.

      • cancelUrlstringoptional

        Only for PayPal (mandatory) - The URL to which to redirect the customer when he or she cancels an agreement.

      • notifyUrlstringoptional

        Only for PayPal (optional) - The URL at which the instant payment notifications (IPN) are sent to notify the merchant when the agreement is created or canceled or payments on the agreement are processed.

      • billingAgreementIdobjectoptional

        Only for PayPal (optional) - when PayPal Billing Agreement is created by third party provider If billingAgreementId is provided, thеn the fields returnUrl, cancelUrl and notifyUrl are optional and should be ignored type: string

      • protocolVersionstringoptional

        Protocol version as provided from google.

      • signaturestringoptional

        signature as provided by google.

      • signedMessagestringoptional

        signed message as provided by google.

      • intermediateSigningKeyobjectoptional
        • signedKeystringoptional

          signed key as provided by google.

        • signaturesstringoptional

          signatures as provided by google.

    Request body

    {
        "type": "creditcard",
        "merchantPaymentInstrumentId": "string",
        "payment": {
            "cardNumber": "stringstring",
            "country": "st",
            "currency": "str",
            "locale": "string",
            "verification": "stri",
            "expiryMonth": "st",
            "expiryYear": "st",
            "cardHolder": "string",
            "bankName": "Deutsche Bank",
            "iban": "DE15111111111111111199",
            "bic": "DEUTDEDBKOE",
            "accountHolder": "Max Muster",
            "customer": "string",
            "mandate": {
                "mandateId": "string",
                "createdDateTime": 0,
                "mandateText": "string",
                "directDebitType": "FIRST"
            },
            "basket": {
                "name": "string",
                "articleType": "physical",
                "articleUrl": "string",
                "imageUrl": "string",
                "quantity": 0,
                "unitPrice": 0,
                "totalPrice": 0,
                "discount": 0
            },
            "returnUrl": "string",
            "cancelUrl": "string",
            "notifyUrl": "string",
            "billingAgreementId": {},
            "protocolVersion": "string",
            "signature": "string",
            "signedMessage": "string",
            "intermediateSigningKey": {
                "signedKey": "string",
                "signatures": "string"
            }
        }
    }

    Responses

    • 200Successful response.optional
      • paymentInstrumentIdstringrequired

        The identifier of the paymentinstrument. Created by payengine

      • merchantPaymentInstrumentIdstringrequired

        The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

      • originstringrequired

        The product used to create this order. (mandatory)

      • typestringrequired

        the type of the payment instrument

      • recurringbooleanrequired

        This flag indicates if this paymentinstrument can be used for recurring payments.

      • createdAtintegeroptional

        Timestamp when it was created

      • modifiedAtintegeroptional

        Timestamp when it was last updated

      • attributesobjectrequired

        Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

        • cofContractsarrayoptional

          For CreditCard only

          • idstringoptional

            Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

          • typestringoptional

            Credential on file type:

            • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
            • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
            • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
          • channelstringoptional

            The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

          • recurringExpirystring (date)optional

            Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

          • recurringFrequencynumberoptional

            Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

        • customerRelationUuidstringoptional

          For TWINT only. Recognition of a returning customer.

    • 400Bad request based on invalid input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
      • errorsarrayoptional
    {
        "paymentInstrumentId": "string",
        "merchantPaymentInstrumentId": "string",
        "origin": "creditcard",
        "type": "sepa",
        "recurring": true,
        "createdAt": 0,
        "modifiedAt": 0,
        "attributes": {
            "cofContracts": [
                {
                    "id": "contract_123abc456x",
                    "type": "ONECLICK",
                    "channel": "ECOM",
                    "recurringExpiry": "2019-07-10",
                    "recurringFrequency": 30
                }
            ],
            "customerRelationUuid": "string"
        }
    }

    Get list of payment instruments

    GET /payment-instruments

    Endpoint to receive a list of available paymentinstruments.

    The following parameters can be used as filter.

    • paymentInstrumentId
    • merchantPaymentInstrumentId
    • type
    • origin
    • recurring
    • createdAt
    • modifiedAt

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    Get list of payment instruments

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • elementsarrayrequired

        A list of paymeninstruments.

        • paymentInstrumentIdstringrequired

          The identifier of the paymentinstrument. Created by payengine

        • merchantPaymentInstrumentIdstringrequired

          The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

        • originstringrequired

          The product used to create this order. (mandatory)

        • typestringrequired

          the type of the payment instrument

        • recurringbooleanrequired

          This flag indicates if this paymentinstrument can be used for recurring payments.

        • createdAtintegeroptional

          Timestamp when it was created

        • modifiedAtintegeroptional

          Timestamp when it was last updated

        • attributesobjectrequired

          Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

          • cofContractsarrayoptional

            For CreditCard only

            • idstringoptional

              Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

            • typestringoptional

              Credential on file type:

              • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
              • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
              • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
            • channelstringoptional

              The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

            • recurringExpirystring (date)optional

              Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

            • recurringFrequencynumberoptional

              Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

          • customerRelationUuidstringoptional

            For TWINT only. Recognition of a returning customer.

      • totalPagesnumber (int)required

        A counter for the total pages returned.

    200

    {
        "elements": [
            {
                "paymentInstrumentId": "string",
                "merchantPaymentInstrumentId": "string",
                "origin": "creditcard",
                "type": "sepa",
                "recurring": true,
                "createdAt": 0,
                "modifiedAt": 0,
                "attributes": {
                    "cofContracts": [
                        {
                            "id": "contract_123abc456x",
                            "type": "ONECLICK",
                            "channel": "ECOM",
                            "recurringExpiry": "2019-07-10",
                            "recurringFrequency": 30
                        }
                    ],
                    "customerRelationUuid": "string"
                }
            }
        ],
        "totalPages": 1
    }

    Get payment instrument

    GET /payment-instruments/{paymentInstrumentId}

    Endpoint to receive a specific payment instrument referencing the paymentInstrumentId.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    Get payment instrument

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • paymentInstrumentIdstringrequired

        The identifier of the paymentinstrument. Created by payengine

      • merchantPaymentInstrumentIdstringrequired

        The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

      • originstringrequired

        The product used to create this order. (mandatory)

      • typestringrequired

        the type of the payment instrument

      • recurringbooleanrequired

        This flag indicates if this paymentinstrument can be used for recurring payments.

      • createdAtintegeroptional

        Timestamp when it was created

      • modifiedAtintegeroptional

        Timestamp when it was last updated

      • attributesobjectrequired

        Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

        • cofContractsarrayoptional

          For CreditCard only

          • idstringoptional

            Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

          • typestringoptional

            Credential on file type:

            • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
            • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
            • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
          • channelstringoptional

            The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

          • recurringExpirystring (date)optional

            Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

          • recurringFrequencynumberoptional

            Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

        • customerRelationUuidstringoptional

          For TWINT only. Recognition of a returning customer.

    • 404Not found caused by invalid input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
      • errorsarrayoptional
    {
        "paymentInstrumentId": "string",
        "merchantPaymentInstrumentId": "string",
        "origin": "creditcard",
        "type": "sepa",
        "recurring": true,
        "createdAt": 0,
        "modifiedAt": 0,
        "attributes": {
            "cofContracts": [
                {
                    "id": "contract_123abc456x",
                    "type": "ONECLICK",
                    "channel": "ECOM",
                    "recurringExpiry": "2019-07-10",
                    "recurringFrequency": 30
                }
            ],
            "customerRelationUuid": "string"
        }
    }

    Delete payment instrument

    DELETE /payment-instruments/{paymentInstrumentId}

    Endpoint to delete an existing payment instrument referencing the paymentInstrumentId.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    Delete payment instrument

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D");
    var request = new RestRequest(Method.DELETE);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 204Successful responseoptional
    • 404Not found caused by invalid input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
      • errorsarrayoptional

    404

    {
        "path": "v1/payment-instruments/paymentinstrument_asdfghjk",
        "timestamp": 1603275671582,
        "status": 404,
        "message": "Error while fetching payment instrument!",
        "code": 10001,
        "globalTrackId": "Some Request ID",
        "errors": [
            [
                {
                    "code": 10101,
                    "field": "paymentInstrumentId",
                    "message": "A Payment Instrument with specified id can not be found. Expected: A valid string identifier representing a Payment Instrument object between 1 and 255 characters."
                }
            ]
        ]
    }

    Update payment instrument

    PATCH /payment-instruments/{paymentInstrumentId}

    Endpoint to update an existing payment instrument referencing the paymentInstrumentId.

    Can be used to refresh the verification code (CVC) for card payment instruments, e.g. in case of a recurring transaction the shopper can be forced to re-enter the CVC.

    Parameters

    • Authorizationstringrequired

      Authentication for all client to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Bearer merchantId

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    Update payment instrument

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D");
    var request = new RestRequest(Method.PATCH);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • typestringoptional

      Type of the selected payment method provided by Klarna. E.g. klarna-pay-later

    • verificationstring (minLength: 3, maxLength: 4)optional

      The verification number of the creditcard. (CC only)

    • expiryMonthstringoptional

      The expiry month of the creditcard. (CC only)

    • expiryYearstringoptional

      The expiry year of the creditcard. (CC only)

    • cardHolderstringoptional

      The name of the creditcard holder. (CC only)

    • bankNamestringoptional

      The name of the bank. (SEPA only)

    • bicstringoptional

      The BIC of the bank. (SEPA only)

    • accountHolderstringoptional

      The name of the bank account holder. (SEPA only)

    • countrystringoptional

      Country which is used

    • currencystringoptional

      Currency which is used

    • localestringoptional

      Locale which is used

    • customerstringoptional

      The id of the customer

    • billingAddressstringoptional

      The id of the billing address

    • shippingAddressstringoptional

      The id of the shipping address

    • mandateobjectoptional

      SEPA mandate (only mandatory for SEPA orders)

      • mandateIdstringoptional

        The mandateId assigned to the SEPA mandate (optional, payengine will generate the id if not present) The id needs to follow the following pattern '^[a-zA-Z0-9-]{1,35}'

      • createdDateTimenumber (date-time)optional

        Timestamp for mandate creation (mandatory)

      • mandateTextstringoptional

        Mandate text displayed to the customer (mandatory)

      • directDebitTypestringoptional

        The current mandate type of the direct debit type. The mandate type can be one of the following. FIRST: It's the first execution of the mandate SINGLE: It's used only for one execution of the mandate RECURRING: It's used for recurring mandate usage FINAL: It's the last execution of the recurring mandate

    • basketobjectoptional

      Basket of the customer (only mandatory for Klarna Orders)

      • namestringoptional

        name of the article

      • articleTypestringoptional

        This is the type of the article. Required for Klarna and optional for all other payment methods.

      • articleUrlstringoptional

        This is the url of the item in the basket

      • imageUrlstringoptional

        The image url of the item in the basket

      • quantitynumberoptional

        Quantity of the article

      • unitPricenumberoptional

        Unit price of the article

      • totalPricenumberoptional

        Total price of the article

      • discountnumberoptional

        It is negative value between -999999999999999998 and -1

    • notifyUrlstringoptional

      Only for PayPal (mandatory) - The URL at which the instant payment notifications (IPN) are sent to notify the merchant when the agreement is created or canceled or payments on the agreement are processed.

    Request body

    {
        "type": "string",
        "verification": "stri",
        "expiryMonth": "string",
        "expiryYear": "string",
        "cardHolder": "string",
        "bankName": "string",
        "bic": "string",
        "accountHolder": "string",
        "country": "st",
        "currency": "str",
        "locale": "string",
        "customer": "string",
        "billingAddress": "string",
        "shippingAddress": "string",
        "mandate": {
            "mandateId": "string",
            "createdDateTime": 0,
            "mandateText": "string",
            "directDebitType": "FIRST"
        },
        "basket": {
            "name": "string",
            "articleType": "physical",
            "articleUrl": "string",
            "imageUrl": "string",
            "quantity": 0,
            "unitPrice": 0,
            "totalPrice": 0,
            "discount": 0
        },
        "notifyUrl": "string"
    }

    Responses

    • 200Successful response.optional
      • paymentInstrumentIdstringrequired

        The identifier of the paymentinstrument. Created by payengine

      • merchantPaymentInstrumentIdstringrequired

        The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

      • originstringrequired

        The product used to create this order. (mandatory)

      • typestringrequired

        the type of the payment instrument

      • recurringbooleanrequired

        This flag indicates if this paymentinstrument can be used for recurring payments.

      • createdAtintegeroptional

        Timestamp when it was created

      • modifiedAtintegeroptional

        Timestamp when it was last updated

      • attributesobjectrequired

        Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

        • cofContractsarrayoptional

          For CreditCard only

          • idstringoptional

            Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

          • typestringoptional

            Credential on file type:

            • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
            • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
            • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
          • channelstringoptional

            The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

          • recurringExpirystring (date)optional

            Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

          • recurringFrequencynumberoptional

            Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

        • customerRelationUuidstringoptional

          For TWINT only. Recognition of a returning customer.

    • 400Bad request caused by invalid input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
      • errorsarrayoptional
    {
        "paymentInstrumentId": "string",
        "merchantPaymentInstrumentId": "string",
        "origin": "creditcard",
        "type": "sepa",
        "recurring": true,
        "createdAt": 0,
        "modifiedAt": 0,
        "attributes": {
            "cofContracts": [
                {
                    "id": "contract_123abc456x",
                    "type": "ONECLICK",
                    "channel": "ECOM",
                    "recurringExpiry": "2019-07-10",
                    "recurringFrequency": 30
                }
            ],
            "customerRelationUuid": "string"
        }
    }

    Initiate cardcheck

    POST /payment-instruments/{paymentInstrumentId}/card-check

    Service to initiate a card check which will results in a 0,00 EUR authorization.

    The card check authorization can be used as an initial authorization containing the 3DS information in case the merchant only stores the payment credentials and at this point no real payment should be initiated.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    Initiate cardcheck

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D/card-check");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • cardAcquirerRoutingTostringoptional

      Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

    • cofContractobjectoptional

      The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

      • typestringoptional

        Credential on file type:

        • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
        • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
        • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
      • channelstringoptional

        The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

    • threeDsAuthenticationIdstringoptional

      Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.

    Request body

    {
        "cardAcquirerRoutingTo": "concardis",
        "cofContract": {
            "type": "ONECLICK",
            "channel": "ECOM"
        },
        "threeDsAuthenticationId": "threeDsAuthentication_123abc987y"
    }

    Responses

    • 200Successful response.optional
      • idstringoptional

        A unique transaction identifier generated by the Payengine.

      • createdAtnumberoptional

        Timestamp when card check was initiated.

      • modifiedAtnumberoptional

        Timestamp when card check was modified.

      • statusstringoptional

        The status of the card check.

      • threeDsAuthenticationIdstringoptional

        Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.

      • cofContractobjectoptional

        The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

        • idstringoptional

          Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

        • typestringoptional

          Credential on file type:

          • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
          • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
          • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
        • channelstringoptional

          The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

        • recurringExpirystring (date)optional

          Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

        • recurringFrequencynumberoptional

          Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

      • errorDetailsobjectoptional

        Object containing error information in case of a FAILURE status.

        • providerCodestringoptional

          Card processor code in case of an error.

        • providerMessagestringoptional

          Card processor message in case of an error.

    200

    {
        "id": "cardcheck_abc123xyz4",
        "createdAt": 1562574062133,
        "modifiedAt": 1562574062133,
        "status": "SUCCESS",
        "threeDsAuthenticationId": "authentication_123abc456x",
        "cofContract": {
            "id": "contract_123abc456x",
            "type": "ONECLICK",
            "channel": "ECOM",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "cardAcquirerRoutingTo": "concardis",
        "errorDetails": {
            "providerCode": "00",
            "providerMessage": "Transaction Approved"
        }
    }

    Create 3DS version info

    POST /payment-instruments/{paymentInstrumentId}/3ds-version

    Endpoint to check the supported 3DS version and receive additional 3DS related information.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    Create 3DS version info

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D/3ds-version");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • cardAcquirerRoutingTostringoptional

      Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

    Request body

    {
        "cardAcquirerRoutingTo": "concardis"
    }

    Responses

    • 200Successful response.optional
      • idstringrequired

        Payeninge identifier for the 3DS version object

      • createdAtnumberrequired

        Timestamp when card check was initiated

      • modifiedAtnumberrequired

        Timestamp when card check was modified

      • versionstringoptional

        Optional parameter showing the 3DS version if the card is enrolled for 3DS. Could be used also as indicator if the card is 3DS enrolled.

      • specificDataobjectoptional

        Generic object which will contain 3DS version specific data

        • methodUrlstringoptional

          The ACS URL that will be used by the 3DS Method, retrieved from the card range data repository (3DS 2.0 only).

        • base64EncodedThreeDsMethodDatastringoptional

          Base64 encoded JSON object containing 3DS Server Transaction ID and 3DS Method Notification URL. This value shall be used when communicating to the ACS 3DS Method URL. (3DS 2.0 only)

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

    • 400Not found caused by invalid input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
    {
        "id": "threedsversion_123abc456z",
        "createdAt": 1562769950956,
        "modifiedAt": 1562769950956,
        "version": "2.0",
        "specificData": {
            "methodUrl": "https://www.acs.com/script",
            "base64EncodedThreeDsMethodData": "YmFzZTY0RW5jb2RlZFRocmVlRHNNZXRob2REYXRh"
        },
        "cardAcquirerRoutingTo": "concardis"
    }

    Store browser information

    POST /browser-info

    Endpoint to store browser session information, the browser session information is usually collected via javascript.

    Parameters

    • Authorizationstringrequired

      Authentication for all client to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Bearer merchantId

    Store browser information

    var client = new RestClient("https://apitest.payengine.de/v1/browser-info");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • acceptHeaderstringoptional

      Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder's browser. This field is limited to maximum 2048 characters and if the total length exceeds the limit, the 3DS Server truncates the excess portion.

    • ipstringoptional

      IP address of the browser as returned by the HTTP headers to the 3DS Requestor. The field is limited to maximum 45 characters and the accepted values are as following: - IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. - IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:).

    • javaEnabledbooleanoptional

      Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.

    • languagestringoptional

      Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property.

    • colorDepthnumberoptional

      Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.

    • screenHeightnumberoptional

      Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.

    • screenWidthnumberoptional

      Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.

    • timezonenumberoptional

      Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method.

    • userAgentstringoptional

      Exact content of the HTTP user-agent header.

    • windowSizestringoptional

      Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width X height in pixels of the window displayed in the Cardholder browser window. This is used only to prepare the CReq request and it is not part of the AReq flow. If not present it will be omitted. However, when sending the Challenge Request. Accepted values are: 01 -> 250 x 400 02 -> 390 x 400 03 -> 500 x 600 04 -> 600 x 400 05 -> Full screen

    Request body

    {
        "acceptHeader": "brw-accept-header",
        "ip": "192.168.0.1",
        "javaEnabled": true,
        "language": "en-US",
        "colorDepth": 8,
        "screenHeight": 100,
        "screenWidth": 100,
        "timezone": 60,
        "userAgent": "Chrome/71.0.3578.98",
        "windowSize": "05"
    }

    Responses

    • 200Successful response.optional
      • browserInfoIdstringoptional

        Payengine identifier of the browser info object

    200

    {
        "browserInfoId": "browserinfo_123xyz456a"
    }

    Create 3DS authentication

    POST /payment-instruments/{paymentInstrumentId}/3ds-version/{threeDsVersionId}/3ds-authentication

    Endpoint to create a standalone 3DS authentication for the given payment-instrument based on the 3DS version result

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • paymentInstrumentIdstringrequired

      ID of the specific paymentinstrument.

    • threeDsVersionIdstringrequired

      ID of the specific 3DS version result.

    Create 3DS authentication

    var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/%7BpaymentInstrumentId%7D/3ds-version/%7BthreeDsVersionId%7D/3ds-authentication");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • typestringoptional

      The type of the authentication requested. PAYMENT_TRANSACTION: authentication with payment; the authentication is used for a normal payment transaction, RECURRING_TRANSACTION: authentication with payment; the authentication is used for an initial recurring payment transaction, RECURRING_CARDCHECK: authentication without payment; the authentication is used for a card check representing the initial recurring payment transaction, ADD_CARD: authentication without payment; the authentication is only used for the verification of stored card credentials, e.g. within a wallet

    • customerIdstringoptional

      The identifier of a payengine customer.

    • shippingAddressIdstringoptional

      The identifier of a payengine address.

    • billingAddressIdstringoptional

      The identifier of a payengine address.

    • transactionDataobjectoptional

      Object containing transaction information

      • amountnumberoptional

        The amount of the purchase. In case of an authentication without payment for recurring future payments this should include the expected total purchase amount. The amount can be 0 for a RECURRING_CARDCHECK or ADD_CARD authentication. The amount needs to be in the minor currency unit.

      • currencystringoptional

        The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217

      • recurringExpirystring (date)optional

        Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

      • recurringFrequencynumberoptional

        Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

    • riskobjectoptional

      An object containing information relevant for risk analysis on the issuere side.

      • customerAccountobjectoptional

        An object containing information about the customer account with the merchant.

        • accountIdentifierstringoptional

          The account identifier at the merchant side.

        • creationDatestring (date)optional

          The date when the customer opened the account with the merchant.

        • lastChangeDatestring (date)optional

          The date when the customer account with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

        • changeIndicatorstringoptional

          Length of the time since the customer account information with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

        • lastPasswordChangeDatestring (date)optional

          The date when the customer account with the merchant had a password change or account reset.

        • passwordChangeIndicatorstringoptional

          Length of the time since the customer account information with the merchant had a password change or account reset.

        • authenticationMethodstringoptional

          Mechanism used by the customer to authenticate to the merchant account.

        • authenticationTimestampstring (date-time)optional

          Date and time in UTC of the customer authentication to the merchant account.

        • shippingAddressUsageIndicatorstringoptional

          Indicates when the shipping address used for this transaction was first used with the merchant account.

        • shippingAddressFirstUsagestring (date)optional

          Date when the shipping address used for this transaction was first used with the merchant.

        • transactionCountLastDaynumberoptional

          Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.

        • transactionCountLastYearnumberoptional

          Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.

        • orderCountLast6Monthsnumberoptional

          Number of purchases with this cardholder account during the previous six months.

        • suspiciousActivitybooleanoptional

          Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.

        • accountEqualsShippingNamebooleanoptional

          Indicates if the customer name on the account is identical to the shipping name used for this transaction.

        • paymentAccountAgeIndicatorstringoptional

          Indicates the length of time that the payment account was enrolled in the customer account with the merchant.

        • paymentAccountEnrollementDatestring (date)optional

          Date that the payment account was enrolled in the customer account with the merchant.

      • shippingInfoobjectoptional

        object containing information about the shipping details for this transaction.

        • shippingEqualsBillingAddressbooleanoptional

          Flag if the shipping address equals the billing address.

        • shippingIndicatorstringoptional

          Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator that most accurately describes the customer's specific transaction. If one or more items are included in the sale, use the shipping indicator for the physical goods, or if all digital goods, use the indicator that describes the most expensive item.

        • deliveryTimestringoptional

          Indicates the merchandise delivery timeframe.

        • deliveryEmailstringoptional

          For electronic delivery, the email address to which the merchandise was delivered.

      • orderInfoobjectoptional

        object containing order information relevant for risk evaluation

        • isReorderbooleanoptional

          Indicates whether the cardholder is reordering previously purchased merchandise.

        • preOrderIndicatorstringoptional

          Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

        • preOrderDatestring (date)optional

          For a pre-ordered purchase, the expected date that the merchandise will be available.

        • orderTypestringoptional

          Identifies the type of transaction being authenticated. The values are derived from ISO 8583. If this value is not provided, a default value of 01 is used. Accepted values are: 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan

    • browserInfoIdstringoptional

      Payengine identifier of the browser info object

    • sdkInfoIdstringoptional

      Payengine identifier of the sdk info object

    • asyncobjectoptional

      An object containing the relevant URLs for asynchronous communication

      • notificationUrlstringoptional

        URL where the result of the 3DS transaction will be sent to

      • successUrlstringoptional

        URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded

      • failureUrlstringoptional

        URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed

    • forceChallengebooleanoptional

      Flag to force challenge for 3ds v2

    Request body

    {
        "type": "PAYMENT_TRANSACTION",
        "customerId": "customer_abc123xyz1",
        "shippingAddressId": "address_abc123xyz1",
        "billingAddressId": "address_abc123xyz1",
        "transactionData": {
            "amount": 1000,
            "currency": "EUR",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "risk": {
            "customerAccount": {
                "accountIdentifier": "customer-abc123",
                "creationDate": "2019-07-10",
                "lastChangeDate": "2019-07-10",
                "changeIndicator": "CHANGED_WITH_THIS_TRANSACTION",
                "lastPasswordChangeDate": "2019-07-10",
                "passwordChangeIndicator": "LESS_THAN_THIRTY_DAYS",
                "authenticationMethod": "OWN_CREDENTIALS",
                "authenticationTimestamp": "2019-07-10T15:04:09.722Z",
                "shippingAddressUsageIndicator": "LESS_THAN_THIRTY_DAYS",
                "shippingAddressFirstUsage": "2019-07-10",
                "transactionCountLastDay": 1,
                "transactionCountLastYear": 10,
                "orderCountLast6Months": 5,
                "suspiciousActivity": false,
                "accountEqualsShippingName": true,
                "paymentAccountAgeIndicator": "NO_ACCOUNT",
                "paymentAccountEnrollementDate": "2019-07-10"
            },
            "shippingInfo": {
                "shippingEqualsBillingAddress": true,
                "shippingIndicator": "SHIP_TO_BILLING_ADDRESS",
                "deliveryTime": "SAME_DAY",
                "deliveryEmail": "john@doe.com"
            },
            "orderInfo": {
                "isReorder": false,
                "preOrderIndicator": "MERCHANTDISE_AVAILABLE",
                "preOrderDate": "2019-07-10",
                "orderType": "01"
            }
        },
        "browserInfoId": "browserinfo_123abc456d",
        "sdkInfoId": "sdkinfo_123abc456d",
        "async": {
            "notificationUrl": "https://my.notification.url",
            "successUrl": "https://my.success.url",
            "failureUrl": "https://my.failure.url"
        },
        "forceChallenge": true
    }

    Responses

    • 200Successful response.optional
      • idstringoptional

        Identifier of the 3DS authentication transaction generated by the Payengine

      • createdAtnumberoptional

        Timestamp when the authentication was initiated.

      • modifiedAtnumberoptional

        Timestamp when the authentication was modified.

      • paymentInstrumentIdstringoptional

        Identifier of the payment instrument used for the 3DS authentication.

      • threeDsVersionIdstringoptional

        Identifier of the 3DS version info based on which the authentication was done.

      • authenticationResultobjectoptional

        Object containing the result of the 3DS authentication transaction (final results will be available only in case of frictionless flow)

        • versionstringoptional

          Parameter indicating the version of the 3DS

        • statusstringoptional

          Indicates whether a transaction qualifies as an authenticated transaction. Y = authentication verificationsuccessful A = authentication attempted; not authenticated, but a proof of attempted authentication is provided C = challenge required; additional SCA authentication is required U = authentication could not be performed; technical or other problem R = authentication rejected; issuer is rejecting N = not authenticated; transaction denied

        • redirectUrlstringoptional

          Conditional - present in case of 3DS 1.0 and challenge flow for 3DS 2.0 redirect URL leading to hosted page by Payengine used for Cardholder authentication (main flow for 3DS 1.0 and fallback flow in case of challenge for 3DS 2.0)

        • challengeDataobjectoptional

          Conditional - information available in case of CHALLENGE status, needed for building the challenge iFrame.

          • acsUrlstringoptional

            Fully qualified URL of the ACS in case the authentication response message indicates that further cardholder interaction is required to complete the authentication. relevant for 3DS 2.0 only

          • base64EncodedChallengeRequeststringoptional

            Base64-encoded Challenge Request object in case the authentication response message indicates that further Cardholder interaction is required to complete the authentication. (3DS 2.0)

          • challengeWindowSizestringoptional

            Dimensions of the challenge iframe window in which the challenge page will be displayed to the Cardholder. This value should match the provided size in the browserInfo call. EMVCo assigned window size. '01' -> 250px x 400px, '02' -> 390px x 400px, '03' -> 500px x 600px, '04' -> 600px x 400px, '05' -> Full screen, or full container content relevant for 3DS 2.0 only

        • transactionIdstringoptional

          The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID

        • acsReferenceNumberstringoptional

          Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. Set by the EMVCo Secretariat.

        • acsSignedContentstringoptional

          Contains the JWS object (represented as a string) created by the ACS for the ARes message. The body of JWS object (represented as a string) will contain the following data elements as defined • ACS URL • ACS Ephemeral Public Key (QT) • SDK Ephemeral Public Key (QC)

        • acsTransactionIdstringoptional

          Universally Unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements.

        • authenticationValuestringoptional

          The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard

        • cardholderInfostringoptional

          Statement about the result of the 3DS authentication.

        • ecistringoptional

          The Electronic Commerce Indicator (ECI) provided by the ACS or DS to indicate the results of the attempt to authenticate the cardholder. The ECI values might differ depending on the card scheme. For all fully authenticated or authentication attempted transactions the liability will be shifted to the card issuer. Mastercard 00 - fully authenticated 01 - authentication attempted 02 - no authentication available 07 - fully authenticated*1 All other card schemes 05 - fully authenticated 06 - authentication attempted 07 - no authentication available *1 - Mastercard distinguishes between fully authenticated recurring payments (flagged with ECI 07) and all other fully authenticated transactions (flagged with ECI 00).

        • statusReasonstringoptional

          Reason why the authenticationResult.status field has the specified value. 01 = Card authentication failed 02 = Unknown Device 03 = Unsupported Device 04 = Exceeds authentication frequency limit 05 = Expired card 06 = Invalid card number 07 = Invalid transaction 08 = No Card record 09 = Security failure 10 = Stolen card 11 = Suspected fraud 12 = Transaction not permitted to cardholder 13 = Cardholder not enrolled in service 14 = Transaction timed out at the ACS 15 = Low confidence 16 = Medium confidence 17 = High confidence 18 = Very High confidence 19 = Exceeds ACS maximum challenges 20 = Non-Payment transaction not supported 21 = 3RI transaction not supported 22 = ACS technical issue 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor 24 = 3DS Requestor Decoupled Max Expiry Time exceeded 25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt 26 = Authentication attempted but not performed by the cardholder 27–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use

        • forceChallengebooleanoptional

          Flag to force challenge for 3ds v2

        • errorDetailsobjectoptional

          Object containing error information in case of error.

          • providerCodestringoptional

            Original error code from the 3DS server or mpi

          • providerMessagestringoptional

            Original error message from the 3DS server or mpi

      • typestringoptional

        The type of the authentication requested. PAYMENT_TRANSACTION: authentication with payment; the authentication is used for a normal payment transaction, RECURRING_TRANSACTION: authentication with payment; the authentication is used for an initial recurring payment transaction, RECURRING_CARDCHECK: authentication without payment; the authentication is used for a card check representing the initial recurring payment transaction, ADD_CARD: authentication without payment; the authentication is only used for the verification of stored card credentials, e.g. within a wallet

      • customerIdstringoptional

        The identifier of a payengine customer.

      • shippingAddressIdstringoptional

        The identifier of a payengine address.

      • billingAddressIdstringoptional

        The identifier of a payengine address.

      • transactionDataobjectoptional

        Object containing transaction information

        • amountnumberoptional

          The amount of the purchase. In case of an authentication without payment for recurring future payments this should include the expected total purchase amount. The amount can be 0 for a RECURRING_CARDCHECK or ADD_CARD authentication. The amount needs to be in the minor currency unit.

        • currencystringoptional

          The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217

        • recurringExpirystring (date)optional

          Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

        • recurringFrequencynumberoptional

          Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

      • riskobjectoptional

        An object containing information relevant for risk analysis on the issuere side.

        • customerAccountobjectoptional

          An object containing information about the customer account with the merchant.

          • accountIdentifierstringoptional

            The account identifier at the merchant side.

          • creationDatestring (date)optional

            The date when the customer opened the account with the merchant.

          • lastChangeDatestring (date)optional

            The date when the customer account with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

          • changeIndicatorstringoptional

            Length of the time since the customer account information with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

          • lastPasswordChangeDatestring (date)optional

            The date when the customer account with the merchant had a password change or account reset.

          • passwordChangeIndicatorstringoptional

            Length of the time since the customer account information with the merchant had a password change or account reset.

          • authenticationMethodstringoptional

            Mechanism used by the customer to authenticate to the merchant account.

          • authenticationTimestampstring (date-time)optional

            Date and time in UTC of the customer authentication to the merchant account.

          • shippingAddressUsageIndicatorstringoptional

            Indicates when the shipping address used for this transaction was first used with the merchant account.

          • shippingAddressFirstUsagestring (date)optional

            Date when the shipping address used for this transaction was first used with the merchant.

          • transactionCountLastDaynumberoptional

            Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.

          • transactionCountLastYearnumberoptional

            Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.

          • orderCountLast6Monthsnumberoptional

            Number of purchases with this cardholder account during the previous six months.

          • suspiciousActivitybooleanoptional

            Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.

          • accountEqualsShippingNamebooleanoptional

            Indicates if the customer name on the account is identical to the shipping name used for this transaction.

          • paymentAccountAgeIndicatorstringoptional

            Indicates the length of time that the payment account was enrolled in the customer account with the merchant.

          • paymentAccountEnrollementDatestring (date)optional

            Date that the payment account was enrolled in the customer account with the merchant.

        • shippingInfoobjectoptional

          object containing information about the shipping details for this transaction.

          • shippingEqualsBillingAddressbooleanoptional

            Flag if the shipping address equals the billing address.

          • shippingIndicatorstringoptional

            Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator that most accurately describes the customer's specific transaction. If one or more items are included in the sale, use the shipping indicator for the physical goods, or if all digital goods, use the indicator that describes the most expensive item.

          • deliveryTimestringoptional

            Indicates the merchandise delivery timeframe.

          • deliveryEmailstringoptional

            For electronic delivery, the email address to which the merchandise was delivered.

        • orderInfoobjectoptional

          object containing order information relevant for risk evaluation

          • isReorderbooleanoptional

            Indicates whether the cardholder is reordering previously purchased merchandise.

          • preOrderIndicatorstringoptional

            Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

          • preOrderDatestring (date)optional

            For a pre-ordered purchase, the expected date that the merchandise will be available.

          • orderTypestringoptional

            Identifies the type of transaction being authenticated. The values are derived from ISO 8583. If this value is not provided, a default value of 01 is used. Accepted values are: 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan

      • browserInfoIdstringoptional

        Payengine identifier of the browser info object

      • asyncobjectoptional

        An object containing the relevant URLs for asynchronous communication

        • notificationUrlstringoptional

          URL where the result of the 3DS transaction will be sent to

        • successUrlstringoptional

          URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded

        • failureUrlstringoptional

          URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed

      • forceChallengebooleanoptional

        Flag to force challenge for 3ds v2

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

      • correlationIdstringoptional

        This field is needed by the mobile sdk to initialize the challenge flow and should be returned both in the authentication response for standalone authentication and in the meta.threeDsdata.authenticationResult section of the order intent execution response. It's equivalent to threeDSServerTransID

    200

    {
        "id": "authentication_def456abc9",
        "createdAt": 1562769950956,
        "modifiedAt": 1562769950956,
        "paymentInstrumentId": "paymentinstrument_pkekrrl5ua",
        "threeDsVersionId": "threedsversion_123def987a",
        "authenticationResult": {
            "version": "2.0",
            "status": "Y",
            "redirectUrl": "https://link-the-hosted-challange.example",
            "challengeData": {
                "acsUrl": "https://link-to-the-issuer.acs",
                "base64EncodedChallengeRequest": "Y2hhbGxhbmdlRGF0YQ==",
                "challengeWindowSize": "05"
            },
            "transactionId": "d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4",
            "acsReferenceNumber": "string",
            "acsSignedContent": "string",
            "acsTransactionId": "string",
            "authenticationValue": "YXV0aGVudGljYXRpb25WYWx1ZQ==",
            "cardholderInfo": "string",
            "eci": "05",
            "statusReason": "01",
            "forceChallenge": true,
            "errorDetails": {
                "providerCode": "301",
                "providerMessage": "TRANSACTION_ID_NOT_RECOGNIZED"
            }
        },
        "type": "PAYMENT_TRANSACTION",
        "customerId": "customer_abc123xyz1",
        "shippingAddressId": "address_abc123xyz1",
        "billingAddressId": "address_abc123xyz1",
        "transactionData": {
            "amount": 1000,
            "currency": "EUR",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "risk": {
            "customerAccount": {
                "accountIdentifier": "customer-abc123",
                "creationDate": "2019-07-10",
                "lastChangeDate": "2019-07-10",
                "changeIndicator": "CHANGED_WITH_THIS_TRANSACTION",
                "lastPasswordChangeDate": "2019-07-10",
                "passwordChangeIndicator": "LESS_THAN_THIRTY_DAYS",
                "authenticationMethod": "OWN_CREDENTIALS",
                "authenticationTimestamp": "2019-07-10T15:04:09.722Z",
                "shippingAddressUsageIndicator": "LESS_THAN_THIRTY_DAYS",
                "shippingAddressFirstUsage": "2019-07-10",
                "transactionCountLastDay": 1,
                "transactionCountLastYear": 10,
                "orderCountLast6Months": 5,
                "suspiciousActivity": false,
                "accountEqualsShippingName": true,
                "paymentAccountAgeIndicator": "NO_ACCOUNT",
                "paymentAccountEnrollementDate": "2019-07-10"
            },
            "shippingInfo": {
                "shippingEqualsBillingAddress": true,
                "shippingIndicator": "SHIP_TO_BILLING_ADDRESS",
                "deliveryTime": "SAME_DAY",
                "deliveryEmail": "john@doe.com"
            },
            "orderInfo": {
                "isReorder": false,
                "preOrderIndicator": "MERCHANTDISE_AVAILABLE",
                "preOrderDate": "2019-07-10",
                "orderType": "01"
            }
        },
        "browserInfoId": "browserinfo_123abc456d",
        "async": {
            "notificationUrl": "https://my.notification.url",
            "successUrl": "https://my.success.url",
            "failureUrl": "https://my.failure.url"
        },
        "forceChallenge": true,
        "cardAcquirerRoutingTo": "concardis",
        "correlationId": "e302d01e-0a0e-4556-a8d2-64bd433170bc"
    }

    Get 3DS authentication result

    GET /creditcard/3ds-authentication/{threeDsAuthenticationId}

    Endpoint to fetch the result details of a 3DS authentication.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • threeDsAuthenticationIdstringrequired

      ID of the specific 3DS authentication.

    Get 3DS authentication result

    var client = new RestClient("https://apitest.payengine.de/v1/creditcard/3ds-authentication/%7BthreeDsAuthenticationId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • idstringoptional

        Identifier of the 3DS authentication transaction generated by the Payengine

      • createdAtnumberoptional

        Timestamp when the authentication was initiated.

      • modifiedAtnumberoptional

        Timestamp when the authentication was modified.

      • paymentInstrumentIdstringoptional

        Identifier of the payment instrument used for the 3DS authentication.

      • threeDsVersionIdstringoptional

        Identifier of the 3DS version info based on which the authentication was done.

      • authenticationResultobjectoptional

        Object containing the result of the 3DS authentication transaction (final results will be available only in case of frictionless flow)

        • versionstringoptional

          Parameter indicating the version of the 3DS

        • statusstringoptional

          Indicates whether a transaction qualifies as an authenticated transaction. Y = authentication verificationsuccessful A = authentication attempted; not authenticated, but a proof of attempted authentication is provided C = challenge required; additional SCA authentication is required U = authentication could not be performed; technical or other problem R = authentication rejected; issuer is rejecting N = not authenticated; transaction denied

        • redirectUrlstringoptional

          Conditional - present in case of 3DS 1.0 and challenge flow for 3DS 2.0 redirect URL leading to hosted page by Payengine used for Cardholder authentication (main flow for 3DS 1.0 and fallback flow in case of challenge for 3DS 2.0)

        • challengeDataobjectoptional

          Conditional - information available in case of CHALLENGE status, needed for building the challenge iFrame.

          • acsUrlstringoptional

            Fully qualified URL of the ACS in case the authentication response message indicates that further cardholder interaction is required to complete the authentication. relevant for 3DS 2.0 only

          • base64EncodedChallengeRequeststringoptional

            Base64-encoded Challenge Request object in case the authentication response message indicates that further Cardholder interaction is required to complete the authentication. (3DS 2.0)

          • challengeWindowSizestringoptional

            Dimensions of the challenge iframe window in which the challenge page will be displayed to the Cardholder. This value should match the provided size in the browserInfo call. EMVCo assigned window size. '01' -> 250px x 400px, '02' -> 390px x 400px, '03' -> 500px x 600px, '04' -> 600px x 400px, '05' -> Full screen, or full container content relevant for 3DS 2.0 only

        • transactionIdstringoptional

          The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID

        • acsReferenceNumberstringoptional

          Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. Set by the EMVCo Secretariat.

        • acsSignedContentstringoptional

          Contains the JWS object (represented as a string) created by the ACS for the ARes message. The body of JWS object (represented as a string) will contain the following data elements as defined • ACS URL • ACS Ephemeral Public Key (QT) • SDK Ephemeral Public Key (QC)

        • acsTransactionIdstringoptional

          Universally Unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements.

        • authenticationValuestringoptional

          The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard

        • cardholderInfostringoptional

          Statement about the result of the 3DS authentication.

        • ecistringoptional

          The Electronic Commerce Indicator (ECI) provided by the ACS or DS to indicate the results of the attempt to authenticate the cardholder. The ECI values might differ depending on the card scheme. For all fully authenticated or authentication attempted transactions the liability will be shifted to the card issuer. Mastercard 00 - fully authenticated 01 - authentication attempted 02 - no authentication available 07 - fully authenticated*1 All other card schemes 05 - fully authenticated 06 - authentication attempted 07 - no authentication available *1 - Mastercard distinguishes between fully authenticated recurring payments (flagged with ECI 07) and all other fully authenticated transactions (flagged with ECI 00).

        • statusReasonstringoptional

          Reason why the authenticationResult.status field has the specified value. 01 = Card authentication failed 02 = Unknown Device 03 = Unsupported Device 04 = Exceeds authentication frequency limit 05 = Expired card 06 = Invalid card number 07 = Invalid transaction 08 = No Card record 09 = Security failure 10 = Stolen card 11 = Suspected fraud 12 = Transaction not permitted to cardholder 13 = Cardholder not enrolled in service 14 = Transaction timed out at the ACS 15 = Low confidence 16 = Medium confidence 17 = High confidence 18 = Very High confidence 19 = Exceeds ACS maximum challenges 20 = Non-Payment transaction not supported 21 = 3RI transaction not supported 22 = ACS technical issue 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor 24 = 3DS Requestor Decoupled Max Expiry Time exceeded 25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt 26 = Authentication attempted but not performed by the cardholder 27–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use

        • forceChallengebooleanoptional

          Flag to force challenge for 3ds v2

        • errorDetailsobjectoptional

          Object containing error information in case of error.

          • providerCodestringoptional

            Original error code from the 3DS server or mpi

          • providerMessagestringoptional

            Original error message from the 3DS server or mpi

      • typestringoptional

        The type of the authentication requested. PAYMENT_TRANSACTION: authentication with payment; the authentication is used for a normal payment transaction, RECURRING_TRANSACTION: authentication with payment; the authentication is used for an initial recurring payment transaction, RECURRING_CARDCHECK: authentication without payment; the authentication is used for a card check representing the initial recurring payment transaction, ADD_CARD: authentication without payment; the authentication is only used for the verification of stored card credentials, e.g. within a wallet

      • customerIdstringoptional

        The identifier of a payengine customer.

      • shippingAddressIdstringoptional

        The identifier of a payengine address.

      • billingAddressIdstringoptional

        The identifier of a payengine address.

      • transactionDataobjectoptional

        Object containing transaction information

        • amountnumberoptional

          The amount of the purchase. In case of an authentication without payment for recurring future payments this should include the expected total purchase amount. The amount can be 0 for a RECURRING_CARDCHECK or ADD_CARD authentication. The amount needs to be in the minor currency unit.

        • currencystringoptional

          The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217

        • recurringExpirystring (date)optional

          Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

        • recurringFrequencynumberoptional

          Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

      • riskobjectoptional

        An object containing information relevant for risk analysis on the issuere side.

        • customerAccountobjectoptional

          An object containing information about the customer account with the merchant.

          • accountIdentifierstringoptional

            The account identifier at the merchant side.

          • creationDatestring (date)optional

            The date when the customer opened the account with the merchant.

          • lastChangeDatestring (date)optional

            The date when the customer account with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

          • changeIndicatorstringoptional

            Length of the time since the customer account information with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

          • lastPasswordChangeDatestring (date)optional

            The date when the customer account with the merchant had a password change or account reset.

          • passwordChangeIndicatorstringoptional

            Length of the time since the customer account information with the merchant had a password change or account reset.

          • authenticationMethodstringoptional

            Mechanism used by the customer to authenticate to the merchant account.

          • authenticationTimestampstring (date-time)optional

            Date and time in UTC of the customer authentication to the merchant account.

          • shippingAddressUsageIndicatorstringoptional

            Indicates when the shipping address used for this transaction was first used with the merchant account.

          • shippingAddressFirstUsagestring (date)optional

            Date when the shipping address used for this transaction was first used with the merchant.

          • transactionCountLastDaynumberoptional

            Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.

          • transactionCountLastYearnumberoptional

            Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.

          • orderCountLast6Monthsnumberoptional

            Number of purchases with this cardholder account during the previous six months.

          • suspiciousActivitybooleanoptional

            Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.

          • accountEqualsShippingNamebooleanoptional

            Indicates if the customer name on the account is identical to the shipping name used for this transaction.

          • paymentAccountAgeIndicatorstringoptional

            Indicates the length of time that the payment account was enrolled in the customer account with the merchant.

          • paymentAccountEnrollementDatestring (date)optional

            Date that the payment account was enrolled in the customer account with the merchant.

        • shippingInfoobjectoptional

          object containing information about the shipping details for this transaction.

          • shippingEqualsBillingAddressbooleanoptional

            Flag if the shipping address equals the billing address.

          • shippingIndicatorstringoptional

            Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator that most accurately describes the customer's specific transaction. If one or more items are included in the sale, use the shipping indicator for the physical goods, or if all digital goods, use the indicator that describes the most expensive item.

          • deliveryTimestringoptional

            Indicates the merchandise delivery timeframe.

          • deliveryEmailstringoptional

            For electronic delivery, the email address to which the merchandise was delivered.

        • orderInfoobjectoptional

          object containing order information relevant for risk evaluation

          • isReorderbooleanoptional

            Indicates whether the cardholder is reordering previously purchased merchandise.

          • preOrderIndicatorstringoptional

            Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

          • preOrderDatestring (date)optional

            For a pre-ordered purchase, the expected date that the merchandise will be available.

          • orderTypestringoptional

            Identifies the type of transaction being authenticated. The values are derived from ISO 8583. If this value is not provided, a default value of 01 is used. Accepted values are: 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan

      • browserInfoIdstringoptional

        Payengine identifier of the browser info object

      • asyncobjectoptional

        An object containing the relevant URLs for asynchronous communication

        • notificationUrlstringoptional

          URL where the result of the 3DS transaction will be sent to

        • successUrlstringoptional

          URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded

        • failureUrlstringoptional

          URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed

      • forceChallengebooleanoptional

        Flag to force challenge for 3ds v2

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

      • correlationIdstringoptional

        This field is needed by the mobile sdk to initialize the challenge flow and should be returned both in the authentication response for standalone authentication and in the meta.threeDsdata.authenticationResult section of the order intent execution response. It's equivalent to threeDSServerTransID

    200

    {
        "id": "authentication_def456abc9",
        "createdAt": 1562769950956,
        "modifiedAt": 1562769950956,
        "paymentInstrumentId": "paymentinstrument_pkekrrl5ua",
        "threeDsVersionId": "threedsversion_123def987a",
        "authenticationResult": {
            "version": "2.0",
            "status": "Y",
            "redirectUrl": "https://link-the-hosted-challange.example",
            "challengeData": {
                "acsUrl": "https://link-to-the-issuer.acs",
                "base64EncodedChallengeRequest": "Y2hhbGxhbmdlRGF0YQ==",
                "challengeWindowSize": "05"
            },
            "transactionId": "d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4",
            "acsReferenceNumber": "string",
            "acsSignedContent": "string",
            "acsTransactionId": "string",
            "authenticationValue": "YXV0aGVudGljYXRpb25WYWx1ZQ==",
            "cardholderInfo": "string",
            "eci": "05",
            "statusReason": "01",
            "forceChallenge": true,
            "errorDetails": {
                "providerCode": "301",
                "providerMessage": "TRANSACTION_ID_NOT_RECOGNIZED"
            }
        },
        "type": "PAYMENT_TRANSACTION",
        "customerId": "customer_abc123xyz1",
        "shippingAddressId": "address_abc123xyz1",
        "billingAddressId": "address_abc123xyz1",
        "transactionData": {
            "amount": 1000,
            "currency": "EUR",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "risk": {
            "customerAccount": {
                "accountIdentifier": "customer-abc123",
                "creationDate": "2019-07-10",
                "lastChangeDate": "2019-07-10",
                "changeIndicator": "CHANGED_WITH_THIS_TRANSACTION",
                "lastPasswordChangeDate": "2019-07-10",
                "passwordChangeIndicator": "LESS_THAN_THIRTY_DAYS",
                "authenticationMethod": "OWN_CREDENTIALS",
                "authenticationTimestamp": "2019-07-10T15:04:09.722Z",
                "shippingAddressUsageIndicator": "LESS_THAN_THIRTY_DAYS",
                "shippingAddressFirstUsage": "2019-07-10",
                "transactionCountLastDay": 1,
                "transactionCountLastYear": 10,
                "orderCountLast6Months": 5,
                "suspiciousActivity": false,
                "accountEqualsShippingName": true,
                "paymentAccountAgeIndicator": "NO_ACCOUNT",
                "paymentAccountEnrollementDate": "2019-07-10"
            },
            "shippingInfo": {
                "shippingEqualsBillingAddress": true,
                "shippingIndicator": "SHIP_TO_BILLING_ADDRESS",
                "deliveryTime": "SAME_DAY",
                "deliveryEmail": "john@doe.com"
            },
            "orderInfo": {
                "isReorder": false,
                "preOrderIndicator": "MERCHANTDISE_AVAILABLE",
                "preOrderDate": "2019-07-10",
                "orderType": "01"
            }
        },
        "browserInfoId": "browserinfo_123abc456d",
        "async": {
            "notificationUrl": "https://my.notification.url",
            "successUrl": "https://my.success.url",
            "failureUrl": "https://my.failure.url"
        },
        "forceChallenge": true,
        "cardAcquirerRoutingTo": "concardis",
        "correlationId": "e302d01e-0a0e-4556-a8d2-64bd433170bc"
    }

    Get list of all card-check transactions

    GET /creditcard/card-check

    Endpoint to receive a list of available card-check transactions.

    The following parameters can be used as filter.

    • cardCheckId
    • paymentInstrumentId
    • cardCheckStatus
    • cofContactStatus
    • threeDsAuthenticationId
    • createdAt

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    Get list of all card-check transactions

    var client = new RestClient("https://apitest.payengine.de/v1/creditcard/card-check");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • idstringoptional

        A unique transaction identifier generated by the Payengine.

      • createdAtnumberoptional

        Timestamp when card check was initiated.

      • modifiedAtnumberoptional

        Timestamp when card check was modified.

      • statusstringoptional

        The status of the card check.

      • threeDsAuthenticationIdstringoptional

        Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.

      • cofContractobjectoptional

        The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

        • idstringoptional

          Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

        • typestringoptional

          Credential on file type:

          • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
          • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
          • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
        • channelstringoptional

          The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

        • recurringExpirystring (date)optional

          Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

        • recurringFrequencynumberoptional

          Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

      • errorDetailsobjectoptional

        Object containing error information in case of a FAILURE status.

        • providerCodestringoptional

          Card processor code in case of an error.

        • providerMessagestringoptional

          Card processor message in case of an error.

    200

    {
        "id": "cardcheck_abc123xyz4",
        "createdAt": 1562574062133,
        "modifiedAt": 1562574062133,
        "status": "SUCCESS",
        "threeDsAuthenticationId": "authentication_123abc456x",
        "cofContract": {
            "id": "contract_123abc456x",
            "type": "ONECLICK",
            "channel": "ECOM",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "cardAcquirerRoutingTo": "concardis",
        "errorDetails": {
            "providerCode": "00",
            "providerMessage": "Transaction Approved"
        }
    }

    Get card-check request

    GET /creditcard/card-check/{cardCheckId}

    Endpoint to receive a specific card-check transaction referencing the cardCheckId.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • cardCheckIdstringrequired

      ID of the specific card-check transaction.

    Get card-check request

    var client = new RestClient("https://apitest.payengine.de/v1/creditcard/card-check/%7BcardCheckId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • idstringoptional

        A unique transaction identifier generated by the Payengine.

      • createdAtnumberoptional

        Timestamp when card check was initiated.

      • modifiedAtnumberoptional

        Timestamp when card check was modified.

      • statusstringoptional

        The status of the card check.

      • threeDsAuthenticationIdstringoptional

        Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.

      • cofContractobjectoptional

        The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

        • idstringoptional

          Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

        • typestringoptional

          Credential on file type:

          • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
          • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
          • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
        • channelstringoptional

          The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

        • recurringExpirystring (date)optional

          Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

        • recurringFrequencynumberoptional

          Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

      • cardAcquirerRoutingTostringoptional

        Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

      • errorDetailsobjectoptional

        Object containing error information in case of a FAILURE status.

        • providerCodestringoptional

          Card processor code in case of an error.

        • providerMessagestringoptional

          Card processor message in case of an error.

    • 400Bad request for provided input.optional
      • pathstringoptional
      • timestampnumber (date-time)optional
      • statusnumberoptional
      • messagestringoptional
      • codenumberoptional
      • globalTrackIdstringoptional
    {
        "id": "cardcheck_abc123xyz4",
        "createdAt": 1562574062133,
        "modifiedAt": 1562574062133,
        "status": "SUCCESS",
        "threeDsAuthenticationId": "authentication_123abc456x",
        "cofContract": {
            "id": "contract_123abc456x",
            "type": "ONECLICK",
            "channel": "ECOM",
            "recurringExpiry": "2019-07-10",
            "recurringFrequency": 30
        },
        "cardAcquirerRoutingTo": "concardis",
        "errorDetails": {
            "providerCode": "00",
            "providerMessage": "Transaction Approved"
        }
    }

    Create eDCC offer

    POST /creditcard/edcc

    Service to create an eDCC offer for a given card with 'bin' and 'baseAmount'.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    Create eDCC offer

    var client = new RestClient("https://apitest.payengine.de/v1/creditcard/edcc");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • baseAmountnumber (int)required

      The amount to be converted, as smallest currency unit e.g 100 EUR will be result in amount = 10000

    • binstringrequired

      The 'bin' of the card, with given currency, for which an eDCC offer will be created

    Request body

    {
        "baseAmount": 12345,
        "bin": "411111"
    }

    Responses

    • 200Successful response.optional
      • edccIdstringoptional

        Identifier of the eDCC offer generated by the Payengine

      • edccOfferobjectoptional
        • uuidstringoptional

          An id of the eDCC offer generated by Fexco

        • baseAmountnumber (int)optional

          The base amount to convert

        • exchangeRateobjectoptional
          • uuidstringoptional

            An id of the eDCC offer's exchange rate object generated by Fexco

          • baseCurrencyobjectoptional

            The currency to of the baseAmount

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • ratenumber (float)optional

            The conversion rate used to convert the baseAmount to the foreignCurrency

          • foreignCurrencyobjectoptional

            The currency to convert the baseAmount to

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • marginPercentagenumber (int)optional
          • commissionPercentagenumber (float)optional
          • sourcestringoptional
          • sourceTimestampnumber (date)optional
          • expirynumber (date)optional

            The date time until the eDCC offer is valid

        • foreignAmountnumber (int)optional

          The foreign amount, to which the baseAmount is converted

        • binobjectoptional
          • numberstringoptional

            The 'bin' of the card passed as a parameter

          • currencyobjectoptional

            The currency of the card with the given 'bin'

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • schemeCodenumber (int)optional
      • edccUsageobjectoptional

        Details about the authorizing transaction, in which the eDCC offer is used

        • merchantNamestringoptional

          The ID of the merchant, who created the authorizing transaction, in which the eDCC offer is used

        • transactionIdstringoptional

          The ID of the authorizing transaction, in which the eDCC offer is used

        • cardTypestringoptional

          The brand of the card, used during the authorizing transaction

        • cardNumberstringoptional

          The last four digits of the number of the card, used during the authorizing transaction

        • cardHolderNamestringoptional

          The card holder of the card, used during the authorizing transaction

    200

    {
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "edccOffer": {
            "uuid": "a670ea4f-f390-46d8-9a90-6b1b99115708",
            "baseAmount": 12345,
            "exchangeRate": {
                "uuid": "c853d076-636e-4ea1-86e8-7c2d4e3e24e9",
                "baseCurrency": {
                    "alphaCode": "EUR",
                    "minorUnits": 2,
                    "numericCode": 978
                },
                "rate": 1.1276,
                "foreignCurrency": {
                    "alphaCode": "USD",
                    "minorUnits": 2,
                    "numericCode": 840
                },
                "marginPercentage": 3,
                "commissionPercentage": 0,
                "source": "REUTERS WHOLESALE INTERBANK",
                "sourceTimestamp": 1454061545000,
                "expiry": 1618783200000
            },
            "foreignAmount": 13920,
            "bin": {
                "number": "411111",
                "currency": {
                    "alphaCode": "USD",
                    "minorUnits": 2,
                    "numericCode": 840
                },
                "schemeCode": 1
            }
        },
        "edccUsage": {
            "merchantName": "merchant_vn9fklv2nb",
            "transactionId": "transaction_mfxrtmqkku",
            "cardType": "VISA",
            "cardNumber": "************1111",
            "cardHolderName": "Max Mustermann"
        }
    }

    Get eDCC offer

    GET /creditcard/edcc/{edccId}

    Service to get an eDCC offer for with given ID.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    • edccIdstringrequired

      ID of the eDCC offer.

    Get eDCC offer

    var client = new RestClient("https://apitest.payengine.de/v1/creditcard/edcc/%7BedccId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • edccIdstringoptional

        Identifier of the eDCC offer generated by the Payengine

      • edccOfferobjectoptional
        • uuidstringoptional

          An id of the eDCC offer generated by Fexco

        • baseAmountnumber (int)optional

          The base amount to convert

        • exchangeRateobjectoptional
          • uuidstringoptional

            An id of the eDCC offer's exchange rate object generated by Fexco

          • baseCurrencyobjectoptional

            The currency to of the baseAmount

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • ratenumber (float)optional

            The conversion rate used to convert the baseAmount to the foreignCurrency

          • foreignCurrencyobjectoptional

            The currency to convert the baseAmount to

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • marginPercentagenumber (int)optional
          • commissionPercentagenumber (float)optional
          • sourcestringoptional
          • sourceTimestampnumber (date)optional
          • expirynumber (date)optional

            The date time until the eDCC offer is valid

        • foreignAmountnumber (int)optional

          The foreign amount, to which the baseAmount is converted

        • binobjectoptional
          • numberstringoptional

            The 'bin' of the card passed as a parameter

          • currencyobjectoptional

            The currency of the card with the given 'bin'

            • alphaCodestringoptional

              The string currency code of the currency

            • minorUnitsnumber (int)optional
            • numericCodenumber (int)optional

              The numeric currency code of the currency

          • schemeCodenumber (int)optional
      • edccUsageobjectoptional

        Details about the authorizing transaction, in which the eDCC offer is used

        • merchantNamestringoptional

          The ID of the merchant, who created the authorizing transaction, in which the eDCC offer is used

        • transactionIdstringoptional

          The ID of the authorizing transaction, in which the eDCC offer is used

        • cardTypestringoptional

          The brand of the card, used during the authorizing transaction

        • cardNumberstringoptional

          The last four digits of the number of the card, used during the authorizing transaction

        • cardHolderNamestringoptional

          The card holder of the card, used during the authorizing transaction

    200

    {
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "edccOffer": {
            "uuid": "a670ea4f-f390-46d8-9a90-6b1b99115708",
            "baseAmount": 12345,
            "exchangeRate": {
                "uuid": "c853d076-636e-4ea1-86e8-7c2d4e3e24e9",
                "baseCurrency": {
                    "alphaCode": "EUR",
                    "minorUnits": 2,
                    "numericCode": 978
                },
                "rate": 1.1276,
                "foreignCurrency": {
                    "alphaCode": "USD",
                    "minorUnits": 2,
                    "numericCode": 840
                },
                "marginPercentage": 3,
                "commissionPercentage": 0,
                "source": "REUTERS WHOLESALE INTERBANK",
                "sourceTimestamp": 1454061545000,
                "expiry": 1618783200000
            },
            "foreignAmount": 13920,
            "bin": {
                "number": "411111",
                "currency": {
                    "alphaCode": "USD",
                    "minorUnits": 2,
                    "numericCode": 840
                },
                "schemeCode": 1
            }
        },
        "edccUsage": {
            "merchantName": "merchant_vn9fklv2nb",
            "transactionId": "transaction_mfxrtmqkku",
            "cardType": "VISA",
            "cardNumber": "************1111",
            "cardHolderName": "Max Mustermann"
        }
    }

    Create order intent

    POST /orders

    Endpoint to create an order intent.

    This service will create a new order incl. all order details with status CREATED and returns a corresponding orderId.

    The order intent is required for Payengine widget solutions which need an orderId as an input in order to execute an order at the end of the process.

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    Create order intent

    var client = new RestClient("https://apitest.payengine.de/v1/orders");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/json");
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • initialAmountnumber (int)required

      Amount as smallest currency unit e.g 100 EUR will be result in amount = 10000

    • currencystringrequired

      Currency code according to https://en.wikipedia.org/wiki/ISO_4217

    • asyncobjectrequired

      Async object for asynchronous payment methods like PayPal.

      • successUrlstring (url)required

        In case of a successful order the customer will be redirected to the given URL.

      • failureUrlstring (url)required

        In case of a failed order the customer will be redirected to the given URL.

      • cancelUrlstring (url)required

        In case of a cancellation by the customer, the customer will be redirected to the given URL.

      • confirmUrlstring (url)optional

        Optional - used for PayPal Checkout - the customer will be redirected to the given URL to confirm the payment.

      • notificationsarrayoptional

        Optional notification subscription requests. This enables receiving notification for this order's transactions.

        • notificationUrnstring (url)required

          Callback URN which will receive the contents of the notification. For http listeners, use an URN like https://your-domain-listener/specific-handler. For email listeners, use an URN like mailto:specific-handler@your-domain-listener. For notificationVersion "2.0" See the content to expect in the listener: TransactionContent. For notificationVersion "2.0" 3ds.success see the content to expect in the listener: ThreeDsContent. Notification Service 2.0 is described here: https://docs.payengine.de/notifications/introduction

        • notificationEventarrayoptional

          The list of Version Two event types to which this notification is subscribing.

        • notificationVersionstringoptional

          2.0: has to be submitted

    • transactionTypestringrequired

      The type of the underlying Transaction

    • termsnumber (integer)optional

      A timestamp in milliseconds of the approval of the customer to your terms and conditions. E.g. this is required for RatePAY orders.

    • privacynumber (integer)optional

      A timestamp in milliseconds of the approval of the customer to your privacy policy. E.g. this is required for RatePAY orders.

    • merchantOrderIdstringoptional

      The order id from your system/shop for Creditcards only 30 alphanumeric characters.

    • descriptionstringoptional

      The description from your system/shop of this order.

    • statementDescriptionstringoptional

      The statement description from your system/shop of this order.

    • basketarrayoptional

      The basket of your order. (optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

      • namestringoptional

        The articles name used in your shop.

      • articleNumberstringoptional

        The articles number used in your shop.

      • totalPricenumber (int)optional

        The total price for this item excluding taxes. The total amount should be given as smallest currency unit.

      • totalPriceWithTaxnumber (int)optional

        The total price for this item including taxes. The total amount should be given as smallest currency unit. If the item is of type discount, the value must be negative: min -999999999999999998, max -1.

      • unitPricenumber (int)optional

        The unit price for this item excluding taxes. The unit amount should be given as smallest currency unit.

      • unitPriceWithTaxnumber (int)optional

        The unit price for this item including taxes. The unit amount should be given as smallest currency unit.

      • taxnumber (float)optional

        The tax rate for the corresponding item. Will be returned in float format only if scale part contains no trailing zeros. 10.99 -> 10.99 10.90 -> 10.9 10.00 -> 10 10.0 -> 10 10 -> 10

      • quantitynumber (int)optional

        The quantity for this item.

      • discountnumber (int)optional

        item specific discount

      • articleTypestringoptional

        This is the type of the article. Required for Klarna and optional for all other payment methods.

    • customerstringoptional

      The customer id which will be used to process this order.

    • personastringoptional

      The persona id which will be used to process this order. note: the persona must be a persona from the given customer.

    • billingAddressstringoptional

      The address id used as billing address for this order.

    • shippingAddressstringoptional

      The address id used as shipping address for this order.

    • ipAddressstringoptional

      The IP address used to submit the order. (Optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

    • channelstringoptional

      The channel determine the kind of origin for this order. (optional, mandatory for creditcard, ratepay-invoice, ratepay-directdebit and ratepay-installment)

    • sourcestringoptional

      The source is a form free descriptor of the origin.

    • allowedProductsarrayoptional

      A List of all valid products for this order.

    • localestringoptional

      Language tag consisting of a two-letter language code combined with a two-letter country code according to RFC 1766. Examples: en-US, en-GB. Only for PayPal, Union Pay and WeChat Pay.

    • riskobjectoptional

      An object containing information relevant for risk analysis on the issuere side.

      • customerAccountobjectoptional

        An object containing information about the customer account with the merchant.

        • accountIdentifierstringoptional

          The account identifier at the merchant side.

        • creationDatestring (date)optional

          The date when the customer opened the account with the merchant.

        • lastChangeDatestring (date)optional

          The date when the customer account with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

        • changeIndicatorstringoptional

          Length of the time since the customer account information with the merchant was last changed, including billing or shipping addres, new payment account or new user(s) added.

        • lastPasswordChangeDatestring (date)optional

          The date when the customer account with the merchant had a password change or account reset.

        • passwordChangeIndicatorstringoptional

          Length of the time since the customer account information with the merchant had a password change or account reset.

        • authenticationMethodstringoptional

          Mechanism used by the customer to authenticate to the merchant account.

        • authenticationTimestampstring (date-time)optional

          Date and time in UTC of the customer authentication to the merchant account.

        • shippingAddressUsageIndicatorstringoptional

          Indicates when the shipping address used for this transaction was first used with the merchant account.

        • shippingAddressFirstUsagestring (date)optional

          Date when the shipping address used for this transaction was first used with the merchant.

        • transactionCountLastDaynumberoptional

          Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.

        • transactionCountLastYearnumberoptional

          Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.

        • orderCountLast6Monthsnumberoptional

          Number of purchases with this cardholder account during the previous six months.

        • suspiciousActivitybooleanoptional

          Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.

        • accountEqualsShippingNamebooleanoptional

          Indicates if the customer name on the account is identical to the shipping name used for this transaction.

        • paymentAccountAgeIndicatorstringoptional

          Indicates the length of time that the payment account was enrolled in the customer account with the merchant.

        • paymentAccountEnrollementDatestring (date)optional

          Date that the payment account was enrolled in the customer account with the merchant.

      • shippingInfoobjectoptional

        object containing information about the shipping details for this transaction.

        • shippingEqualsBillingAddressbooleanoptional

          Flag if the shipping address equals the billing address.

        • shippingIndicatorstringoptional

          Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator that most accurately describes the customer's specific transaction. If one or more items are included in the sale, use the shipping indicator for the physical goods, or if all digital goods, use the indicator that describes the most expensive item.

        • deliveryTimestringoptional

          Indicates the merchandise delivery timeframe.

        • deliveryEmailstringoptional

          For electronic delivery, the email address to which the merchandise was delivered.

      • orderInfoobjectoptional

        object containing order information relevant for risk evaluation

        • isReorderbooleanoptional

          Indicates whether the cardholder is reordering previously purchased merchandise.

        • preOrderIndicatorstringoptional

          Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

        • preOrderDatestring (date)optional

          For a pre-ordered purchase, the expected date that the merchandise will be available.

        • orderTypestringoptional

          Identifies the type of transaction being authenticated. The values are derived from ISO 8583. If this value is not provided, a default value of 01 is used. Accepted values are: 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan

    Request body

    {
        "initialAmount": 0,
        "currency": "str",
        "async": {
            "successUrl": "string",
            "failureUrl": "string",
            "cancelUrl": "string",
            "confirmUrl": "string",
            "notifications": [
                {
                    "notificationUrn": "string",
                    "notificationEvent": [
                        "string"
                    ],
                    "notificationVersion": "string"
                }
            ]
        },
        "transactionType": "PREAUTH",
        "terms": 0,
        "privacy": 0,
        "merchantOrderId": "string",
        "description": "string",
        "statementDescription": "string",
        "basket": [
            {
                "name": "string",
                "articleNumber": "string",
                "totalPrice": -1000000000000000000,
                "totalPriceWithTax": -1000000000000000000,
                "unitPrice": -1000000000000000000,
                "unitPriceWithTax": -1000000000000000000,
                "tax": 100,
                "quantity": 1,
                "discount": -1000000000000000000,
                "articleType": "physical"
            }
        ],
        "customer": "string",
        "persona": "string",
        "billingAddress": "string",
        "shippingAddress": "string",
        "ipAddress": "string",
        "channel": "MOTO",
        "source": "string",
        "allowedProducts": [
            "creditcard"
        ],
        "locale": "string",
        "risk": {
            "customerAccount": {
                "accountIdentifier": "customer-abc123",
                "creationDate": "2019-07-10",
                "lastChangeDate": "2019-07-10",
                "changeIndicator": "CHANGED_WITH_THIS_TRANSACTION",
                "lastPasswordChangeDate": "2019-07-10",
                "passwordChangeIndicator": "LESS_THAN_THIRTY_DAYS",
                "authenticationMethod": "OWN_CREDENTIALS",
                "authenticationTimestamp": "2019-07-10T15:04:09.722Z",
                "shippingAddressUsageIndicator": "LESS_THAN_THIRTY_DAYS",
                "shippingAddressFirstUsage": "2019-07-10",
                "transactionCountLastDay": 1,
                "transactionCountLastYear": 10,
                "orderCountLast6Months": 5,
                "suspiciousActivity": false,
                "accountEqualsShippingName": true,
                "paymentAccountAgeIndicator": "NO_ACCOUNT",
                "paymentAccountEnrollementDate": "2019-07-10"
            },
            "shippingInfo": {
                "shippingEqualsBillingAddress": true,
                "shippingIndicator": "SHIP_TO_BILLING_ADDRESS",
                "deliveryTime": "SAME_DAY",
                "deliveryEmail": "john@doe.com"
            },
            "orderInfo": {
                "isReorder": false,
                "preOrderIndicator": "MERCHANTDISE_AVAILABLE",
                "preOrderDate": "2019-07-10",
                "orderType": "01"
            }
        }
    }

    Responses

    • 200Successful response.optional
      • orderIdstringrequired

        The order id from payengine.

      • initialAmountnumber (int)required

        The initial amount given to create this order.

      • preauthorizedAmountnumber (int)required

        The amount which has been authorized.

      • capturedAmountnumber (int)required

        The amount which has been captured.

      • refundedAmountnumber (int)required

        The amount which has been refunded.

      • canceledAmountnumber (int)required

        The amount which has been cancelled.

      • currencystringrequired

        Currency code according to https://en.wikipedia.org/wiki/ISO_4217

      • transactionsarrayrequired

        A list of all underlying transactions.

        • typestringoptional

          the type of the transaction

        • transactionIdstringrequired

          The identifier of the transaction. Created by payengine

        • statusstringrequired

          The current status of the transaction. The status can be one of the following. CREATED, PENDING, IN_PROGRESS, OK, SUCCESS, FAILURE, DECLINED, ABORTED, EXPIRED

        • initialAmountnumber (int)required

          The initial amount given to create this transaction.

        • currencystringrequired

          Currency code according to https://en.wikipedia.org/wiki/ISO_4217

        • descriptionstringrequired

          The description from your system/shop of this transaction.

        • createdAtnumber (date-time)required

          This timestamp indicates the creation of this transaction.

        • modifiedAtnumber (date-time)required

          This timestamp indicates the last modification of this transaction.

        • orderstringrequired

          The identifier of the connected order.

        • transactionsarrayrequired

          A list of underlying transactions.

        • parentTransactionstringrequired

          The identifier of the parent transaction.

        • descriptorstringoptional

          Identifier which holds the orderId

        • capturedAmountnumber (int)required

          The amount which has been captured.

        • refundedAmountnumber (int)required

          The amount which has been refunded.

        • canceledAmountnumber (int)required

          The amount which has been cancelled.

        • challangeobjectoptional

          Contains payment method specifc meta data. For prepayment TAN instructions.

          • titlestringoptional

            The title of the prepayment TAN challange (can be displayed in the TAN form)

          • labelstringoptional

            The label of the prepayment tan challange (can be displayed in the TAN form)

          • formatstringoptional

            The TAN format for prepayment (iTAN, photoTAN, etc.)

          • datastringoptional

            Optional data field for prepayment is needed for some TAN formats e.g. photoTAN

        • trackingarrayoptional

          specific parameter for all payment methods, array of object of type Tracking

          • trackingIdstringoptional
          • providerstringoptional
        • metaobjectoptional

          Contains payment method specifc meta data. For prepayment TAN instructions.

          • tanSentbooleanoptional

            Flag which indicates if the TAN was sent to the bank

          • tanSchemastringoptional

            The TAN schema which was used to finalize a online bank transfer based refund

      • statusstringrequired

        The current status of the order It can be one of the following CREATED, OPEN, CLOSED A order remains open until the initial amount has been refunded or cancelled.

      • channelstringrequired

        The channel determine the kind of origin for this order. (optional, mandatory for creditcard, ratepay-invoice, ratepay-directdebit and ratepay-installment)

      • createdAtnumber (date-time)required

        This timestamp indicates the creation of this order.

      • modifiedAtnumber (date-time)required

        This timestamp indicates the last modification of this order.

      • termsnumber (integer)optional

        A timestamp in milliseconds of the approval of the customer to your terms and conditions. E.g. this is required for RatePAY orders.

      • privacynumber (integer)optional

        A timestamp in milliseconds of the approval of the customer to your privacy policy. E.g. this is required for RatePAY orders.

      • merchantOrderIdstringoptional

        The order id from your system/shop for Creditcards only 30 alphanumeric characters.

      • paymentProviderTransactionIdstringoptional

        The order id from the payment provider.

      • descriptionstringoptional

        The description from your system/shop of this order.

      • statementDescriptionstringoptional

        The statement description from your system/shop of this order.

      • basketarrayoptional

        The basket of your order. (optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

        • namestringoptional

          The articles name used in your shop.

        • articleNumberstringoptional

          The articles number used in your shop.

        • totalPricenumber (int)optional

          The total price for this item excluding taxes. The total amount should be given as smallest currency unit.

        • totalPriceWithTaxnumber (int)optional

          The total price for this item including taxes. The total amount should be given as smallest currency unit. If the item is of type discount, the value must be negative: min -999999999999999998, max -1.

        • unitPricenumber (int)optional

          The unit price for this item excluding taxes. The unit amount should be given as smallest currency unit.

        • unitPriceWithTaxnumber (int)optional

          The unit price for this item including taxes. The unit amount should be given as smallest currency unit.

        • taxnumber (float)optional

          The tax rate for the corresponding item. Will be returned in float format only if scale part contains no trailing zeros. 10.99 -> 10.99 10.90 -> 10.9 10.00 -> 10 10.0 -> 10 10 -> 10

        • quantitynumber (int)optional

          The quantity for this item.

        • discountnumber (int)optional

          item specific discount

        • articleTypestringoptional

          This is the type of the article. Required for Klarna and optional for all other payment methods.

      • customerobjectoptional
        • customerIdstringrequired

          The identifier of the customer. Created by payengine

        • emailstring (email)required

          The customers email address. unique.

        • merchantCustomerIdstringoptional

          The identifier of the customer. Created by you.

        • addressesarrayoptional

          A list of all underlying addresses which are connected to the customer.

          • addressIdstringrequired

            The identifier of the address. Created by payengine

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this address.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this address.

          • firstNamestringoptional

            The firstname of this address. limited to 35 characters!

          • lastNamestringoptional

            The lastname of this address. limited to 35 characters!

          • streetstringoptional

            The street of this address.

          • houseNumberstringoptional

            The housenumber of the street.

          • citystringoptional

            The city of the address.

          • zipstringoptional

            The zip of the address.

          • countrystringoptional

            The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

          • statestringoptional

            The state of the address.

          • phonestringoptional

            The phone of the address. limited to 16 characters!

          • faxstringoptional

            The fax of the address. limited to 16 characters!

          • mobilestringoptional

            The mobile of the address. limited to 16 characters!

          • titlestringoptional

            The title of the address.

          • additionalDetailsstringoptional

            Additional details for this address. This is a form free descriptor.

        • personasarrayoptional

          A list of all underlying personas which are connected to the customer.

          • personaIdstringrequired

            The identifier of the persona. Created by payengine

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this persona.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this persona.

          • firstNamestringoptional

            The firstname of this persona. limited to 35 characters!

          • lastNamestringoptional

            The lastname of this persona. limited to 35 characters!

          • phonestringoptional

            The phone of the persona. limited to 16 characters!

          • mobilestringoptional

            The mobile of the persona. limited to 16 characters!

          • faxstringoptional

            The fax of the persona. limited to 16 characters!

          • birthdaynumber (date-time)optional

            The birthday of the persona. Format as milliseconds since epoch representing UTC Date.

          • genderstringoptional

            The gender of the persona.

          • titlestringoptional

            The title of the persona.

        • paymentInstrumentsarrayoptional

          A list of all underlying paymentinstruments which are connected to the customer.

          • paymentInstrumentIdstringrequired

            The identifier of the paymentinstrument. Created by payengine

          • merchantPaymentInstrumentIdstringrequired

            The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

          • originstringrequired

            The product used to create this order. (mandatory)

          • typestringrequired

            the type of the payment instrument

          • recurringbooleanrequired

            This flag indicates if this paymentinstrument can be used for recurring payments.

          • createdAtintegeroptional

            Timestamp when it was created

          • modifiedAtintegeroptional

            Timestamp when it was last updated

          • attributesobjectrequired

            Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

            • cofContractsarrayoptional

              For CreditCard only

              • idstringoptional

                Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

              • typestringoptional

                Credential on file type:

                • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
                • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
                • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
              • channelstringoptional

                The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

              • recurringExpirystring (date)optional

                Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

              • recurringFrequencynumberoptional

                Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

            • customerRelationUuidstringoptional

              For TWINT only. Recognition of a returning customer.

      • personaobjectoptional
        • personaIdstringrequired

          The identifier of the persona. Created by payengine

        • createdAtnumber (date-time)required

          This timestamp indicates the creation of this persona.

        • modifiedAtnumber (date-time)required

          This timestamp indicates the last modification of this persona.

        • firstNamestringoptional

          The firstname of this persona. limited to 35 characters!

        • lastNamestringoptional

          The lastname of this persona. limited to 35 characters!

        • phonestringoptional

          The phone of the persona. limited to 16 characters!

        • mobilestringoptional

          The mobile of the persona. limited to 16 characters!

        • faxstringoptional

          The fax of the persona. limited to 16 characters!

        • birthdaynumber (date-time)optional

          The birthday of the persona. Format as milliseconds since epoch representing UTC Date.

        • genderstringoptional

          The gender of the persona.

        • titlestringoptional

          The title of the persona.

      • billingAddressobjectoptional
        • addressIdstringrequired

          The identifier of the address. Created by payengine

        • createdAtnumber (date-time)required

          This timestamp indicates the creation of this address.

        • modifiedAtnumber (date-time)required

          This timestamp indicates the last modification of this address.

        • firstNamestringoptional

          The firstname of this address. limited to 35 characters!

        • lastNamestringoptional

          The lastname of this address. limited to 35 characters!

        • streetstringoptional

          The street of this address.

        • houseNumberstringoptional

          The housenumber of the street.

        • citystringoptional

          The city of the address.

        • zipstringoptional

          The zip of the address.

        • countrystringoptional

          The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

        • statestringoptional

          The state of the address.

        • phonestringoptional

          The phone of the address. limited to 16 characters!

        • faxstringoptional

          The fax of the address. limited to 16 characters!

        • mobilestringoptional

          The mobile of the address. limited to 16 characters!

        • titlestringoptional

          The title of the address.

        • additionalDetailsstringoptional

          Additional details for this address. This is a form free descriptor.

      • shippingAddressobjectoptional
        • addressIdstringrequired

          The identifier of the address. Created by payengine

        • createdAtnumber (date-time)required

          This timestamp indicates the creation of this address.

        • modifiedAtnumber (date-time)required

          This timestamp indicates the last modification of this address.

        • firstNamestringoptional

          The firstname of this address. limited to 35 characters!

        • lastNamestringoptional

          The lastname of this address. limited to 35 characters!

        • streetstringoptional

          The street of this address.

        • houseNumberstringoptional

          The housenumber of the street.

        • citystringoptional

          The city of the address.

        • zipstringoptional

          The zip of the address.

        • countrystringoptional

          The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

        • statestringoptional

          The state of the address.

        • phonestringoptional

          The phone of the address. limited to 16 characters!

        • faxstringoptional

          The fax of the address. limited to 16 characters!

        • mobilestringoptional

          The mobile of the address. limited to 16 characters!

        • titlestringoptional

          The title of the address.

        • additionalDetailsstringoptional

          Additional details for this address. This is a form free descriptor.

      • ipAddressstringoptional

        The IP address used to submit the order. (Optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

      • paymentInstrumentobjectoptional

        The paymentinstrument which has been used to process this order. note: If no paymentinstrument has been submitted, one has been created with your submitted data.

        • paymentInstrumentIdstringrequired

          The identifier of the paymentinstrument. Created by payengine

        • merchantPaymentInstrumentIdstringrequired

          The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

        • originstringrequired

          The product used to create this order. (mandatory)

        • typestringrequired

          the type of the payment instrument

        • recurringbooleanrequired

          This flag indicates if this paymentinstrument can be used for recurring payments.

        • createdAtintegeroptional

          Timestamp when it was created

        • modifiedAtintegeroptional

          Timestamp when it was last updated

        • attributesobjectrequired

          Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

          • cofContractsarrayoptional

            For CreditCard only

            • idstringoptional

              Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

            • typestringoptional

              Credential on file type:

              • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
              • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
              • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
            • channelstringoptional

              The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

            • recurringExpirystring (date)optional

              Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

            • recurringFrequencynumberoptional

              Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

          • customerRelationUuidstringoptional

            For TWINT only. Recognition of a returning customer.

      • redirectUrlstring (url)optional

        The URL which the customer needs to be redirected to.

      • sourcestringoptional

        The source of the order.

      • productstringoptional

        The product used to create this order. (mandatory)

      • allowedProductsarrayoptional

        A List of all valid products for this order.

      • settledbooleanoptional

        A flag which indicates if this order has been settled or not.

      • settlementDatestring (date-time)optional

        The date of the settlement.

      • transactionTypestringoptional

        The type of the underlying Transaction

      • deviceIdentobjectoptional
        • tokenstringoptional
        • fraudscorenumberoptional
        • fraudscoreRawnumberoptional
        • ruleScoresstringoptional
        • fraudscoreRulematchesstringoptional
        • citystringoptional
        • ipstringoptional
        • regioncodestringoptional
        • continentstringoptional
        • countrynamestringoptional
        • regionnamestringoptional
        • countrycodestringoptional
        • latitudenumberoptional
        • longitudenumberoptional
        • exactidCreatedstringoptional
        • smartidCreatedstringoptional
        • exactidstringoptional
        • confidencelevelnumberoptional
        • smartidstringoptional
        • confidencelevelhistorynumberoptional
        • verifiedOsstringoptional
        • deviceTypestringoptional
        • languagesstringoptional
      • metaobjectoptional
        • deferredbooleanoptional

          Indicates if the order is marked as deferred. Available only for paypal.

        • emailSubjectstringoptional

          Available only for paypal. The subject line of the email that PayPal sends when the transaction is completed.

        • receiverTypestringoptional

          Available only for paypal. Indicates how you identify the recipients of payments in this call to MassPay.

        • receiverEmailstringoptional

          Available only for paypal. Email address of recipient.

        • receiverPhonestringoptional

          Available only for paypal. Mobile phone number of recipient.

        • receiverIdstringoptional

          Available only for paypal. Unique PayPal customer account number.

        • preferredLanguagestringoptional

          Available only for RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay.

        • mobileViewbooleanoptional

          Available only for Alipay.

        • qrCodestringoptional

          Available only for TWINT. Image of the pairing token as a QR code (PNG image in base-64 encoding).

        • tokenstringoptional

          Available only for TWINT. Numeric token to establish the pairing between the customer and cash register.

        • cofContractobjectoptional

          The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

          • idstringoptional

            Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

          • typestringoptional

            Credential on file type:

            • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
            • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
            • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
          • channelstringoptional

            The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

          • recurringExpirystring (date)optional

            Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

          • recurringFrequencynumberoptional

            Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

        • externalCofDataobjectoptional
          • typestringrequired

            The type of the credential on file usage.

            • UNSCHEDULED - The payment credentials can be used for merchant initiated unscheduled orders.
            • SCHEDULED - The payment credentials can be used for merchant initiated scheduled orders.
          • initialSchemeTraceIdstringoptional

            The initial Trace ID that was used for the MIT (merchant initiated transaction) mandate setup. This reference will be used by the card schemes to trace back the strong customer authentication that was provided with the initial CIT (cardholder initiated transaction) of the credential on file setup. The value should only be used if the handling of the CIT was done externally outside of the Payengine. Mandatory for subsequent MIT transactions.

            If no schemeTraceId is available, the payengine allows this field to be null, initially. The response meta will contain a new 'schemeTraceId' provided by the credit card scheme which is to be supplied in subsequent order requests in this property.

        • schemeTraceIdstringoptional

          Scheme Trace ID or transaction reference returned by the card scheme for each authorization. This value can be used in subsequent MIT payments if the credential on file handling is not done by the Payengine but externally. See 'externalCofData.initialSchemeTraceId' description.

        • threeDsDataobjectoptional
          • authenticationResultobjectoptional

            Object containing the result of the 3DS authentication transaction (final results will be available only in case of frictionless flow)

            • versionstringoptional

              Parameter indicating the version of the 3DS

            • statusstringoptional

              Indicates whether a transaction qualifies as an authenticated transaction. Y = authentication verificationsuccessful A = authentication attempted; not authenticated, but a proof of attempted authentication is provided C = challenge required; additional SCA authentication is required U = authentication could not be performed; technical or other problem R = authentication rejected; issuer is rejecting N = not authenticated; transaction denied

            • redirectUrlstringoptional

              Conditional - present in case of 3DS 1.0 and challenge flow for 3DS 2.0 redirect URL leading to hosted page by Payengine used for Cardholder authentication (main flow for 3DS 1.0 and fallback flow in case of challenge for 3DS 2.0)

            • challengeDataobjectoptional

              Conditional - information available in case of CHALLENGE status, needed for building the challenge iFrame.

              • acsUrlstringoptional

                Fully qualified URL of the ACS in case the authentication response message indicates that further cardholder interaction is required to complete the authentication. relevant for 3DS 2.0 only

              • base64EncodedChallengeRequeststringoptional

                Base64-encoded Challenge Request object in case the authentication response message indicates that further Cardholder interaction is required to complete the authentication. (3DS 2.0)

              • challengeWindowSizestringoptional

                Dimensions of the challenge iframe window in which the challenge page will be displayed to the Cardholder. This value should match the provided size in the browserInfo call. EMVCo assigned window size. '01' -> 250px x 400px, '02' -> 390px x 400px, '03' -> 500px x 600px, '04' -> 600px x 400px, '05' -> Full screen, or full container content relevant for 3DS 2.0 only

            • transactionIdstringoptional

              The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID

            • acsReferenceNumberstringoptional

              Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. Set by the EMVCo Secretariat.

            • acsSignedContentstringoptional

              Contains the JWS object (represented as a string) created by the ACS for the ARes message. The body of JWS object (represented as a string) will contain the following data elements as defined • ACS URL • ACS Ephemeral Public Key (QT) • SDK Ephemeral Public Key (QC)

            • acsTransactionIdstringoptional

              Universally Unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements.

            • authenticationValuestringoptional

              The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard

            • cardholderInfostringoptional

              Statement about the result of the 3DS authentication.

            • ecistringoptional

              The Electronic Commerce Indicator (ECI) provided by the ACS or DS to indicate the results of the attempt to authenticate the cardholder. The ECI values might differ depending on the card scheme. For all fully authenticated or authentication attempted transactions the liability will be shifted to the card issuer. Mastercard 00 - fully authenticated 01 - authentication attempted 02 - no authentication available 07 - fully authenticated*1 All other card schemes 05 - fully authenticated 06 - authentication attempted 07 - no authentication available *1 - Mastercard distinguishes between fully authenticated recurring payments (flagged with ECI 07) and all other fully authenticated transactions (flagged with ECI 00).

            • statusReasonstringoptional

              Reason why the authenticationResult.status field has the specified value. 01 = Card authentication failed 02 = Unknown Device 03 = Unsupported Device 04 = Exceeds authentication frequency limit 05 = Expired card 06 = Invalid card number 07 = Invalid transaction 08 = No Card record 09 = Security failure 10 = Stolen card 11 = Suspected fraud 12 = Transaction not permitted to cardholder 13 = Cardholder not enrolled in service 14 = Transaction timed out at the ACS 15 = Low confidence 16 = Medium confidence 17 = High confidence 18 = Very High confidence 19 = Exceeds ACS maximum challenges 20 = Non-Payment transaction not supported 21 = 3RI transaction not supported 22 = ACS technical issue 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor 24 = 3DS Requestor Decoupled Max Expiry Time exceeded 25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt 26 = Authentication attempted but not performed by the cardholder 27–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use

            • forceChallengebooleanoptional

              Flag to force challenge for 3ds v2

            • errorDetailsobjectoptional

              Object containing error information in case of error.

              • providerCodestringoptional

                Original error code from the 3DS server or mpi

              • providerMessagestringoptional

                Original error message from the 3DS server or mpi

        • edccDataobjectoptional

          Details about the eDCC offer used in the order

          • edccIdstringoptional

            The ID of the eDCC offer to be used for currency conversion

          • foreignAmountnumber (int)optional

            The foreign amount, to which the baseAmount is converted

          • marginPercentagenumber (int)optional
          • ratenumber (float)optional

            The conversion rate used to convert the baseAmount to the foreignCurrency

          • baseCurrencystringoptional

            The string currency code of the base currency

          • foreignCurrencystringoptional

            The string currency code of the foreign currency

        • cardAcquirerRoutingTostringoptional

          Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

        • instantbooleanoptional

          Indicator if the credit should be instant e.g. visa oct

      • lastOperationstringoptional

        A combined field of the last executed transaction and the status of the transaction. "TRANSACTION_<TRANSACTION_TYPE>_<TRANSACTION_STATUS>"

    200

    {
        "orderId": "string",
        "initialAmount": 1,
        "preauthorizedAmount": 1,
        "capturedAmount": 1,
        "refundedAmount": 1,
        "canceledAmount": 1,
        "currency": "str",
        "transactions": [
            {
                "type": "PREAUTH",
                "transactionId": "string",
                "status": "CREATED",
                "initialAmount": 1,
                "currency": "str",
                "description": "string",
                "createdAt": 0,
                "modifiedAt": 0,
                "order": "string",
                "transactions": [
                    "string"
                ],
                "parentTransaction": "string",
                "descriptor": "string",
                "capturedAmount": 1,
                "refundedAmount": 1,
                "canceledAmount": 1,
                "challange": {
                    "title": "string",
                    "label": "string",
                    "format": "string",
                    "data": "string"
                },
                "tracking": [
                    {
                        "trackingId": "string",
                        "provider": "DPD"
                    }
                ],
                "meta": {
                    "tanSent": true,
                    "tanSchema": "string"
                }
            }
        ],
        "status": "CREATED",
        "channel": "MOTO",
        "createdAt": 0,
        "modifiedAt": 0,
        "terms": 0,
        "privacy": 0,
        "merchantOrderId": "string",
        "paymentProviderTransactionId": "string",
        "description": "string",
        "statementDescription": "string",
        "basket": [
            {
                "name": "string",
                "articleNumber": "string",
                "totalPrice": -1000000000000000000,
                "totalPriceWithTax": -1000000000000000000,
                "unitPrice": -1000000000000000000,
                "unitPriceWithTax": -1000000000000000000,
                "tax": 100,
                "quantity": 1,
                "discount": -1000000000000000000,
                "articleType": "physical"
            }
        ],
        "customer": {
            "customerId": "string",
            "email": "user@example.com",
            "merchantCustomerId": "string",
            "addresses": [
                {
                    "addressId": "string",
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "firstName": "string",
                    "lastName": "string",
                    "street": "string",
                    "houseNumber": "string",
                    "city": "string",
                    "zip": "string",
                    "country": "st",
                    "state": "string",
                    "phone": "string",
                    "fax": "string",
                    "mobile": "string",
                    "title": "string",
                    "additionalDetails": "string"
                }
            ],
            "personas": [
                {
                    "personaId": "string",
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "firstName": "string",
                    "lastName": "string",
                    "phone": "string",
                    "mobile": "string",
                    "fax": "string",
                    "birthday": 0,
                    "gender": "MALE",
                    "title": "string"
                }
            ],
            "paymentInstruments": [
                {
                    "paymentInstrumentId": "string",
                    "merchantPaymentInstrumentId": "string",
                    "origin": "creditcard",
                    "type": "sepa",
                    "recurring": true,
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "attributes": {
                        "cofContracts": [
                            {
                                "id": "contract_123abc456x",
                                "type": "ONECLICK",
                                "channel": "ECOM",
                                "recurringExpiry": "2019-07-10",
                                "recurringFrequency": 30
                            }
                        ],
                        "customerRelationUuid": "string"
                    }
                }
            ]
        },
        "persona": {
            "personaId": "string",
            "createdAt": 0,
            "modifiedAt": 0,
            "firstName": "string",
            "lastName": "string",
            "phone": "string",
            "mobile": "string",
            "fax": "string",
            "birthday": 0,
            "gender": "MALE",
            "title": "string"
        },
        "billingAddress": {
            "addressId": "string",
            "createdAt": 0,
            "modifiedAt": 0,
            "firstName": "string",
            "lastName": "string",
            "street": "string",
            "houseNumber": "string",
            "city": "string",
            "zip": "string",
            "country": "st",
            "state": "string",
            "phone": "string",
            "fax": "string",
            "mobile": "string",
            "title": "string",
            "additionalDetails": "string"
        },
        "shippingAddress": {
            "addressId": "string",
            "createdAt": 0,
            "modifiedAt": 0,
            "firstName": "string",
            "lastName": "string",
            "street": "string",
            "houseNumber": "string",
            "city": "string",
            "zip": "string",
            "country": "st",
            "state": "string",
            "phone": "string",
            "fax": "string",
            "mobile": "string",
            "title": "string",
            "additionalDetails": "string"
        },
        "ipAddress": "string",
        "paymentInstrument": {
            "paymentInstrumentId": "string",
            "merchantPaymentInstrumentId": "string",
            "origin": "creditcard",
            "type": "sepa",
            "recurring": true,
            "createdAt": 0,
            "modifiedAt": 0,
            "attributes": {
                "cofContracts": [
                    {
                        "id": "contract_123abc456x",
                        "type": "ONECLICK",
                        "channel": "ECOM",
                        "recurringExpiry": "2019-07-10",
                        "recurringFrequency": 30
                    }
                ],
                "customerRelationUuid": "string"
            }
        },
        "redirectUrl": "string",
        "source": "string",
        "product": "creditcard",
        "allowedProducts": [
            "creditcard"
        ],
        "settled": true,
        "settlementDate": "2019-08-24T14:15:22Z",
        "transactionType": "PREAUTH",
        "deviceIdent": {
            "token": "string",
            "fraudscore": 0,
            "fraudscoreRaw": 0,
            "ruleScores": "string",
            "fraudscoreRulematches": "string",
            "city": "string",
            "ip": "string",
            "regioncode": "string",
            "continent": "string",
            "countryname": "string",
            "regionname": "string",
            "countrycode": "string",
            "latitude": 0,
            "longitude": 0,
            "exactidCreated": "string",
            "smartidCreated": "string",
            "exactid": "string",
            "confidencelevel": 0,
            "smartid": "string",
            "confidencelevelhistory": 0,
            "verifiedOs": "string",
            "deviceType": "string",
            "languages": "string"
        },
        "meta": {
            "deferred": true,
            "emailSubject": "string",
            "receiverType": "string",
            "receiverEmail": "string",
            "receiverPhone": "string",
            "receiverId": "string",
            "preferredLanguage": "string",
            "mobileView": true,
            "qrCode": "string",
            "token": "string",
            "cofContract": {
                "id": "contract_123abc456x",
                "type": "ONECLICK",
                "channel": "ECOM",
                "recurringExpiry": "2019-07-10",
                "recurringFrequency": 30
            },
            "externalCofData": {
                "type": "UNSCHEDULED",
                "initialSchemeTraceId": "123456789012345"
            },
            "schemeTraceId": "123456789012345",
            "threeDsData": {
                "authenticationResult": {
                    "version": "2.0",
                    "status": "Y",
                    "redirectUrl": "https://link-the-hosted-challange.example",
                    "challengeData": {
                        "acsUrl": "https://link-to-the-issuer.acs",
                        "base64EncodedChallengeRequest": "Y2hhbGxhbmdlRGF0YQ==",
                        "challengeWindowSize": "05"
                    },
                    "transactionId": "d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4",
                    "acsReferenceNumber": "string",
                    "acsSignedContent": "string",
                    "acsTransactionId": "string",
                    "authenticationValue": "YXV0aGVudGljYXRpb25WYWx1ZQ==",
                    "cardholderInfo": "string",
                    "eci": "05",
                    "statusReason": "01",
                    "forceChallenge": true,
                    "errorDetails": {
                        "providerCode": "301",
                        "providerMessage": "TRANSACTION_ID_NOT_RECOGNIZED"
                    }
                }
            },
            "edccData": {
                "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
                "foreignAmount": 13920,
                "marginPercentage": 3,
                "rate": 1.1276,
                "baseCurrency": "EUR",
                "foreignCurrency": "USD"
            },
            "cardAcquirerRoutingTo": "concardis",
            "instant": true
        },
        "lastOperation": "TRANSACTION_PREAUTH_OK"
    }

    Get list of orders

    GET /orders

    Endpoint to receive a list of available orders.

    The following parameters can be used as filter.

    • terms
    • privacy
    • orderId
    • merchantOrderId
    • paymentProviderTransactionId
    • initialAmount
    • currency
    • customerId
    • ipAddress
    • status
    • channel
    • source
    • product
    • settled
    • settlementDate
    • createdAt
    • modifiedAt
    • lastOperation
    • email

    The following parameters can be used as a range filter.

    Dates:

    • terms
    • privacy
    • settlementDate
    • createdAt
    • modifiedAt

    Numbers:

    • initialAmount

    Parameters

    • Authorizationstringrequired

      Authorization for all server to server API calls. The following syntax must be used in the 'Authorization' header :

      Authorization: Basic base64(merchantId:apiKey)

    Get list of orders

    var client = new RestClient("https://apitest.payengine.de/v1/orders");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successful response.optional
      • elementsarrayrequired

        A list of orders.

        • orderIdstringrequired

          The order id from payengine.

        • initialAmountnumber (int)required

          The initial amount given to create this order.

        • preauthorizedAmountnumber (int)required

          The amount which has been authorized.

        • capturedAmountnumber (int)required

          The amount which has been captured.

        • refundedAmountnumber (int)required

          The amount which has been refunded.

        • canceledAmountnumber (int)required

          The amount which has been cancelled.

        • currencystringrequired

          Currency code according to https://en.wikipedia.org/wiki/ISO_4217

        • transactionsarrayrequired

          A list of all underlying transactions.

          • typestringoptional

            the type of the transaction

          • transactionIdstringrequired

            The identifier of the transaction. Created by payengine

          • statusstringrequired

            The current status of the transaction. The status can be one of the following. CREATED, PENDING, IN_PROGRESS, OK, SUCCESS, FAILURE, DECLINED, ABORTED, EXPIRED

          • initialAmountnumber (int)required

            The initial amount given to create this transaction.

          • currencystringrequired

            Currency code according to https://en.wikipedia.org/wiki/ISO_4217

          • descriptionstringrequired

            The description from your system/shop of this transaction.

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this transaction.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this transaction.

          • orderstringrequired

            The identifier of the connected order.

          • transactionsarrayrequired

            A list of underlying transactions.

          • parentTransactionstringrequired

            The identifier of the parent transaction.

          • descriptorstringoptional

            Identifier which holds the orderId

          • capturedAmountnumber (int)required

            The amount which has been captured.

          • refundedAmountnumber (int)required

            The amount which has been refunded.

          • canceledAmountnumber (int)required

            The amount which has been cancelled.

          • challangeobjectoptional

            Contains payment method specifc meta data. For prepayment TAN instructions.

            • titlestringoptional

              The title of the prepayment TAN challange (can be displayed in the TAN form)

            • labelstringoptional

              The label of the prepayment tan challange (can be displayed in the TAN form)

            • formatstringoptional

              The TAN format for prepayment (iTAN, photoTAN, etc.)

            • datastringoptional

              Optional data field for prepayment is needed for some TAN formats e.g. photoTAN

          • trackingarrayoptional

            specific parameter for all payment methods, array of object of type Tracking

            • trackingIdstringoptional
            • providerstringoptional
          • metaobjectoptional

            Contains payment method specifc meta data. For prepayment TAN instructions.

            • tanSentbooleanoptional

              Flag which indicates if the TAN was sent to the bank

            • tanSchemastringoptional

              The TAN schema which was used to finalize a online bank transfer based refund

        • statusstringrequired

          The current status of the order It can be one of the following CREATED, OPEN, CLOSED A order remains open until the initial amount has been refunded or cancelled.

        • channelstringrequired

          The channel determine the kind of origin for this order. (optional, mandatory for creditcard, ratepay-invoice, ratepay-directdebit and ratepay-installment)

        • createdAtnumber (date-time)required

          This timestamp indicates the creation of this order.

        • modifiedAtnumber (date-time)required

          This timestamp indicates the last modification of this order.

        • termsnumber (integer)optional

          A timestamp in milliseconds of the approval of the customer to your terms and conditions. E.g. this is required for RatePAY orders.

        • privacynumber (integer)optional

          A timestamp in milliseconds of the approval of the customer to your privacy policy. E.g. this is required for RatePAY orders.

        • merchantOrderIdstringoptional

          The order id from your system/shop for Creditcards only 30 alphanumeric characters.

        • paymentProviderTransactionIdstringoptional

          The order id from the payment provider.

        • descriptionstringoptional

          The description from your system/shop of this order.

        • statementDescriptionstringoptional

          The statement description from your system/shop of this order.

        • basketarrayoptional

          The basket of your order. (optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

          • namestringoptional

            The articles name used in your shop.

          • articleNumberstringoptional

            The articles number used in your shop.

          • totalPricenumber (int)optional

            The total price for this item excluding taxes. The total amount should be given as smallest currency unit.

          • totalPriceWithTaxnumber (int)optional

            The total price for this item including taxes. The total amount should be given as smallest currency unit. If the item is of type discount, the value must be negative: min -999999999999999998, max -1.

          • unitPricenumber (int)optional

            The unit price for this item excluding taxes. The unit amount should be given as smallest currency unit.

          • unitPriceWithTaxnumber (int)optional

            The unit price for this item including taxes. The unit amount should be given as smallest currency unit.

          • taxnumber (float)optional

            The tax rate for the corresponding item. Will be returned in float format only if scale part contains no trailing zeros. 10.99 -> 10.99 10.90 -> 10.9 10.00 -> 10 10.0 -> 10 10 -> 10

          • quantitynumber (int)optional

            The quantity for this item.

          • discountnumber (int)optional

            item specific discount

          • articleTypestringoptional

            This is the type of the article. Required for Klarna and optional for all other payment methods.

        • customerobjectoptional
          • customerIdstringrequired

            The identifier of the customer. Created by payengine

          • emailstring (email)required

            The customers email address. unique.

          • merchantCustomerIdstringoptional

            The identifier of the customer. Created by you.

          • addressesarrayoptional

            A list of all underlying addresses which are connected to the customer.

            • addressIdstringrequired

              The identifier of the address. Created by payengine

            • createdAtnumber (date-time)required

              This timestamp indicates the creation of this address.

            • modifiedAtnumber (date-time)required

              This timestamp indicates the last modification of this address.

            • firstNamestringoptional

              The firstname of this address. limited to 35 characters!

            • lastNamestringoptional

              The lastname of this address. limited to 35 characters!

            • streetstringoptional

              The street of this address.

            • houseNumberstringoptional

              The housenumber of the street.

            • citystringoptional

              The city of the address.

            • zipstringoptional

              The zip of the address.

            • countrystringoptional

              The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

            • statestringoptional

              The state of the address.

            • phonestringoptional

              The phone of the address. limited to 16 characters!

            • faxstringoptional

              The fax of the address. limited to 16 characters!

            • mobilestringoptional

              The mobile of the address. limited to 16 characters!

            • titlestringoptional

              The title of the address.

            • additionalDetailsstringoptional

              Additional details for this address. This is a form free descriptor.

          • personasarrayoptional

            A list of all underlying personas which are connected to the customer.

            • personaIdstringrequired

              The identifier of the persona. Created by payengine

            • createdAtnumber (date-time)required

              This timestamp indicates the creation of this persona.

            • modifiedAtnumber (date-time)required

              This timestamp indicates the last modification of this persona.

            • firstNamestringoptional

              The firstname of this persona. limited to 35 characters!

            • lastNamestringoptional

              The lastname of this persona. limited to 35 characters!

            • phonestringoptional

              The phone of the persona. limited to 16 characters!

            • mobilestringoptional

              The mobile of the persona. limited to 16 characters!

            • faxstringoptional

              The fax of the persona. limited to 16 characters!

            • birthdaynumber (date-time)optional

              The birthday of the persona. Format as milliseconds since epoch representing UTC Date.

            • genderstringoptional

              The gender of the persona.

            • titlestringoptional

              The title of the persona.

          • paymentInstrumentsarrayoptional

            A list of all underlying paymentinstruments which are connected to the customer.

            • paymentInstrumentIdstringrequired

              The identifier of the paymentinstrument. Created by payengine

            • merchantPaymentInstrumentIdstringrequired

              The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

            • originstringrequired

              The product used to create this order. (mandatory)

            • typestringrequired

              the type of the payment instrument

            • recurringbooleanrequired

              This flag indicates if this paymentinstrument can be used for recurring payments.

            • createdAtintegeroptional

              Timestamp when it was created

            • modifiedAtintegeroptional

              Timestamp when it was last updated

            • attributesobjectrequired

              Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

              • cofContractsarrayoptional

                For CreditCard only

                • idstringoptional

                  Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

                • typestringoptional

                  Credential on file type:

                  • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
                  • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
                  • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
                • channelstringoptional

                  The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

                • recurringExpirystring (date)optional

                  Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

                • recurringFrequencynumberoptional

                  Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

              • customerRelationUuidstringoptional

                For TWINT only. Recognition of a returning customer.

        • personaobjectoptional
          • personaIdstringrequired

            The identifier of the persona. Created by payengine

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this persona.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this persona.

          • firstNamestringoptional

            The firstname of this persona. limited to 35 characters!

          • lastNamestringoptional

            The lastname of this persona. limited to 35 characters!

          • phonestringoptional

            The phone of the persona. limited to 16 characters!

          • mobilestringoptional

            The mobile of the persona. limited to 16 characters!

          • faxstringoptional

            The fax of the persona. limited to 16 characters!

          • birthdaynumber (date-time)optional

            The birthday of the persona. Format as milliseconds since epoch representing UTC Date.

          • genderstringoptional

            The gender of the persona.

          • titlestringoptional

            The title of the persona.

        • billingAddressobjectoptional
          • addressIdstringrequired

            The identifier of the address. Created by payengine

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this address.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this address.

          • firstNamestringoptional

            The firstname of this address. limited to 35 characters!

          • lastNamestringoptional

            The lastname of this address. limited to 35 characters!

          • streetstringoptional

            The street of this address.

          • houseNumberstringoptional

            The housenumber of the street.

          • citystringoptional

            The city of the address.

          • zipstringoptional

            The zip of the address.

          • countrystringoptional

            The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

          • statestringoptional

            The state of the address.

          • phonestringoptional

            The phone of the address. limited to 16 characters!

          • faxstringoptional

            The fax of the address. limited to 16 characters!

          • mobilestringoptional

            The mobile of the address. limited to 16 characters!

          • titlestringoptional

            The title of the address.

          • additionalDetailsstringoptional

            Additional details for this address. This is a form free descriptor.

        • shippingAddressobjectoptional
          • addressIdstringrequired

            The identifier of the address. Created by payengine

          • createdAtnumber (date-time)required

            This timestamp indicates the creation of this address.

          • modifiedAtnumber (date-time)required

            This timestamp indicates the last modification of this address.

          • firstNamestringoptional

            The firstname of this address. limited to 35 characters!

          • lastNamestringoptional

            The lastname of this address. limited to 35 characters!

          • streetstringoptional

            The street of this address.

          • houseNumberstringoptional

            The housenumber of the street.

          • citystringoptional

            The city of the address.

          • zipstringoptional

            The zip of the address.

          • countrystringoptional

            The country of the address. Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]

          • statestringoptional

            The state of the address.

          • phonestringoptional

            The phone of the address. limited to 16 characters!

          • faxstringoptional

            The fax of the address. limited to 16 characters!

          • mobilestringoptional

            The mobile of the address. limited to 16 characters!

          • titlestringoptional

            The title of the address.

          • additionalDetailsstringoptional

            Additional details for this address. This is a form free descriptor.

        • ipAddressstringoptional

          The IP address used to submit the order. (Optional, mandatory for ratepay-invoice, ratepay-directdebit and ratepay-installment)

        • paymentInstrumentobjectoptional

          The paymentinstrument which has been used to process this order. note: If no paymentinstrument has been submitted, one has been created with your submitted data.

          • paymentInstrumentIdstringrequired

            The identifier of the paymentinstrument. Created by payengine

          • merchantPaymentInstrumentIdstringrequired

            The identifier of the paymentinstrument on your system. Created by you. limited to 100 characters.

          • originstringrequired

            The product used to create this order. (mandatory)

          • typestringrequired

            the type of the payment instrument

          • recurringbooleanrequired

            This flag indicates if this paymentinstrument can be used for recurring payments.

          • createdAtintegeroptional

            Timestamp when it was created

          • modifiedAtintegeroptional

            Timestamp when it was last updated

          • attributesobjectrequired

            Additional attributes of this paymentinstrument. E.g. masked bank- or creditcarddata. For Klarna we will have possibleTypes object in the response (e.g. klarna-pay-now, klarna-pay-later, klarna-slice-it) Also we will have country, and locale. For PPRO payments methods we could have accountHolder (if one was used for making the transaction)

            • cofContractsarrayoptional

              For CreditCard only

              • idstringoptional

                Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

              • typestringoptional

                Credential on file type:

                • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
                • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
                • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
              • channelstringoptional

                The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

              • recurringExpirystring (date)optional

                Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

              • recurringFrequencynumberoptional

                Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

            • customerRelationUuidstringoptional

              For TWINT only. Recognition of a returning customer.

        • redirectUrlstring (url)optional

          The URL which the customer needs to be redirected to.

        • sourcestringoptional

          The source of the order.

        • productstringoptional

          The product used to create this order. (mandatory)

        • allowedProductsarrayoptional

          A List of all valid products for this order.

        • settledbooleanoptional

          A flag which indicates if this order has been settled or not.

        • settlementDatestring (date-time)optional

          The date of the settlement.

        • transactionTypestringoptional

          The type of the underlying Transaction

        • deviceIdentobjectoptional
          • tokenstringoptional
          • fraudscorenumberoptional
          • fraudscoreRawnumberoptional
          • ruleScoresstringoptional
          • fraudscoreRulematchesstringoptional
          • citystringoptional
          • ipstringoptional
          • regioncodestringoptional
          • continentstringoptional
          • countrynamestringoptional
          • regionnamestringoptional
          • countrycodestringoptional
          • latitudenumberoptional
          • longitudenumberoptional
          • exactidCreatedstringoptional
          • smartidCreatedstringoptional
          • exactidstringoptional
          • confidencelevelnumberoptional
          • smartidstringoptional
          • confidencelevelhistorynumberoptional
          • verifiedOsstringoptional
          • deviceTypestringoptional
          • languagesstringoptional
        • metaobjectoptional
          • deferredbooleanoptional

            Indicates if the order is marked as deferred. Available only for paypal.

          • emailSubjectstringoptional

            Available only for paypal. The subject line of the email that PayPal sends when the transaction is completed.

          • receiverTypestringoptional

            Available only for paypal. Indicates how you identify the recipients of payments in this call to MassPay.

          • receiverEmailstringoptional

            Available only for paypal. Email address of recipient.

          • receiverPhonestringoptional

            Available only for paypal. Mobile phone number of recipient.

          • receiverIdstringoptional

            Available only for paypal. Unique PayPal customer account number.

          • preferredLanguagestringoptional

            Available only for RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay.

          • mobileViewbooleanoptional

            Available only for Alipay.

          • qrCodestringoptional

            Available only for TWINT. Image of the pairing token as a QR code (PNG image in base-64 encoding).

          • tokenstringoptional

            Available only for TWINT. Numeric token to establish the pairing between the customer and cash register.

          • cofContractobjectoptional

            The credentials on file (COF) contract object specifying the COF usage of the payment instrument. The presence of this object triggers an zero amount authorization (card check) for the given channel and type.

            • idstringoptional

              Unique identifier for the COF contract of the payment instrument. In case more than one COF type should be used for one paymentInstrument this identifier should be stored by the merchant and referenced in the payment transactions.

            • typestringoptional

              Credential on file type:

              • ONECLICK - The payment instrument is persisted, recurring and can be used for oneClick payments.
              • UNSCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated unscheduled orders.
              • SCHEDULED - The payment instrument is persisted, recurring and can be used for merchant initiated scheduled or instalments orders.
            • channelstringoptional

              The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.

            • recurringExpirystring (date)optional

              Date after which no further authorizations shall be performed. This field is only required in case of an authentication for recurring payments.

            • recurringFrequencynumberoptional

              Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.

          • externalCofDataobjectoptional
            • typestringrequired

              The type of the credential on file usage.

              • UNSCHEDULED - The payment credentials can be used for merchant initiated unscheduled orders.
              • SCHEDULED - The payment credentials can be used for merchant initiated scheduled orders.
            • initialSchemeTraceIdstringoptional

              The initial Trace ID that was used for the MIT (merchant initiated transaction) mandate setup. This reference will be used by the card schemes to trace back the strong customer authentication that was provided with the initial CIT (cardholder initiated transaction) of the credential on file setup. The value should only be used if the handling of the CIT was done externally outside of the Payengine. Mandatory for subsequent MIT transactions.

              If no schemeTraceId is available, the payengine allows this field to be null, initially. The response meta will contain a new 'schemeTraceId' provided by the credit card scheme which is to be supplied in subsequent order requests in this property.

          • schemeTraceIdstringoptional

            Scheme Trace ID or transaction reference returned by the card scheme for each authorization. This value can be used in subsequent MIT payments if the credential on file handling is not done by the Payengine but externally. See 'externalCofData.initialSchemeTraceId' description.

          • threeDsDataobjectoptional
            • authenticationResultobjectoptional

              Object containing the result of the 3DS authentication transaction (final results will be available only in case of frictionless flow)

              • versionstringoptional

                Parameter indicating the version of the 3DS

              • statusstringoptional

                Indicates whether a transaction qualifies as an authenticated transaction. Y = authentication verificationsuccessful A = authentication attempted; not authenticated, but a proof of attempted authentication is provided C = challenge required; additional SCA authentication is required U = authentication could not be performed; technical or other problem R = authentication rejected; issuer is rejecting N = not authenticated; transaction denied

              • redirectUrlstringoptional

                Conditional - present in case of 3DS 1.0 and challenge flow for 3DS 2.0 redirect URL leading to hosted page by Payengine used for Cardholder authentication (main flow for 3DS 1.0 and fallback flow in case of challenge for 3DS 2.0)

              • challengeDataobjectoptional

                Conditional - information available in case of CHALLENGE status, needed for building the challenge iFrame.

                • acsUrlstringoptional

                  Fully qualified URL of the ACS in case the authentication response message indicates that further cardholder interaction is required to complete the authentication. relevant for 3DS 2.0 only

                • base64EncodedChallengeRequeststringoptional

                  Base64-encoded Challenge Request object in case the authentication response message indicates that further Cardholder interaction is required to complete the authentication. (3DS 2.0)

                • challengeWindowSizestringoptional

                  Dimensions of the challenge iframe window in which the challenge page will be displayed to the Cardholder. This value should match the provided size in the browserInfo call. EMVCo assigned window size. '01' -> 250px x 400px, '02' -> 390px x 400px, '03' -> 500px x 600px, '04' -> 600px x 400px, '05' -> Full screen, or full container content relevant for 3DS 2.0 only

              • transactionIdstringoptional

                The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID

              • acsReferenceNumberstringoptional

                Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval. Set by the EMVCo Secretariat.

              • acsSignedContentstringoptional

                Contains the JWS object (represented as a string) created by the ACS for the ARes message. The body of JWS object (represented as a string) will contain the following data elements as defined • ACS URL • ACS Ephemeral Public Key (QT) • SDK Ephemeral Public Key (QC)

              • acsTransactionIdstringoptional

                Universally Unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements.

              • authenticationValuestringoptional

                The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard

              • cardholderInfostringoptional

                Statement about the result of the 3DS authentication.

              • ecistringoptional

                The Electronic Commerce Indicator (ECI) provided by the ACS or DS to indicate the results of the attempt to authenticate the cardholder. The ECI values might differ depending on the card scheme. For all fully authenticated or authentication attempted transactions the liability will be shifted to the card issuer. Mastercard 00 - fully authenticated 01 - authentication attempted 02 - no authentication available 07 - fully authenticated*1 All other card schemes 05 - fully authenticated 06 - authentication attempted 07 - no authentication available *1 - Mastercard distinguishes between fully authenticated recurring payments (flagged with ECI 07) and all other fully authenticated transactions (flagged with ECI 00).

              • statusReasonstringoptional

                Reason why the authenticationResult.status field has the specified value. 01 = Card authentication failed 02 = Unknown Device 03 = Unsupported Device 04 = Exceeds authentication frequency limit 05 = Expired card 06 = Invalid card number 07 = Invalid transaction 08 = No Card record 09 = Security failure 10 = Stolen card 11 = Suspected fraud 12 = Transaction not permitted to cardholder 13 = Cardholder not enrolled in service 14 = Transaction timed out at the ACS 15 = Low confidence 16 = Medium confidence 17 = High confidence 18 = Very High confidence 19 = Exceeds ACS maximum challenges 20 = Non-Payment transaction not supported 21 = 3RI transaction not supported 22 = ACS technical issue 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor 24 = 3DS Requestor Decoupled Max Expiry Time exceeded 25 = Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt 26 = Authentication attempted but not performed by the cardholder 27–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use

              • forceChallengebooleanoptional

                Flag to force challenge for 3ds v2

              • errorDetailsobjectoptional

                Object containing error information in case of error.

                • providerCodestringoptional

                  Original error code from the 3DS server or mpi

                • providerMessagestringoptional

                  Original error message from the 3DS server or mpi

          • edccDataobjectoptional

            Details about the eDCC offer used in the order

            • edccIdstringoptional

              The ID of the eDCC offer to be used for currency conversion

            • foreignAmountnumber (int)optional

              The foreign amount, to which the baseAmount is converted

            • marginPercentagenumber (int)optional
            • ratenumber (float)optional

              The conversion rate used to convert the baseAmount to the foreignCurrency

            • baseCurrencystringoptional

              The string currency code of the base currency

            • foreignCurrencystringoptional

              The string currency code of the foreign currency

          • cardAcquirerRoutingTostringoptional

            Card specific parameter: The acquirer the card transaction should be routed to. This flagging can only be used if more than one acquirer is enabled for the merchant account.

          • instantbooleanoptional

            Indicator if the credit should be instant e.g. visa oct

        • lastOperationstringoptional

          A combined field of the last executed transaction and the status of the transaction. "TRANSACTION_<TRANSACTION_TYPE>_<TRANSACTION_STATUS>"

      • totalPagesnumber (int)required

        A counter for the total pages returned.

    200

    {
        "elements": [
            {
                "orderId": "string",
                "initialAmount": 1,
                "preauthorizedAmount": 1,
                "capturedAmount": 1,
                "refundedAmount": 1,
                "canceledAmount": 1,
                "currency": "str",
                "transactions": [
                    {
                        "type": "PREAUTH",
                        "transactionId": "string",
                        "status": "CREATED",
                        "initialAmount": 1,
                        "currency": "str",
                        "description": "string",
                        "createdAt": 0,
                        "modifiedAt": 0,
                        "order": "string",
                        "transactions": [
                            "string"
                        ],
                        "parentTransaction": "string",
                        "descriptor": "string",
                        "capturedAmount": 1,
                        "refundedAmount": 1,
                        "canceledAmount": 1,
                        "challange": {
                            "title": "string",
                            "label": "string",
                            "format": "string",
                            "data": "string"
                        },
                        "tracking": [
                            {
                                "trackingId": "string",
                                "provider": "DPD"
                            }
                        ],
                        "meta": {
                            "tanSent": true,
                            "tanSchema": "string"
                        }
                    }
                ],
                "status": "CREATED",
                "channel": "MOTO",
                "createdAt": 0,
                "modifiedAt": 0,
                "terms": 0,
                "privacy": 0,
                "merchantOrderId": "string",
                "paymentProviderTransactionId": "string",
                "description": "string",
                "statementDescription": "string",
                "basket": [
                    {
                        "name": "string",
                        "articleNumber": "string",
                        "totalPrice": -1000000000000000000,
                        "totalPriceWithTax": -1000000000000000000,
                        "unitPrice": -1000000000000000000,
                        "unitPriceWithTax": -1000000000000000000,
                        "tax": 100,
                        "quantity": 1,
                        "discount": -1000000000000000000,
                        "articleType": "physical"
                    }
                ],
                "customer": {
                    "customerId": "string",
                    "email": "user@example.com",
                    "merchantCustomerId": "string",
                    "addresses": [
                        {
                            "addressId": "string",
                            "createdAt": 0,
                            "modifiedAt": 0,
                            "firstName": "string",
                            "lastName": "string",
                            "street": "string",
                            "houseNumber": "string",
                            "city": "string",
                            "zip": "string",
                            "country": "st",
                            "state": "string",
                            "phone": "string",
                            "fax": "string",
                            "mobile": "string",
                            "title": "string",
                            "additionalDetails": "string"
                        }
                    ],
                    "personas": [
                        {
                            "personaId": "string",
                            "createdAt": 0,
                            "modifiedAt": 0,
                            "firstName": "string",
                            "lastName": "string",
                            "phone": "string",
                            "mobile": "string",
                            "fax": "string",
                            "birthday": 0,
                            "gender": "MALE",
                            "title": "string"
                        }
                    ],
                    "paymentInstruments": [
                        {
                            "paymentInstrumentId": "string",
                            "merchantPaymentInstrumentId": "string",
                            "origin": "creditcard",
                            "type": "sepa",
                            "recurring": true,
                            "createdAt": 0,
                            "modifiedAt": 0,
                            "attributes": {
                                "cofContracts": [
                                    {
                                        "id": "contract_123abc456x",
                                        "type": "ONECLICK",
                                        "channel": "ECOM",
                                        "recurringExpiry": "2019-07-10",
                                        "recurringFrequency": 30
                                    }
                                ],
                                "customerRelationUuid": "string"
                            }
                        }
                    ]
                },
                "persona": {
                    "personaId": "string",
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "firstName": "string",
                    "lastName": "string",
                    "phone": "string",
                    "mobile": "string",
                    "fax": "string",
                    "birthday": 0,
                    "gender": "MALE",
                    "title": "string"
                },
                "billingAddress": {
                    "addressId": "string",
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "firstName": "string",
                    "lastName": "string",
                    "street": "string",
                    "houseNumber": "string",
                    "city": "string",
                    "zip": "string",
                    "country": "st",
                    "state": "string",
                    "phone": "string",
                    "fax": "string",
                    "mobile": "string",
                    "title": "string",
                    "additionalDetails": "string"
                },
                "shippingAddress": {
                    "addressId": "string",
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "firstName": "string",
                    "lastName": "string",
                    "street": "string",
                    "houseNumber": "string",
                    "city": "string",
                    "zip": "string",
                    "country": "st",
                    "state": "string",
                    "phone": "string",
                    "fax": "string",
                    "mobile": "string",
                    "title": "string",
                    "additionalDetails": "string"
                },
                "ipAddress": "string",
                "paymentInstrument": {
                    "paymentInstrumentId": "string",
                    "merchantPaymentInstrumentId": "string",
                    "origin": "creditcard",
                    "type": "sepa",
                    "recurring": true,
                    "createdAt": 0,
                    "modifiedAt": 0,
                    "attributes": {
                        "cofContracts": [
                            {
                                "id": "contract_123abc456x",
                                "type": "ONECLICK",
                                "channel": "ECOM",
                                "recurringExpiry": "2019-07-10",