Payengine Public

Documentation for Payengine API v1.0

C#PHPNodeShell

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

C#
PHP
Node
Shell

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.

creditcard, sepa, klarna, paypal
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.
  example: Deutsche Bank
- ibanstringoptional
  IBAN of the SEPA account. (mandatory for sepa, optional if a sepa paymentInstrumentId was passed)
  example: DE15111111111111111199
- 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)
  example: DEUTDEDBKOE
- 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.
  example: Max Muster
- 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
    
    FIRST, SINGLE, RECURRING, FINAL
- 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.
    
    physical, digital, discount, shipping_fee, gift_card
  - 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)
  
  creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
- typestringrequired
  the type of the payment instrument
  
  sepa, creditcard, paypal, paydirekt, bank-transfer
- 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
  - customerRelationUuidstringoptional
    For TWINT only. Recognition of a returning customer.
400Bad request based on invalid input.optional
- pathstringoptionalexample: v1/payment-instruments
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating payment instrument!
- codenumberoptionalexample: 10003
- globalTrackIdstringoptionalexample: Some Request ID
- 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

C#
PHP
Node
Shell

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)
    
    creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
  - typestringrequired
    the type of the payment instrument
    
    sepa, creditcard, paypal, paydirekt, bank-transfer
  - 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
    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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}");
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)
  
  creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
- typestringrequired
  the type of the payment instrument
  
  sepa, creditcard, paypal, paydirekt, bank-transfer
- 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
  - customerRelationUuidstringoptional
    For TWINT only. Recognition of a returning customer.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/payment-instruments/paymentinstrument_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while fetching payment instrument!
- codenumberoptionalexample: 10001
- globalTrackIdstringoptionalexample: Some Request ID
- 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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}");
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
- pathstringoptionalexample: v1/payment-instruments/paymentinstrument_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while fetching payment instrument!
- codenumberoptionalexample: 10001
- globalTrackIdstringoptionalexample: Some Request ID
- 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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}");
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
  
  FIRST, SINGLE, RECURRING, FINAL
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.
  
  physical, digital, discount, shipping_fee, gift_card
- 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)
  
  creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
- typestringrequired
  the type of the payment instrument
  
  sepa, creditcard, paypal, paydirekt, bank-transfer
- 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
  - customerRelationUuidstringoptional
    For TWINT only. Recognition of a returning customer.
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/payment-instruments/paymentinstrument_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while updating payment instrument!
- codenumberoptionalexample: 10003
- globalTrackIdstringoptionalexample: Some Request ID
- 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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}/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.

concardis, nets
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.
  
  ONECLICK, UNSCHEDULED, SCHEDULED
- channelstringoptional
  The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
  
  ECOM, MOTO
  example: 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.
example: threeDsAuthentication_123abc987y

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.
  example: cardcheck_abc123xyz4
- createdAtnumberoptional
  Timestamp when card check was initiated.
  example: 1562574062133
- modifiedAtnumberoptional
  Timestamp when card check was modified.
  example: 1562574062133
- statusstringoptional
  The status of the card check.
  
  SUCCESS, FAILURE
  example: SUCCESS
- threeDsAuthenticationIdstringoptional
  Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.
  example: authentication_123abc456x
- 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.
    example: contract_123abc456x
  - 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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
  - channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
  - recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
- 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.
  
  concardis, nets
- errorDetailsobjectoptional
  Object containing error information in case of a FAILURE status.
  - providerCodestringoptional
    Card processor code in case of an error.
    example: 00
  - providerMessagestringoptional
    Card processor message in case of an error.
    example: Transaction Approved

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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}/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.

concardis, nets

Request body

{
    "cardAcquirerRoutingTo": "concardis"
}

Responses

200Successful response.optional
- idstringrequired
  Payeninge identifier for the 3DS version object
  example: threedsversion_123abc456z
- createdAtnumberrequired
  Timestamp when card check was initiated
  example: 1562769950956
- modifiedAtnumberrequired
  Timestamp when card check was modified
  example: 1562769950956
- 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.
  example: 2.0
- 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).
    example: https://www.acs.com/script
  - 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)
    example: YmFzZTY0RW5jb2RlZFRocmVlRHNNZXRob2REYXRh
- 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.
  
  concardis, nets
400Not found caused by invalid input.optional
- pathstringoptionalexample: v1/payment-instruments/paymentinstrument_asdfghjk/3ds-version
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: There is problem with 3DS version request.
- codenumberoptionalexample: 25719
- globalTrackIdstringoptionalexample: Some Request ID

{
    "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

C#
PHP
Node
Shell

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.
example: brw-accept-header
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 (:).
example: 192.168.0.1
javaEnabledbooleanoptional
Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.
example: true
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.
example: en-US
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.
example: 8
screenHeightnumberoptional
Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.
example: 100
screenWidthnumberoptional
Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.
example: 100
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.
example: 60
userAgentstringoptional
Exact content of the HTTP user-agent header.
example: Chrome/71.0.3578.98
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

01, 02, 03, 04, 05
example: 05

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
  example: browserinfo_123xyz456a

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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/payment-instruments/{paymentInstrumentId}/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

PAYMENT_TRANSACTION, RECURRING_TRANSACTION, RECURRING_CARDCHECK, ADD_CARD
example: PAYMENT_TRANSACTION
customerIdstringoptional
The identifier of a payengine customer.
example: customer_abc123xyz1
shippingAddressIdstringoptional
The identifier of a payengine address.
example: address_abc123xyz1
billingAddressIdstringoptional
The identifier of a payengine address.
example: address_abc123xyz1
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.
  example: 1000
- currencystringoptional
  The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217
  example: EUR
- 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.
  example: 2019-07-10
- recurringFrequencynumberoptional
  Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
  example: 30
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.
    example: customer-abc123
  - creationDatestring (date)optional
    The date when the customer opened the account with the merchant.
    example: 2019-07-10
  - 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.
    example: 2019-07-10
  - 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.
    
    CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: CHANGED_WITH_THIS_TRANSACTION
  - lastPasswordChangeDatestring (date)optional
    The date when the customer account with the merchant had a password change or account reset.
    example: 2019-07-10
  - passwordChangeIndicatorstringoptional
    Length of the time since the customer account information with the merchant had a password change or account reset.
    
    NO_CHANGE, CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
  - authenticationMethodstringoptional
    Mechanism used by the customer to authenticate to the merchant account.
    
    GUEST, OWN_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_AUTH, FIDO_AUTHENTICATOR
    example: OWN_CREDENTIALS
  - authenticationTimestampstring (date-time)optional
    Date and time in UTC of the customer authentication to the merchant account.
    example: 2019-07-10T15:04:09.722Z
  - shippingAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the merchant account.
    
    FIRST_TIME, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
  - shippingAddressFirstUsagestring (date)optional
    Date when the shipping address used for this transaction was first used with the merchant.
    example: 2019-07-10
  - transactionCountLastDaynumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.
    example: 1
  - transactionCountLastYearnumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.
    example: 10
  - orderCountLast6Monthsnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    example: 5
  - suspiciousActivitybooleanoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.
    example: false
  - accountEqualsShippingNamebooleanoptional
    Indicates if the customer name on the account is identical to the shipping name used for this transaction.
    example: true
  - paymentAccountAgeIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the customer account with the merchant.
    
    NO_ACCOUNT, CREATED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
  - paymentAccountEnrollementDatestring (date)optional
    Date that the payment account was enrolled in the customer account with the merchant.
    example: 2019-07-10
- shippingInfoobjectoptional
  object containing information about the shipping details for this transaction.
  - shippingEqualsBillingAddressbooleanoptional
    Flag if the shipping address equals the billing address.
    example: true
  - 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.
    
    SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TICKETS_NOT_SHIPPED, OTHER
    example: SHIP_TO_BILLING_ADDRESS
  - deliveryTimestringoptional
    Indicates the merchandise delivery timeframe.
    
    ELECTRONIC, SAME_DAY, OVERNIGHT, TWO_DAY_OR_MORE
    example: SAME_DAY
  - deliveryEmailstringoptional
    For electronic delivery, the email address to which the merchandise was delivered.
    example: john@doe.com
- orderInfoobjectoptional
  object containing order information relevant for risk evaluation
  - isReorderbooleanoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: false
  - preOrderIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    
    MERCHANTDISE_AVAILABLE, FUTURE_AVAILABILITY
    example: MERCHANTDISE_AVAILABLE
  - preOrderDatestring (date)optional
    For a pre-ordered purchase, the expected date that the merchandise will be available.
    example: 2019-07-10
  - 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
    
    01, 03, 10, 11, 28
    example: 01
browserInfoIdstringoptional
Payengine identifier of the browser info object
example: browserinfo_123abc456d
sdkInfoIdstringoptional
Payengine identifier of the sdk info object
example: sdkinfo_123abc456d
asyncobjectoptional
An object containing the relevant URLs for asynchronous communication
- notificationUrlstringoptional
  URL where the result of the 3DS transaction will be sent to
  example: https://my.notification.url
- successUrlstringoptional
  URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded
  example: https://my.success.url
- failureUrlstringoptional
  URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed
  example: https://my.failure.url
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
  example: authentication_def456abc9
- createdAtnumberoptional
  Timestamp when the authentication was initiated.
  example: 1562769950956
- modifiedAtnumberoptional
  Timestamp when the authentication was modified.
  example: 1562769950956
- paymentInstrumentIdstringoptional
  Identifier of the payment instrument used for the 3DS authentication.
  example: paymentinstrument_pkekrrl5ua
- threeDsVersionIdstringoptional
  Identifier of the 3DS version info based on which the authentication was done.
  example: threedsversion_123def987a
- 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
    example: 2.0
  - 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
    
    Y, A, C, U, R, N
    example: Y
  - 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)
    example: https://link-the-hosted-challange.example
  - 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
    example: https://link-to-the-issuer.acs
    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)
    example: Y2hhbGxhbmdlRGF0YQ==
    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
    
    01, 02, 03, 04, 05
    example: 05
  - transactionIdstringoptional
    The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID
    example: d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4
  - 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
    example: YXV0aGVudGljYXRpb25WYWx1ZQ==
  - 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).
    example: 05
  - 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
    example: 01
  - forceChallengebooleanoptional
    Flag to force challenge for 3ds v2
    example: true
  - errorDetailsobjectoptional
    Object containing error information in case of error.
    providerCodestringoptional
    Original error code from the 3DS server or mpi
    example: 301
    providerMessagestringoptional
    Original error message from the 3DS server or mpi
    example: TRANSACTION_ID_NOT_RECOGNIZED
- 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
  
  PAYMENT_TRANSACTION, RECURRING_TRANSACTION, RECURRING_CARDCHECK, ADD_CARD
  example: PAYMENT_TRANSACTION
- customerIdstringoptional
  The identifier of a payengine customer.
  example: customer_abc123xyz1
- shippingAddressIdstringoptional
  The identifier of a payengine address.
  example: address_abc123xyz1
- billingAddressIdstringoptional
  The identifier of a payengine address.
  example: address_abc123xyz1
- 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.
    example: 1000
  - currencystringoptional
    The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217
    example: EUR
  - 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.
    example: 2019-07-10
  - recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
- 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.
    example: customer-abc123
    creationDatestring (date)optional
    The date when the customer opened the account with the merchant.
    example: 2019-07-10
    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.
    example: 2019-07-10
    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.
    
    CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: CHANGED_WITH_THIS_TRANSACTION
    lastPasswordChangeDatestring (date)optional
    The date when the customer account with the merchant had a password change or account reset.
    example: 2019-07-10
    passwordChangeIndicatorstringoptional
    Length of the time since the customer account information with the merchant had a password change or account reset.
    
    NO_CHANGE, CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
    authenticationMethodstringoptional
    Mechanism used by the customer to authenticate to the merchant account.
    
    GUEST, OWN_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_AUTH, FIDO_AUTHENTICATOR
    example: OWN_CREDENTIALS
    authenticationTimestampstring (date-time)optional
    Date and time in UTC of the customer authentication to the merchant account.
    example: 2019-07-10T15:04:09.722Z
    shippingAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the merchant account.
    
    FIRST_TIME, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
    shippingAddressFirstUsagestring (date)optional
    Date when the shipping address used for this transaction was first used with the merchant.
    example: 2019-07-10
    transactionCountLastDaynumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.
    example: 1
    transactionCountLastYearnumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.
    example: 10
    orderCountLast6Monthsnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    example: 5
    suspiciousActivitybooleanoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.
    example: false
    accountEqualsShippingNamebooleanoptional
    Indicates if the customer name on the account is identical to the shipping name used for this transaction.
    example: true
    paymentAccountAgeIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the customer account with the merchant.
    
    NO_ACCOUNT, CREATED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    paymentAccountEnrollementDatestring (date)optional
    Date that the payment account was enrolled in the customer account with the merchant.
    example: 2019-07-10
  - shippingInfoobjectoptional
    object containing information about the shipping details for this transaction.
    shippingEqualsBillingAddressbooleanoptional
    Flag if the shipping address equals the billing address.
    example: true
    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.
    
    SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TICKETS_NOT_SHIPPED, OTHER
    example: SHIP_TO_BILLING_ADDRESS
    deliveryTimestringoptional
    Indicates the merchandise delivery timeframe.
    
    ELECTRONIC, SAME_DAY, OVERNIGHT, TWO_DAY_OR_MORE
    example: SAME_DAY
    deliveryEmailstringoptional
    For electronic delivery, the email address to which the merchandise was delivered.
    example: john@doe.com
  - orderInfoobjectoptional
    object containing order information relevant for risk evaluation
    isReorderbooleanoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: false
    preOrderIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    
    MERCHANTDISE_AVAILABLE, FUTURE_AVAILABILITY
    example: MERCHANTDISE_AVAILABLE
    preOrderDatestring (date)optional
    For a pre-ordered purchase, the expected date that the merchandise will be available.
    example: 2019-07-10
    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
    
    01, 03, 10, 11, 28
    example: 01
- browserInfoIdstringoptional
  Payengine identifier of the browser info object
  example: browserinfo_123abc456d
- asyncobjectoptional
  An object containing the relevant URLs for asynchronous communication
  - notificationUrlstringoptional
    URL where the result of the 3DS transaction will be sent to
    example: https://my.notification.url
  - successUrlstringoptional
    URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded
    example: https://my.success.url
  - failureUrlstringoptional
    URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed
    example: https://my.failure.url
- 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.
  
  concardis, nets
- 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
  example: e302d01e-0a0e-4556-a8d2-64bd433170bc

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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/creditcard/3ds-authentication/{threeDsAuthenticationId}");
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
  example: authentication_def456abc9
- createdAtnumberoptional
  Timestamp when the authentication was initiated.
  example: 1562769950956
- modifiedAtnumberoptional
  Timestamp when the authentication was modified.
  example: 1562769950956
- paymentInstrumentIdstringoptional
  Identifier of the payment instrument used for the 3DS authentication.
  example: paymentinstrument_pkekrrl5ua
- threeDsVersionIdstringoptional
  Identifier of the 3DS version info based on which the authentication was done.
  example: threedsversion_123def987a
- 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
    example: 2.0
  - 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
    
    Y, A, C, U, R, N
    example: Y
  - 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)
    example: https://link-the-hosted-challange.example
  - 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
    example: https://link-to-the-issuer.acs
    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)
    example: Y2hhbGxhbmdlRGF0YQ==
    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
    
    01, 02, 03, 04, 05
    example: 05
  - transactionIdstringoptional
    The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID
    example: d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4
  - 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
    example: YXV0aGVudGljYXRpb25WYWx1ZQ==
  - 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).
    example: 05
  - 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
    example: 01
  - forceChallengebooleanoptional
    Flag to force challenge for 3ds v2
    example: true
  - errorDetailsobjectoptional
    Object containing error information in case of error.
    providerCodestringoptional
    Original error code from the 3DS server or mpi
    example: 301
    providerMessagestringoptional
    Original error message from the 3DS server or mpi
    example: TRANSACTION_ID_NOT_RECOGNIZED
- 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
  
  PAYMENT_TRANSACTION, RECURRING_TRANSACTION, RECURRING_CARDCHECK, ADD_CARD
  example: PAYMENT_TRANSACTION
- customerIdstringoptional
  The identifier of a payengine customer.
  example: customer_abc123xyz1
- shippingAddressIdstringoptional
  The identifier of a payengine address.
  example: address_abc123xyz1
- billingAddressIdstringoptional
  The identifier of a payengine address.
  example: address_abc123xyz1
- 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.
    example: 1000
  - currencystringoptional
    The currency of the purchase according to https://en.wikipedia.org/wiki/ISO_4217
    example: EUR
  - 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.
    example: 2019-07-10
  - recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
- 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.
    example: customer-abc123
    creationDatestring (date)optional
    The date when the customer opened the account with the merchant.
    example: 2019-07-10
    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.
    example: 2019-07-10
    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.
    
    CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: CHANGED_WITH_THIS_TRANSACTION
    lastPasswordChangeDatestring (date)optional
    The date when the customer account with the merchant had a password change or account reset.
    example: 2019-07-10
    passwordChangeIndicatorstringoptional
    Length of the time since the customer account information with the merchant had a password change or account reset.
    
    NO_CHANGE, CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
    authenticationMethodstringoptional
    Mechanism used by the customer to authenticate to the merchant account.
    
    GUEST, OWN_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_AUTH, FIDO_AUTHENTICATOR
    example: OWN_CREDENTIALS
    authenticationTimestampstring (date-time)optional
    Date and time in UTC of the customer authentication to the merchant account.
    example: 2019-07-10T15:04:09.722Z
    shippingAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the merchant account.
    
    FIRST_TIME, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
    shippingAddressFirstUsagestring (date)optional
    Date when the shipping address used for this transaction was first used with the merchant.
    example: 2019-07-10
    transactionCountLastDaynumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.
    example: 1
    transactionCountLastYearnumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.
    example: 10
    orderCountLast6Monthsnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    example: 5
    suspiciousActivitybooleanoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.
    example: false
    accountEqualsShippingNamebooleanoptional
    Indicates if the customer name on the account is identical to the shipping name used for this transaction.
    example: true
    paymentAccountAgeIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the customer account with the merchant.
    
    NO_ACCOUNT, CREATED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    paymentAccountEnrollementDatestring (date)optional
    Date that the payment account was enrolled in the customer account with the merchant.
    example: 2019-07-10
  - shippingInfoobjectoptional
    object containing information about the shipping details for this transaction.
    shippingEqualsBillingAddressbooleanoptional
    Flag if the shipping address equals the billing address.
    example: true
    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.
    
    SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TICKETS_NOT_SHIPPED, OTHER
    example: SHIP_TO_BILLING_ADDRESS
    deliveryTimestringoptional
    Indicates the merchandise delivery timeframe.
    
    ELECTRONIC, SAME_DAY, OVERNIGHT, TWO_DAY_OR_MORE
    example: SAME_DAY
    deliveryEmailstringoptional
    For electronic delivery, the email address to which the merchandise was delivered.
    example: john@doe.com
  - orderInfoobjectoptional
    object containing order information relevant for risk evaluation
    isReorderbooleanoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: false
    preOrderIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    
    MERCHANTDISE_AVAILABLE, FUTURE_AVAILABILITY
    example: MERCHANTDISE_AVAILABLE
    preOrderDatestring (date)optional
    For a pre-ordered purchase, the expected date that the merchandise will be available.
    example: 2019-07-10
    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
    
    01, 03, 10, 11, 28
    example: 01
- browserInfoIdstringoptional
  Payengine identifier of the browser info object
  example: browserinfo_123abc456d
- asyncobjectoptional
  An object containing the relevant URLs for asynchronous communication
  - notificationUrlstringoptional
    URL where the result of the 3DS transaction will be sent to
    example: https://my.notification.url
  - successUrlstringoptional
    URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl succeeded
    example: https://my.success.url
  - failureUrlstringoptional
    URL where the end customer will be redirected to in case of challenge flow using the generated redirectUrl failed
    example: https://my.failure.url
- 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.
  
  concardis, nets
- 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
  example: e302d01e-0a0e-4556-a8d2-64bd433170bc

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

C#
PHP
Node
Shell

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.
  example: cardcheck_abc123xyz4
- createdAtnumberoptional
  Timestamp when card check was initiated.
  example: 1562574062133
- modifiedAtnumberoptional
  Timestamp when card check was modified.
  example: 1562574062133
- statusstringoptional
  The status of the card check.
  
  SUCCESS, FAILURE
  example: SUCCESS
- threeDsAuthenticationIdstringoptional
  Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.
  example: authentication_123abc456x
- 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.
    example: contract_123abc456x
  - 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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
  - channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
  - recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
- 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.
  
  concardis, nets
- errorDetailsobjectoptional
  Object containing error information in case of a FAILURE status.
  - providerCodestringoptional
    Card processor code in case of an error.
    example: 00
  - providerMessagestringoptional
    Card processor message in case of an error.
    example: Transaction Approved

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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/creditcard/card-check/{cardCheckId}");
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.
  example: cardcheck_abc123xyz4
- createdAtnumberoptional
  Timestamp when card check was initiated.
  example: 1562574062133
- modifiedAtnumberoptional
  Timestamp when card check was modified.
  example: 1562574062133
- statusstringoptional
  The status of the card check.
  
  SUCCESS, FAILURE
  example: SUCCESS
- threeDsAuthenticationIdstringoptional
  Identifier of the 3DS authentication in case they should be passed together with the card check authorization to mark an initial COF transaction.
  example: authentication_123abc456x
- 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.
    example: contract_123abc456x
  - 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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
  - channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
  - recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
- 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.
  
  concardis, nets
- errorDetailsobjectoptional
  Object containing error information in case of a FAILURE status.
  - providerCodestringoptional
    Card processor code in case of an error.
    example: 00
  - providerMessagestringoptional
    Card processor message in case of an error.
    example: Transaction Approved
400Bad request for provided input.optional
- pathstringoptionalexample: v1/creditcard/card-check/cardcheck_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Expected: valid identifier for card check transaction.
- codenumberoptionalexample: 25744
- globalTrackIdstringoptionalexample: Some Request ID

{
    "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

C#
PHP
Node
Shell

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
example: 12345
binstringrequired
The 'bin' of the card, with given currency, for which an eDCC offer will be created
example: 411111

Request body

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

Responses

200Successful response.optional
- edccIdstringoptional
  Identifier of the eDCC offer generated by the Payengine
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- edccOfferobjectoptional
  - uuidstringoptional
    An id of the eDCC offer generated by Fexco
    example: a670ea4f-f390-46d8-9a90-6b1b99115708
  - baseAmountnumber (int)optional
    The base amount to convert
    example: 12345
  - exchangeRateobjectoptional
    uuidstringoptional
    An id of the eDCC offer's exchange rate object generated by Fexco
    example: c853d076-636e-4ea1-86e8-7c2d4e3e24e9
    baseCurrencyobjectoptional
    The currency to of the baseAmount
    alphaCodestringoptional
    The string currency code of the currency
    example: EUR
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 978
    ratenumber (float)optional
    The conversion rate used to convert the baseAmount to the foreignCurrency
    example: 1.1276
    foreignCurrencyobjectoptional
    The currency to convert the baseAmount to
    alphaCodestringoptional
    The string currency code of the currency
    example: USD
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 840
    marginPercentagenumber (int)optionalexample: 3
    commissionPercentagenumber (float)optionalexample: 0
    sourcestringoptionalexample: REUTERS WHOLESALE INTERBANK
    sourceTimestampnumber (date)optionalexample: 1454061545000
    expirynumber (date)optional
    The date time until the eDCC offer is valid
    example: 1618783200000
  - foreignAmountnumber (int)optional
    The foreign amount, to which the baseAmount is converted
    example: 13920
  - binobjectoptional
    numberstringoptional
    The 'bin' of the card passed as a parameter
    example: 411111
    currencyobjectoptional
    The currency of the card with the given 'bin'
    alphaCodestringoptional
    The string currency code of the currency
    example: USD
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 840
    schemeCodenumber (int)optionalexample: 1
- 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
    example: merchant_vn9fklv2nb
  - transactionIdstringoptional
    The ID of the authorizing transaction, in which the eDCC offer is used
    example: transaction_mfxrtmqkku
  - cardTypestringoptional
    The brand of the card, used during the authorizing transaction
    example: VISA
  - cardNumberstringoptional
    The last four digits of the number of the card, used during the authorizing transaction
    example: ************1111
  - cardHolderNamestringoptional
    The card holder of the card, used during the authorizing transaction
    example: Max Mustermann

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

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/creditcard/edcc/{edccId}");
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
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- edccOfferobjectoptional
  - uuidstringoptional
    An id of the eDCC offer generated by Fexco
    example: a670ea4f-f390-46d8-9a90-6b1b99115708
  - baseAmountnumber (int)optional
    The base amount to convert
    example: 12345
  - exchangeRateobjectoptional
    uuidstringoptional
    An id of the eDCC offer's exchange rate object generated by Fexco
    example: c853d076-636e-4ea1-86e8-7c2d4e3e24e9
    baseCurrencyobjectoptional
    The currency to of the baseAmount
    alphaCodestringoptional
    The string currency code of the currency
    example: EUR
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 978
    ratenumber (float)optional
    The conversion rate used to convert the baseAmount to the foreignCurrency
    example: 1.1276
    foreignCurrencyobjectoptional
    The currency to convert the baseAmount to
    alphaCodestringoptional
    The string currency code of the currency
    example: USD
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 840
    marginPercentagenumber (int)optionalexample: 3
    commissionPercentagenumber (float)optionalexample: 0
    sourcestringoptionalexample: REUTERS WHOLESALE INTERBANK
    sourceTimestampnumber (date)optionalexample: 1454061545000
    expirynumber (date)optional
    The date time until the eDCC offer is valid
    example: 1618783200000
  - foreignAmountnumber (int)optional
    The foreign amount, to which the baseAmount is converted
    example: 13920
  - binobjectoptional
    numberstringoptional
    The 'bin' of the card passed as a parameter
    example: 411111
    currencyobjectoptional
    The currency of the card with the given 'bin'
    alphaCodestringoptional
    The string currency code of the currency
    example: USD
    minorUnitsnumber (int)optionalexample: 2
    numericCodenumber (int)optional
    The numeric currency code of the currency
    example: 840
    schemeCodenumber (int)optionalexample: 1
- 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
    example: merchant_vn9fklv2nb
  - transactionIdstringoptional
    The ID of the authorizing transaction, in which the eDCC offer is used
    example: transaction_mfxrtmqkku
  - cardTypestringoptional
    The brand of the card, used during the authorizing transaction
    example: VISA
  - cardNumberstringoptional
    The last four digits of the number of the card, used during the authorizing transaction
    example: ************1111
  - cardHolderNamestringoptional
    The card holder of the card, used during the authorizing transaction
    example: Max Mustermann

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

C#
PHP
Node
Shell

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

PREAUTH, DEBIT
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.
  
  physical, digital, discount, shipping_fee, gift_card
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)

MOTO, ECOM
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.
    example: customer-abc123
  - creationDatestring (date)optional
    The date when the customer opened the account with the merchant.
    example: 2019-07-10
  - 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.
    example: 2019-07-10
  - 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.
    
    CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: CHANGED_WITH_THIS_TRANSACTION
  - lastPasswordChangeDatestring (date)optional
    The date when the customer account with the merchant had a password change or account reset.
    example: 2019-07-10
  - passwordChangeIndicatorstringoptional
    Length of the time since the customer account information with the merchant had a password change or account reset.
    
    NO_CHANGE, CHANGED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
  - authenticationMethodstringoptional
    Mechanism used by the customer to authenticate to the merchant account.
    
    GUEST, OWN_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARTY_AUTH, FIDO_AUTHENTICATOR
    example: OWN_CREDENTIALS
  - authenticationTimestampstring (date-time)optional
    Date and time in UTC of the customer authentication to the merchant account.
    example: 2019-07-10T15:04:09.722Z
  - shippingAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the merchant account.
    
    FIRST_TIME, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
    example: LESS_THAN_THIRTY_DAYS
  - shippingAddressFirstUsagestring (date)optional
    Date when the shipping address used for this transaction was first used with the merchant.
    example: 2019-07-10
  - transactionCountLastDaynumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous 24 hours.
    example: 1
  - transactionCountLastYearnumberoptional
    Number of transactions (successful and abandoned) for this customer account with the merchant across all payment accounts in the previous year.
    example: 10
  - orderCountLast6Monthsnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    example: 5
  - suspiciousActivitybooleanoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the customer account.
    example: false
  - accountEqualsShippingNamebooleanoptional
    Indicates if the customer name on the account is identical to the shipping name used for this transaction.
    example: true
  - paymentAccountAgeIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the customer account with the merchant.
    
    NO_ACCOUNT, CREATED_WITH_THIS_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS
  - paymentAccountEnrollementDatestring (date)optional
    Date that the payment account was enrolled in the customer account with the merchant.
    example: 2019-07-10
- shippingInfoobjectoptional
  object containing information about the shipping details for this transaction.
  - shippingEqualsBillingAddressbooleanoptional
    Flag if the shipping address equals the billing address.
    example: true
  - 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.
    
    SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TICKETS_NOT_SHIPPED, OTHER
    example: SHIP_TO_BILLING_ADDRESS
  - deliveryTimestringoptional
    Indicates the merchandise delivery timeframe.
    
    ELECTRONIC, SAME_DAY, OVERNIGHT, TWO_DAY_OR_MORE
    example: SAME_DAY
  - deliveryEmailstringoptional
    For electronic delivery, the email address to which the merchandise was delivered.
    example: john@doe.com
- orderInfoobjectoptional
  object containing order information relevant for risk evaluation
  - isReorderbooleanoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: false
  - preOrderIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    
    MERCHANTDISE_AVAILABLE, FUTURE_AVAILABILITY
    example: MERCHANTDISE_AVAILABLE
  - preOrderDatestring (date)optional
    For a pre-ordered purchase, the expected date that the merchandise will be available.
    example: 2019-07-10
  - 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
    
    01, 03, 10, 11, 28
    example: 01

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
    
    PREAUTH, DEBIT, CANCEL, CAPTURE, REFUND
  - 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
    
    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
    DPD, GLS, DHL, HLG, HVS, UPS, TNT, OTH
  - 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.
  
  CREATED, OPEN, CLOSED
- channelstringrequired
  The channel determine the kind of origin for this order. (optional, mandatory for creditcard, ratepay-invoice, ratepay-directdebit and ratepay-installment)
  
  MOTO, ECOM
- 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.
    
    physical, digital, discount, shipping_fee, gift_card
- 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.
    
    MALE, FEMALE
    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)
    
    creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
    typestringrequired
    the type of the payment instrument
    
    sepa, creditcard, paypal, paydirekt, bank-transfer
    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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
    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.
    
    MALE, FEMALE
  - 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)
    
    creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
  - typestringrequired
    the type of the payment instrument
    
    sepa, creditcard, paypal, paydirekt, bank-transfer
  - 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
    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)
  
  creditcard, paypal, paydirekt, ratepay-invoice, ratepay-directdebit, ratepay-installment, sepa, sofort, klarna-pay-now, klarna-pay-later, klarna-slice-it, prepayment, giropay, eps, ideal, alipay, bancontact, wechat-pay, postfinance-card, payu, paysafecard, twint, union-pay
- 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
  
  PREAUTH, DEBIT
- 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.
    example: contract_123abc456x
    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.
    
    ONECLICK, UNSCHEDULED, SCHEDULED
    channelstringoptional
    The channel (entry mode) via which the COF initial storage transaction is processed. If not passed it defaults to ECOM.
    
    ECOM, MOTO
    example: 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.
    example: 2019-07-10
    recurringFrequencynumberoptional
    Indicates the minimum number of days between authorizations. This field is only required in case of an authentication for recurring payments.
    example: 30
  - 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.
    
    UNSCHEDULED, SCHEDULED
    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.
    example: 123456789012345
  - 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.
    example: 123456789012345
  - 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
    example: 2.0
    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
    
    Y, A, C, U, R, N
    example: Y
    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)
    example: https://link-the-hosted-challange.example
    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
    example: https://link-to-the-issuer.acs
    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)
    example: Y2hhbGxhbmdlRGF0YQ==
    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
    
    01, 02, 03, 04, 05
    example: 05
    transactionIdstringoptional
    The transaction identifier from the 3DS authentication 3DS 1.0: This will be the XID 3DS 2.0: This will be the dsTransID
    example: d00b8de2-a2e4-11e9-a2a3-2a2ae2dbcce4
    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
    example: YXV0aGVudGljYXRpb25WYWx1ZQ==
    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).
    example: 05
    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
    example: 01
    forceChallengebooleanoptional
    Flag to force challenge for 3ds v2
    example: true
    errorDetailsobjectoptional
    Object containing error information in case of error.
    providerCodestringoptional
    Original error code from the 3DS server or mpi
    example: 301
    providerMessagestringoptional
    Original error message from the 3DS server or mpi
    example: TRANSACTION_ID_NOT_RECOGNIZED
  - edccDataobjectoptional
    Details about the eDCC offer used in the order
    edccIdstringoptional
    The ID of the eDCC offer to be used for currency conversion
    example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
    foreignAmountnumber (int)optional
    The foreign amount, to which the baseAmount is converted
    example: 13920
    marginPercentagenumber (int)optionalexample: 3
    ratenumber (float)optional
    The conversion rate used to convert the baseAmount to the foreignCurrency
    example: 1.1276
    baseCurrencystringoptional
    The string currency code of the base currency
    example: EUR
    foreignCurrencystringoptional
    The string currency code of the foreign currency
    example: USD
  - 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.
    
    concardis, nets
  - 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>"
  
  TRANSACTION_PREAUTH_OK, TRANSACTION_PREAUTH_CREATED, TRANSACTION_PREAUTH_IN_PROGRESS, TRANSACTION_PREAUTH_PENDING, TRANSACTION_PREAUTH_FAILURE, TRANSACTION_PREAUTH_DECLINED, TRANSACTION_PREAUTH_ABORTED, TRANSACTION_PREAUTH_EXPIRED, TRANSACTION_CANCEL_OK, TRANSACTION_CANCEL_SUCCESS, TRANSACTION_CANCEL_CREATED, TRANSACTION_CANCEL_IN_PROGRESS, TRANSACTION_CANCEL_FAILURE, TRANSACTION_CANCEL_DECLINED, TRANSACTION_DEBIT_OK, TRANSACTION_DEBIT_SUCCESS, TRANSACTION_DEBIT_CREATED, TRANSACTION_DEBIT_IN_PROGRESS, TRANSACTION_DEBIT_PENDING, TRANSACTION_DEBIT_FAILURE, TRANSACTION_DEBIT_DECLINED, TRANSACTION_DEBIT_ABORTED, TRANSACTION_DEBIT_EXPIRED, TRANSACTION_CAPTURE_OK, TRANSACTION_CAPTURE_SUCCESS, TRANSACTION_CAPTURE_CREATED, TRANSACTION_CAPTURE_IN_PROGRESS, TRANSACTION_CAPTURE_FAILURE, TRANSACTION_CAPTURE_DECLINED, TRANSACTION_CAPTURE_EXPIRED, TRANSACTION_REFUND_OK, TRANSACTION_REFUND_SUCCESS, TRANSACTION_REFUND_CREATED, TRANSACTION_REFUND_IN_PROGRESS, TRANSACTION_REFUND_FAILURE, TRANSACTION_REFUND_DECLINED, TRANSACTION_CREDIT_OK, TRANSACTION_CREDIT_SUCCESS, TRANSACTION_CREDIT_CREATED, TRANSACTION_CREDIT_IN_PROGRESS, TRANSACTION_CREDIT_PENDING, TRANSACTION_CREDIT_FAILURE, TRANSACTION_CREDIT_ABORTED, TRANSACTION_CREDIT_DECLINED, TRANSACTION_CHARGEBACK_CHARGEBACK, TRANSACTION_CHARGEBACK_BOOKED, TRANSACTION_CHARGEBACK_LIFTED, TRANSACTION_CHARGEBACK_BOOKIN

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

C#
PHP
Node
Shell

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
    
    PREAUTH, DEBIT, CANCEL, CAPTURE, REFUND
    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
    
    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
    DPD, GLS, DHL, HLG, HVS, UPS, TNT, OTH
    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.
    
    CREATED, OPEN, CLOSED
  - channelstringrequired
    The channel determine the kind of origin for this order. (optional, mandatory for creditcard, ratepay-invoice, ratepay-directdebit and ratepay-installment)
    
    MOTO, ECOM
  - 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
    articleTy