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
    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
- totalPagesnumber (int)required
  A counter for the total pages returned.

200

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

Get order

GET /orders/{orderId}

Endpoint to receive a specific order referencing the orderId.

The returned order object includes all details and transactions of the whole lifecycle of the order.

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)
orderIdstringrequired
ID of the specific order.

Get order

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}");
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
    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
- totalPagesnumber (int)required
  A counter for the total pages returned.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while loading order!
- codenumberoptionalexample: 12001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Update order

PATCH /orders/{orderId}

Endpoint to update an order intent referencing the orderId.

This service can be used for updating order details as long as the order is still in status CREATED.

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)
orderIdstringrequired
ID of the specific order.

Update order

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}");
var request = new RestRequest(Method.PATCH);
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

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.
initialAmountnumber (int)optional
Amount as smallest currency unit e.g 100 EUR will be result in amount = 10000
currencystringoptional
Currency code according to https://en.wikipedia.org/wiki/ISO_4217
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.
asyncobjectoptional
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
allowedProductsarrayoptional
A List of all valid products for this order.
transactionTypestringoptional
The type of the underlying Transaction

PREAUTH, DEBIT
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
executeOrderbooleanoptional
Paypal specific parameter. If true the order will be processed after the update. This property is used to finish the processing of order, when the Paypal debit or preauth is created with 'addressOverride=false'. Defaut is false.
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.

Request body

{
    "terms": 0,
    "privacy": 0,
    "merchantOrderId": "string",
    "description": "string",
    "statementDescription": "string",
    "initialAmount": 1,
    "currency": "str",
    "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",
    "async": {
        "successUrl": "string",
        "failureUrl": "string",
        "cancelUrl": "string",
        "confirmUrl": "string",
        "notifications": [
            {
                "notificationUrn": "string",
                "notificationEvent": [
                    "string"
                ],
                "notificationVersion": "string"
            }
        ]
    },
    "allowedProducts": [
        "creditcard"
    ],
    "transactionType": "PREAUTH",
    "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"
        }
    },
    "executeOrder": true,
    "locale": "string"
}

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

Create preauth transaction

POST /orders/preauth

Endpoint to create a preauth transaction. A preauth transaction only authorizes a payment and for certain methods also reserves the authorized amount. However no cash flow will be triggered as long as no corresponding capture transaction is initiated at a later stage.

There are 2 workflows to process a preauth: ASYNC and SYNC.

With SYNC payment methods the transaction will directly result in a OK/SUCCESS or a negative status. With ASYNC payment methods the transaction will result in a PENDING or FAILURE/DECLINED/ABORTED status.

The integrating system needs to redirect the shopper to the redirectUrl After the shopper completes the payment action the transaction status will change accordingly and the integrator can query the updated status.

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 preauth transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/preauth");
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
productstringrequired
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
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
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.
paymentobjectoptional
Additional information Payment needed to proceed the order.
- paymentInstrumentIdstringoptional
  An ID of an already created paymentinstrument. Used to proceed the order. (optional)
  example: paymentinstrument_123abcdef5
- uniqueIdstringoptional
  An unique ID of a concrete tokenized card. Used to proceed POS orders. (optional)
- cardNumberstringoptional
  The Creditcard PAN used to proceed. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)
- 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 bank account.
  example: Deutsche Bank
- ibanstringoptional
  IBAN of the bank account. (mandatory for sepa, optional if a sepa paymentInstrumentId was passed)
- bicstringoptional
  BIC of the bank account. (mandatory for sepa payments with a non german iban, optional if a sepa paymentInstrumentId was passed optional for ideal and sofort-collecting)
  example: DE15111111111111111199
- 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: Deutsche Bank
- deferredbooleanoptional
  Indicates if the order should be deferred. (only available for paypal preauth/execute, optional)
- numberOfRatesintegeroptional
  Number of rates for ratepay installment
- rateintegeroptional
  Rate for ratepay installment
- lastRateintegeroptional
  Last rate for ratepay installment
- interestRatenumberoptional
  Interest rate for ratepay installment
- totalAmountintegeroptional
  Total amount for ratepay installment
- initializeCustomerTokenizationbooleanoptional
  Only for Klarna preauth or debit. True if we want to create token and next orders will be as recurring, false otherwise. Organization customers can't use initializeCustomerTokenization.
- 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
- riskIdentIdstringoptional
  Only for RatePay preauth or debit.
- countryCodestringoptional
  Mandatory parameter for Paysafecard Optional parameter for WeChat Pay, Union Pay and Sofort Collecting via PPRO debit. The 2-letter ISO country code of the country in which the payment instrument is issued/operated (e.g. DE) Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]
- compliantEmailstringoptional
  Optional parameter only for PayU via PPRO debit. RFC compliant email address of the account holder.
- createRecurringBillingAgreementbooleanoptional
  Only for paypal. Indicates if the payment is recurring.
- cofContractobjectoptional
  - 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
  - recurringExpirystring (date)optional
    Date after which no further authorizations shall be performed. This field is limited to 8 characters, and the
  - recurringFrequencyintegeroptional
    Indicates the minimum number of days between authorizations. The field is limited to maximum 4 characters.
- displayLanguagestringoptional
  Only for postfinance-card. This field is mandatory and contains the language of the shopper with possible values de, fr, it, en.
- displayMobileScreenbooleanoptional
  Only for postfinance-card. This field is optional and it determines if it's used normal device with "false" value or smartphone with "true" as value. The default the value is "false".
deviceIdentobjectoptional
- deviceIdentTokenstringoptional
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 specific information for different payment methods.
- 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
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- threeDsDataobjectoptional
  - threeDsAuthenticationIdstringoptional
    Id of successfull 3DS authentication
    example: authentication_abc123xyz9
  - browserInfoIdstringoptional
    Payengine identifier of the browser info object
    example: browserInfo_e1f6b193df
  - threeDsVersionIdstringoptional
    Payengine identifier of the 3DS version object
    example: threedsversion_123abc456z
  - versionstringoptional
    Parameter indicating the version of the 3DS
    example: 2.0
  - 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: 8a880dc0-d2d2-4067-bcb1-b08d1690b26e
  - authenticationValuestringoptional
    The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard
    example: MTIzNDU2Nzg5MDA5ODc2NTQzMjE=
  - 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
  - forceChallengebooleanoptional
    Flag to force challenge for 3ds v2
    example: true
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS creditcard orders.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS creditcard orders.
  example: true
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
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": 1,
    "currency": "str",
    "product": "creditcard",
    "async": {
        "successUrl": "string",
        "failureUrl": "string",
        "cancelUrl": "string",
        "confirmUrl": "string",
        "notifications": [
            {
                "notificationUrn": "string",
                "notificationEvent": [
                    "string"
                ],
                "notificationVersion": "string"
            }
        ]
    },
    "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",
    "payment": {
        "paymentInstrumentId": "paymentinstrument_123abcdef5",
        "uniqueId": "stringstringstringstringst",
        "cardNumber": "stringstring",
        "verification": "stri",
        "expiryMonth": "st",
        "expiryYear": "st",
        "cardHolder": "string",
        "bankName": "Deutsche Bank",
        "iban": "string",
        "bic": "DE15111111111111111199",
        "accountHolder": "Deutsche Bank",
        "deferred": true,
        "numberOfRates": 0,
        "rate": 0,
        "lastRate": 0,
        "interestRate": 0,
        "totalAmount": 0,
        "initializeCustomerTokenization": true,
        "mandate": {
            "mandateId": "string",
            "createdDateTime": 0,
            "mandateText": "string",
            "directDebitType": "FIRST"
        },
        "riskIdentId": "string",
        "countryCode": "st",
        "compliantEmail": "string",
        "createRecurringBillingAgreement": true,
        "cofContract": {
            "id": "contract_123abc456x",
            "type": "ONECLICK",
            "recurringExpiry": "2019-08-24",
            "recurringFrequency": 1
        },
        "displayLanguage": "string",
        "displayMobileScreen": true
    },
    "deviceIdent": {
        "deviceIdentToken": "string"
    },
    "tracking": [
        {
            "trackingId": "string",
            "provider": "DPD"
        }
    ],
    "meta": {
        "externalCofData": {
            "type": "UNSCHEDULED",
            "initialSchemeTraceId": "123456789012345"
        },
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "threeDsData": {
            "threeDsAuthenticationId": "authentication_abc123xyz9",
            "browserInfoId": "browserInfo_e1f6b193df",
            "threeDsVersionId": "threedsversion_123abc456z",
            "version": "2.0",
            "transactionId": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
            "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
            "eci": "05",
            "forceChallenge": true
        },
        "terminalId": "69038411",
        "printerReady": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis"
    },
    "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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/preauth
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Create debit transaction

POST /orders/debit

Endpoint to create a debit transaction.

The debit transaction authorizes the payment and triggers the cash flow as the money will be debited from the end customer account.

No further capture transaction is required anymore afterwards.

There are 2 workflows to process a debit: ASYNC and SYNC.

With SYNC payment methods the transaction will directly result in a OK/SUCCESS or a negative status.

With ASYNC payment methods the transaction will result in a PENDING or FAILURE/DECLINED/ABORTED status.

If the status of the transaction is in PENDING the response will contain a redirectUrl.

The integrating system needs to redirect the shopper to the redirectUrl.

After the shopper completes the payment action the transaction status will change accordingly and the integrator can query the updated status.

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 debit transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/debit");
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
productstringrequired
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
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
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.
paymentobjectoptional
Additional information Payment needed to proceed the order.
- paymentInstrumentIdstringoptional
  An ID of an already created paymentinstrument. Used to proceed the order. (optional)
  example: paymentinstrument_123abcdef5
- uniqueIdstringoptional
  An unique ID of a concrete tokenized card. Used to proceed POS orders. (optional)
- cardNumberstringoptional
  The Creditcard PAN used to proceed. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)
- 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 bank account.
  example: Deutsche Bank
- ibanstringoptional
  IBAN of the bank account. (mandatory for sepa, optional if a sepa paymentInstrumentId was passed)
- bicstringoptional
  BIC of the bank account. (mandatory for sepa payments with a non german iban, optional if a sepa paymentInstrumentId was passed optional for ideal and sofort-collecting)
  example: DE15111111111111111199
- 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: Deutsche Bank
- deferredbooleanoptional
  Indicates if the order should be deferred. (only available for paypal preauth/execute, optional)
- numberOfRatesintegeroptional
  Number of rates for ratepay installment
- rateintegeroptional
  Rate for ratepay installment
- lastRateintegeroptional
  Last rate for ratepay installment
- interestRatenumberoptional
  Interest rate for ratepay installment
- totalAmountintegeroptional
  Total amount for ratepay installment
- initializeCustomerTokenizationbooleanoptional
  Only for Klarna preauth or debit. True if we want to create token and next orders will be as recurring, false otherwise. Organization customers can't use initializeCustomerTokenization.
- 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
- riskIdentIdstringoptional
  Only for RatePay preauth or debit.
- countryCodestringoptional
  Mandatory parameter for Paysafecard Optional parameter for WeChat Pay, Union Pay and Sofort Collecting via PPRO debit. The 2-letter ISO country code of the country in which the payment instrument is issued/operated (e.g. DE) Format [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]
- compliantEmailstringoptional
  Optional parameter only for PayU via PPRO debit. RFC compliant email address of the account holder.
- createRecurringBillingAgreementbooleanoptional
  Only for paypal. Indicates if the payment is recurring.
- cofContractobjectoptional
  - 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
  - recurringExpirystring (date)optional
    Date after which no further authorizations shall be performed. This field is limited to 8 characters, and the
  - recurringFrequencyintegeroptional
    Indicates the minimum number of days between authorizations. The field is limited to maximum 4 characters.
- displayLanguagestringoptional
  Only for postfinance-card. This field is mandatory and contains the language of the shopper with possible values de, fr, it, en.
- displayMobileScreenbooleanoptional
  Only for postfinance-card. This field is optional and it determines if it's used normal device with "false" value or smartphone with "true" as value. The default the value is "false".
deviceIdentobjectoptional
- deviceIdentTokenstringoptional
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 specific information for different payment methods.
- 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
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- threeDsDataobjectoptional
  - threeDsAuthenticationIdstringoptional
    Id of successfull 3DS authentication
    example: authentication_abc123xyz9
  - browserInfoIdstringoptional
    Payengine identifier of the browser info object
    example: browserInfo_e1f6b193df
  - threeDsVersionIdstringoptional
    Payengine identifier of the 3DS version object
    example: threedsversion_123abc456z
  - versionstringoptional
    Parameter indicating the version of the 3DS
    example: 2.0
  - 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: 8a880dc0-d2d2-4067-bcb1-b08d1690b26e
  - authenticationValuestringoptional
    The authenticationValue returned in the 3DS authentication CAVV: Visa, AMEX, JCB, Diners/Discover UCAF: Mastercard
    example: MTIzNDU2Nzg5MDA5ODc2NTQzMjE=
  - 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
  - forceChallengebooleanoptional
    Flag to force challenge for 3ds v2
    example: true
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS creditcard orders.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS creditcard orders.
  example: true
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
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": 1,
    "currency": "str",
    "product": "creditcard",
    "async": {
        "successUrl": "string",
        "failureUrl": "string",
        "cancelUrl": "string",
        "confirmUrl": "string",
        "notifications": [
            {
                "notificationUrn": "string",
                "notificationEvent": [
                    "string"
                ],
                "notificationVersion": "string"
            }
        ]
    },
    "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",
    "payment": {
        "paymentInstrumentId": "paymentinstrument_123abcdef5",
        "uniqueId": "stringstringstringstringst",
        "cardNumber": "stringstring",
        "verification": "stri",
        "expiryMonth": "st",
        "expiryYear": "st",
        "cardHolder": "string",
        "bankName": "Deutsche Bank",
        "iban": "string",
        "bic": "DE15111111111111111199",
        "accountHolder": "Deutsche Bank",
        "deferred": true,
        "numberOfRates": 0,
        "rate": 0,
        "lastRate": 0,
        "interestRate": 0,
        "totalAmount": 0,
        "initializeCustomerTokenization": true,
        "mandate": {
            "mandateId": "string",
            "createdDateTime": 0,
            "mandateText": "string",
            "directDebitType": "FIRST"
        },
        "riskIdentId": "string",
        "countryCode": "st",
        "compliantEmail": "string",
        "createRecurringBillingAgreement": true,
        "cofContract": {
            "id": "contract_123abc456x",
            "type": "ONECLICK",
            "recurringExpiry": "2019-08-24",
            "recurringFrequency": 1
        },
        "displayLanguage": "string",
        "displayMobileScreen": true
    },
    "deviceIdent": {
        "deviceIdentToken": "string"
    },
    "tracking": [
        {
            "trackingId": "string",
            "provider": "DPD"
        }
    ],
    "meta": {
        "externalCofData": {
            "type": "UNSCHEDULED",
            "initialSchemeTraceId": "123456789012345"
        },
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "threeDsData": {
            "threeDsAuthenticationId": "authentication_abc123xyz9",
            "browserInfoId": "browserInfo_e1f6b193df",
            "threeDsVersionId": "threedsversion_123abc456z",
            "version": "2.0",
            "transactionId": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
            "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
            "eci": "05",
            "forceChallenge": true
        },
        "terminalId": "69038411",
        "printerReady": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis"
    },
    "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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/debit
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Create credit transaction

POST /orders/credit

Endpoint to create a credit transaction. Initialise a transaction and book an amount. The creditor is the customer and the debitor is the merchant. Credit transaction is always processed synchronously, 'channel' has to be MOTO.

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 credit transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/credit");
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
productstringrequired
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
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.
paymentobjectoptional
Additional information Payment needed to proceed the order.
- paymentInstrumentIdstringoptional
  An ID of an already created paymentinstrument. Used to proceed the order. (optional)
  example: paymentinstrument_123abcdef5
- cardNumberstringoptional
  The Creditcard PAN used to proceed. (mandatory for creditcard, optional if a creditcard paymentInstrumentId was passed)
- 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.
- deferredbooleanoptional
  Indicates if the order should be deferred. (only available for paypal preauth/execute, optional)
- emailSubjectstringoptional
  Only for paypal. The subject line of the email that PayPal sends when the transaction is completed. The emailSubject must follow the following pattern '^(\p{L}|\s|\d)*$'
- receiverTypestringoptional
  Only for paypal. Indicates how you identify the recipients of payments in this call to MassPay. Must be either 'EmailAddress', 'PhoneNumber', or 'UserID'.
- receiverEmailstringoptional
  Only for paypal. Email address of recipient. Mandatory if receiverType is EmailAddress.
- receiverPhonestringoptional
  Only for paypal. Mobile phone number of recipient. Mandatory if receiverType is PhoneNumber. The receiverPhone must follow the following pattern '^\s*+?(\d|-|\s|/){1,16}$'
- receiverIdstringoptional
  Only for paypal. Unique PayPal customer account number. Mandatory if receiverType is UserID.
- createRecurringBillingAgreementbooleanoptional
  Only for paypal. Indicates if the payment is recurring.
- 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
deviceIdentobjectoptional
- deviceIdentTokenstringoptional
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.
metaobjectoptional
- instantbooleanoptional
  Indicator if the credit should be instant e.g. visa oct

Request body

{
    "initialAmount": 1,
    "currency": "str",
    "product": "creditcard",
    "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",
    "payment": {
        "paymentInstrumentId": "paymentinstrument_123abcdef5",
        "cardNumber": "stringstring",
        "verification": "stri",
        "expiryMonth": "st",
        "expiryYear": "st",
        "cardHolder": "string",
        "deferred": true,
        "emailSubject": "string",
        "receiverType": "string",
        "receiverEmail": "string",
        "receiverPhone": "string",
        "receiverId": "string",
        "createRecurringBillingAgreement": true,
        "bankName": "Deutsche Bank",
        "iban": "DE15111111111111111199",
        "bic": "DEUTDEDBKOE",
        "accountHolder": "Max Muster"
    },
    "deviceIdent": {
        "deviceIdentToken": "string"
    },
    "locale": "string",
    "meta": {
        "instant": true
    }
}

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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/credit
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Create cancel transaction

POST /orders/{orderId}/transactions/{transactionId}/cancel

Endpoint to create a cancelation a preauth transaction referencing the corresponding orderId and transactionId.

A cancel transaction can only be applied to a non expired preauth transaction that is in status SUCCESS. Partial cancelations are supported but the initialAmount cannot be higher than the amount that was authorized

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)
orderIdstringrequired
ID of the affected order.
transactionIdstringrequired
ID of the affected transaction. note: it must be a preauth.

Create cancel transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions/%7BtransactionId%7D/cancel");
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
descriptionstringoptional
The description from your system/shop of this transaction.
basketarrayoptional
The basket of your transaction. (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
metaobjectoptional
Contains specific information for different payment methods.
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS Auth UP operation.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS Auth UP operation.
  example: true

Request body

{
    "initialAmount": 0,
    "currency": "str",
    "description": "string",
    "basket": [
        {
            "name": "string",
            "articleNumber": "string",
            "totalPrice": -1000000000000000000,
            "totalPriceWithTax": -1000000000000000000,
            "unitPrice": -1000000000000000000,
            "unitPriceWithTax": -1000000000000000000,
            "tax": 100,
            "quantity": 1,
            "discount": -1000000000000000000,
            "articleType": "physical"
        }
    ],
    "meta": {
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis",
        "terminalId": "69038411",
        "printerReady": true
    }
}

Responses

200Successful response.optional
- 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.
- orderobjectrequired
  - 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
- transactionsarrayrequired
  A list of 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
- parentTransactionobjectrequired
  - 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
- 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
- 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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions/transaction_asdfghjk/cancel
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "type": "PREAUTH",
    "transactionId": "string",
    "status": "CREATED",
    "initialAmount": 1,
    "currency": "str",
    "description": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "order": {
        "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"
    },
    "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"
            }
        }
    ],
    "parentTransaction": {
        "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"
        }
    },
    "descriptor": "string",
    "capturedAmount": 1,
    "refundedAmount": 1,
    "canceledAmount": 1,
    "challange": {
        "title": "string",
        "label": "string",
        "format": "string",
        "data": "string"
    },
    "meta": {
        "tanSent": true,
        "tanSchema": "string"
    }
}

Create capture transaction

POST /orders/{orderId}/transactions/{transactionId}/capture

Endpoint to capture a preauth transaction referencing the corresponding orderId and transactionId.

A capture transaction can only be applied to a non expired preauth transaction that is in status SUCCESS. Partial captures are supported but the initialAmount cannot be higher than the amount that was authorized.

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)
orderIdstringrequired
ID of the affected order.
transactionIdstringrequired
ID of the affected transaction. note: it must be a preauth.

Create capture transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions/%7BtransactionId%7D/capture");
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
descriptionstringoptional
The description from your system/shop of this transaction.
basketarrayoptional
The basket of your transaction. (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
metaobjectoptional
Contains specific information for different payment methods.
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS Auth UP operation.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS Auth UP operation.
  example: true

Request body

{
    "initialAmount": 0,
    "currency": "str",
    "description": "string",
    "basket": [
        {
            "name": "string",
            "articleNumber": "string",
            "totalPrice": -1000000000000000000,
            "totalPriceWithTax": -1000000000000000000,
            "unitPrice": -1000000000000000000,
            "unitPriceWithTax": -1000000000000000000,
            "tax": 100,
            "quantity": 1,
            "discount": -1000000000000000000,
            "articleType": "physical"
        }
    ],
    "meta": {
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis",
        "terminalId": "69038411",
        "printerReady": true
    }
}

Responses

200Successful response.optional
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions/transaction_asdfghjk/capture
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

400

{
    "path": "v1/orders/order_asdfghjk/transactions/transaction_asdfghjk/capture",
    "timestamp": 1603275671582,
    "status": 400,
    "message": "Error while creating order!",
    "code": 12000,
    "globalTrackId": "Some Request ID",
    "errors": [
        [
            {
                "code": 12200,
                "field": "initialAmount",
                "message": "Field initialAmount is missing.  Expected: Positive integer between 1 and 999999999999999999."
            },
            {
                "code": 12201,
                "field": "initialAmount",
                "message": "Bad value for initialAmount. Expected: Positive integer between 1 and 999999999999999999."
            },
            {
                "code": 12202,
                "field": "currency",
                "message": "Field currency is missing. Expected: string value in ['EUR']."
            },
            {
                "code": 12203,
                "field": "currency",
                "message": "Bad value for currency. Expected: string value in ['EUR']."
            },
            {
                "code": 12217,
                "field": "description",
                "message": "Bad value for description. Expected: string of length between 1 and 128."
            },
            {
                "code": 12219,
                "field": "basket",
                "message": "Field basket is missing. Expected: array of type Item."
            },
            {
                "code": 12220,
                "field": "basket",
                "message": "Bad value for basket. Expected: array of type Item."
            },
            {
                "code": 12221,
                "field": "basket.item.name",
                "message": "Field basket.item.name is missing. Expected: string of length between 1 and 128."
            },
            {
                "code": 12222,
                "field": "basket.item.name",
                "message": "Bad value for basket.item.name. Expected: string of length between 1 and 128."
            },
            {
                "code": 12223,
                "field": "basket.item.articleNumber",
                "message": "Field basket.item.articleNumber is missing. Expected: string of length between 1 and 255."
            },
            {
                "code": 12224,
                "field": "basket.item.articleNumber",
                "message": "Bad value for basket.item.articleNumber. Expected: string of length between 1 and 255."
            },
            {
                "code": 12225,
                "field": "basket.item.totalPrice",
                "message": "Field basket.item.totalPrice is missing. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12226,
                "field": "basket.item.totalPrice",
                "message": "Bad value for basket.item.totalPrice. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12227,
                "field": "basket.item.totalPriceWithTax",
                "message": "Field basket.item.totalPriceWithTax is missing. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12228,
                "field": "basket.item.totalPriceWithTax",
                "message": "Bad value for basket.item.totalPriceWithTax. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12229,
                "field": "basket.item.tax",
                "message": "Field basket.item.tax is missing. Expected: positive integer between 1 and 100."
            },
            {
                "code": 12230,
                "field": "basket.item.tax",
                "message": "Bad value for basket.item.tax. Expected: positive integer between 1 and 100."
            },
            {
                "code": 12231,
                "field": "basket.item.unitPrice",
                "message": "Field basket.item.unitPrice is missing. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12232,
                "field": "basket.item.unitPrice",
                "message": "Bad value for basket.item.unitPrice. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12233,
                "field": "basket.item.unitPriceWithTax",
                "message": "Field basket.item.unitPriceWithTax is missing. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12234,
                "field": "basket.item.unitPriceWithTax",
                "message": "Bad value for basket.item.unitPriceWithTax. Expected: Integer between -999999999999999998 and 999999999999999999."
            },
            {
                "code": 12235,
                "field": "basket.item.quantity",
                "message": "Field basket.item.quantity is missing. Expected: positive integer between 1 and 9999999."
            },
            {
                "code": 12236,
                "field": "basket.item.quantity",
                "message": "Bad value for basket.item.quantity. Expected: positive integer between 1 and 9999999."
            }
        ]
    ]
}

Create refund transaction

POST /orders/{orderId}/transactions/{transactionId}/refund

Endpoint to refund a capture transaction referencing the corresponding orderId and transactionId.

A refund transaction can only be applied to a capture transaction that is in status SUCCESS. Partial refunds are supported but the initialAmount cannot be higher than the amount that was captured.

In case refunds for sepa/sofort/prepayment are executed using the online bank transfer feature the refund will result in the status PENDING.

The transaction response will contain a challenge element with the TAN instructions.

The TAN needs to be transmitted in subsequent request. See "PATCH /orders/{orderId}/transactions/{transactionId}"

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)
orderIdstringrequired
ID of the affected order.
transactionIdstringrequired
ID of the affected transaction. note: it must be a capture or a debit.

Create refund transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions/%7BtransactionId%7D/refund");
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
descriptionstringoptional
The description from your system/shop of this transaction.
basketarrayoptional
The basket of your transaction. (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
metaobjectoptional
Contains specific information for different payment methods.
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS Auth UP operation.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS Auth UP operation.
  example: true

Request body

{
    "initialAmount": 0,
    "currency": "str",
    "description": "string",
    "basket": [
        {
            "name": "string",
            "articleNumber": "string",
            "totalPrice": -1000000000000000000,
            "totalPriceWithTax": -1000000000000000000,
            "unitPrice": -1000000000000000000,
            "unitPriceWithTax": -1000000000000000000,
            "tax": 100,
            "quantity": 1,
            "discount": -1000000000000000000,
            "articleType": "physical"
        }
    ],
    "meta": {
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis",
        "terminalId": "69038411",
        "printerReady": true
    }
}

Responses

200Successful response.optional
- 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.
- orderobjectrequired
  - 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
- transactionsarrayrequired
  A list of 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
- parentTransactionobjectrequired
  - 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
- 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
- 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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions/transaction_asdfghjk/refund
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating order!
- codenumberoptionalexample: 12000
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "type": "PREAUTH",
    "transactionId": "string",
    "status": "CREATED",
    "initialAmount": 1,
    "currency": "str",
    "description": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "order": {
        "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"
    },
    "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"
            }
        }
    ],
    "parentTransaction": {
        "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"
        }
    },
    "descriptor": "string",
    "capturedAmount": 1,
    "refundedAmount": 1,
    "canceledAmount": 1,
    "challange": {
        "title": "string",
        "label": "string",
        "format": "string",
        "data": "string"
    },
    "meta": {
        "tanSent": true,
        "tanSchema": "string"
    }
}

Get transaction

GET /orders/{orderId}/transactions/{transactionId}

Endpoint to receive a specific transaction referencing the orderId and transactionId.

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)
orderIdstringrequired
ID of the affected order.
transactionIdstringrequired
ID of the specific transaction.

Get transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions/%7BtransactionId%7D");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- 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.
- orderobjectrequired
  - 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
- transactionsarrayrequired
  A list of 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
- parentTransactionobjectrequired
  - 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
- 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
- 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
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions/transaction_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while loading transaction!
- codenumberoptionalexample: 14001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "type": "PREAUTH",
    "transactionId": "string",
    "status": "CREATED",
    "initialAmount": 1,
    "currency": "str",
    "description": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "order": {
        "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"
    },
    "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"
            }
        }
    ],
    "parentTransaction": {
        "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"
        }
    },
    "descriptor": "string",
    "capturedAmount": 1,
    "refundedAmount": 1,
    "canceledAmount": 1,
    "challange": {
        "title": "string",
        "label": "string",
        "format": "string",
        "data": "string"
    },
    "meta": {
        "tanSent": true,
        "tanSchema": "string"
    }
}

Update order transaction

PATCH /orders/{orderId}/transactions/{transactionId}

Endpoint to update a specific transaction referencing the orderId and transactionId.

The service can be used for updating preauth transactions for ratepay-invoice, ratepay-directdebit or ratepay-installment that have not been captured yet.

The service can also be used for updating the TAN for refund transactions using the online bank transfer feature for sepa/sofort/prepayment that are in status PENDING.

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)
orderIdstringrequired
ID of the affected order.
transactionIdstringrequired
ID of the specific transaction.

Update order transaction

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions/%7BtransactionId%7D");
var request = new RestRequest(Method.PATCH);
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
descriptionstringoptional
The description from your system/shop of this transaction.
basketarrayoptional
The basket of your transaction. (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
metaobjectoptional
Contains specific information for different payment methods.
- invoicingobjectoptional
  - invoiceIdstringoptional
    Merchant supplied unique reference on transaction level. Valid for PayPal and Creditcard only. For Creditcard minLength is limited to 30 characters.
  - invoiceDateintegeroptional
    Timestamp - earliest - 7 days before request, latest - day of request. Valid for PayPal only.
  - deliveryDateintegeroptional
    Timestamp - earliest - 365 days before request, latest - 365 days after request. Valid for PayPal only.
  - dueDateintegeroptional
    Timestamp - not before date of request AND not before invoice-date (if present). Valid for PayPal only.
- preferredLanguagestringoptional
  Works with RatePay, iDEAL, Alipay, Bancontact, Union Pay and WeChat Pay. Two-letter language code, lower case.
- referenceIdstringoptional
  RatePAY specific parameter.
- addressOverridebooleanoptional
  Paypal specific parameter. If false the shipping address passed with the request will be editable on the paypal site. Default value is true.
- fraudNetIdstringoptional
  Paypal specific parameter. Verifies that the payment originates from a valid, user-consented device and application.
- tanstringoptional
  Second factor for online bank transfer based refunds
- mobileViewbooleanoptional
  Set to true for the mobile enabled variant of Alipay.
- edccIdstringoptional
  The ID of the eDCC offer to be used for currency conversion. Applicable only for credit card orders
  example: Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20
- 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
- terminalIdstringoptional
  The terminalId of the POS terminal, mandatory for POS Auth UP operation.
  example: 69038411
- printerReadybooleanoptional
  Indicates if the receipt printer is ready to use, mandatory for POS Auth UP operation.
  example: true

Request body

{
    "initialAmount": 0,
    "currency": "str",
    "description": "string",
    "basket": [
        {
            "name": "string",
            "articleNumber": "string",
            "totalPrice": -1000000000000000000,
            "totalPriceWithTax": -1000000000000000000,
            "unitPrice": -1000000000000000000,
            "unitPriceWithTax": -1000000000000000000,
            "tax": 100,
            "quantity": 1,
            "discount": -1000000000000000000,
            "articleType": "physical"
        }
    ],
    "meta": {
        "invoicing": {
            "invoiceId": "string",
            "invoiceDate": 0,
            "deliveryDate": 0,
            "dueDate": 0
        },
        "preferredLanguage": "st",
        "referenceId": "string",
        "addressOverride": true,
        "fraudNetId": "string",
        "tan": "string",
        "mobileView": true,
        "edccId": "Edcc-cbc6ffd8-6417-49ee-92c1-121fe1e19b20",
        "cardAcquirerRoutingTo": "concardis",
        "terminalId": "69038411",
        "printerReady": true
    }
}

Responses

200Successful response.optional
- 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.
- orderobjectrequired
  - 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
- transactionsarrayrequired
  A list of 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
- parentTransactionobjectrequired
  - 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
- 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
- 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
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions/transaction_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while updating transaction!
- codenumberoptionalexample: 14002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "type": "PREAUTH",
    "transactionId": "string",
    "status": "CREATED",
    "initialAmount": 1,
    "currency": "str",
    "description": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "order": {
        "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"
    },
    "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"
            }
        }
    ],
    "parentTransaction": {
        "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"
        }
    },
    "descriptor": "string",
    "capturedAmount": 1,
    "refundedAmount": 1,
    "canceledAmount": 1,
    "challange": {
        "title": "string",
        "label": "string",
        "format": "string",
        "data": "string"
    },
    "meta": {
        "tanSent": true,
        "tanSchema": "string"
    }
}

Get list of order transactions

GET /orders/{orderId}/transactions

Endpoint to receive a list of all available transactions of an orders referencing the orderId.

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)
orderIdstringrequired
ID of the affected order.

Get list of order transactions

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/orders/{orderId}/transactions");
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 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.
  - orderobjectrequired
    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
  - transactionsarrayrequired
    A list of 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
  - parentTransactionobjectrequired
    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
  - 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
  - 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
- totalPagesnumber (int)required
  A counter for the total pages returned.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/orders/order_asdfghjk/transactions
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while loading transaction!
- codenumberoptionalexample: 14001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "elements": [
        {
            "type": "PREAUTH",
            "transactionId": "string",
            "status": "CREATED",
            "initialAmount": 1,
            "currency": "str",
            "description": "string",
            "createdAt": 0,
            "modifiedAt": 0,
            "order": {
                "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"
            },
            "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"
                    }
                }
            ],
            "parentTransaction": {
                "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"
                }
            },
            "descriptor": "string",
            "capturedAmount": 1,
            "refundedAmount": 1,
            "canceledAmount": 1,
            "challange": {
                "title": "string",
                "label": "string",
                "format": "string",
                "data": "string"
            },
            "meta": {
                "tanSent": true,
                "tanSchema": "string"
            }
        }
    ],
    "totalPages": 1
}

Create customer

POST /customers

Endpoint to create a new customer returning a unique customerId.

A customer object acts as a container for customer specific personas and addresses.

If the email address or the merchantCustomerId of the given customer is already known to the platform the service will respond with HTTP status 200 OK. For every newly created customer service will respond with the HTTP status 201 CREATED

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 customer

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers");
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

emailstring (email)required
The customers email address. unique. Mandatory for the products 'klarna-pay-now', 'klarna-pay-later', 'klarna-slice-it, sepa'
merchantCustomerIdstringoptional
The identifier of the customer. Created by you.
customerTypestringoptional
Customer type. Specified as "organization" for companies and organizations. Mandatory for b2b customers.
organizationRegistrationIdstringoptional
Organization registration id. Only applicable for organization customer types.
organizationVatIdstringoptional
Organization VAT id. Only used for organization customer types.
organizationRegistrationRegisterstringoptional
Organization registers can be the court name that registered the company. The registry location name, or another other organization registering institution name. This field is optional.
organizationEntityTypestringoptional
Customers that are organizations use this to specify their entity type. Klarna B2B specific organizationEntityType : LIMITED_COMPANY PUBLIC_LIMITED_COMPANY ENTREPRENEURIAL_COMPANY LIMITED_PARTNERSHIP_LIMITED_COMPANY LIMITED_PARTNERSHIP GENERAL_PARTNERSHIP REGISTERED_SOLE_TRADER SOLE_TRADER CIVIL_LAW_PARTNERSHIP PUBLIC_INSTITUTION OTHER RatePAY B2B specific organizationEntityType : GMBH GMBH-I-GR GGMBH GMBH-CO-KG OHG KG EV EG AG UG UG-I-GR EINZELUNTERNEHMER EK PARTNERSCHAFT PUBLIC_INSTITUTION GBR AOR KOR STIFTUNG OTHER SE SCE OG OEG KEG CH_EINZELUNTERNEHMER EINFACHE-GESELLSCHAFT KOLLEKTIVGESELLSCHAFT

LIMITED_COMPANY, PUBLIC_LIMITED_COMPANY, ENTREPRENEURIAL_COMPANY, LIMITED_PARTNERSHIP_LIMITED_COMPANY, LIMITED_PARTNERSHIP, GENERAL_PARTNERSHIP, REGISTERED_SOLE_TRADER, SOLE_TRADER, CIVIL_LAW_PARTNERSHIP, PUBLIC_INSTITUTION, GMBH, GMBH-I-GR, GGMBH, GMBH-CO-KG, OHG, KG, EV, EG, AG, UG, UG-I-GR, EINZELUNTERNEHMER, EK, PARTNERSCHAFT, GBR, AOR, KOR, STIFTUNG, SE, SCE, OG, OEG, KEG, CH_EINZELUNTERNEHMER, EINFACHE-GESELLSCHAFT, KOLLEKTIVGESELLSCHAFT, OTHER
companyNamestringoptional
Company name. Required for organization customers. limited to 99 characters!
referencestringoptional
Additional reference within the company. i.e. 'Department XYZ'. Can be specified for organization customers. limited to 99 characters!

Request body

{
    "email": "user@example.com",
    "merchantCustomerId": "string",
    "customerType": "string",
    "organizationRegistrationId": "string",
    "organizationVatId": "string",
    "organizationRegistrationRegister": "string",
    "organizationEntityType": "LIMITED_COMPANY",
    "companyName": "string",
    "reference": "string"
}

Responses

201Successful response.optional
- 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.
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/customers
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating customer!
- codenumberoptionalexample: 4001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Get list of customers

GET /customers

Endpoint to receive a list of available customers.

The following parameters can be used as filter.

customerId
email
merchantCustomerId
createdAt
modifiedAt

The following parameters can be used as a range filter.

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 customers

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers");
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 customers.
  - 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.
- totalPagesnumber (int)required
  A counter for the total pages returned.

200

{
    "elements": [
        {
            "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"
                    }
                }
            ]
        }
    ],
    "totalPages": 1
}

Get customer

GET /customers/{customerId}

Endpoint to receive a customer referencing the customerId.

The service will also return associated persona and address data

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)
customerIdstringrequired
ID of the specific customer.

Get customer

C#
PHP
Node
Shell

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

Responses

200Successful response.optional
- 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.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while fetching customer!
- codenumberoptionalexample: 4002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Delete customer

DELETE /customers/{customerId}

Endpoint to delete a specific customer referencing the customerId.

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)
customerIdstringrequired
ID of the specific customer.

Delete customer

C#
PHP
Node
Shell

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

Responses

204Successful response.optional
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while fetching customer!
- codenumberoptionalexample: 4002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

404

{
    "path": "v1/customers/customer_asdfghjk",
    "timestamp": 1603275671582,
    "status": 404,
    "message": "Error while fetching customer!",
    "code": 4002,
    "globalTrackId": "Some Request ID",
    "errors": [
        [
            {
                "code": 4101,
                "field": "customerId",
                "message": "A Customer with specified id can not be found. Expected: A valid string identifier representing a Customer object between 1 and 255 characters."
            }
        ]
    ]
}

Update customer

PATCH /customers/{customerId}

Endpoint to update the merchantCustomerId of a specific customer referencing the customerId

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)
customerIdstringrequired
ID of the specific customer.

Update customer

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}");
var request = new RestRequest(Method.PATCH);
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

merchantCustomerIdstringoptional
The identifier of the customer. Created by you.
customerTypestringoptional
Customer type. Specified as "organization" for companies and organizations. Mandatory for b2b customers.
organizationRegistrationIdstringoptional
Organization registration id. Only applicable for organization customer types.
organizationVatIdstringoptional
Organization VAT id. Only used for organization customer types.
organizationRegistrationRegisterstringoptional
Organization registers can be the court name that registered the company. The registry location name, or another other organization registering institution name. This field is optional.
organizationEntityTypestringoptional
Customers that are organizations use this to specify their entity type. Klarna B2B specific organizationEntityType : LIMITED_COMPANY PUBLIC_LIMITED_COMPANY ENTREPRENEURIAL_COMPANY LIMITED_PARTNERSHIP_LIMITED_COMPANY LIMITED_PARTNERSHIP GENERAL_PARTNERSHIP REGISTERED_SOLE_TRADER SOLE_TRADER CIVIL_LAW_PARTNERSHIP PUBLIC_INSTITUTION OTHER RatePAY B2B specific organizationEntityType : GMBH GMBH-I-GR GGMBH GMBH-CO-KG OHG KG EV EG AG UG UG-I-GR EINZELUNTERNEHMER EK PARTNERSCHAFT PUBLIC_INSTITUTION GBR AOR KOR STIFTUNG OTHER SE SCE OG OEG KEG CH_EINZELUNTERNEHMER EINFACHE-GESELLSCHAFT KOLLEKTIVGESELLSCHAFT

LIMITED_COMPANY, PUBLIC_LIMITED_COMPANY, ENTREPRENEURIAL_COMPANY, LIMITED_PARTNERSHIP_LIMITED_COMPANY, LIMITED_PARTNERSHIP, GENERAL_PARTNERSHIP, REGISTERED_SOLE_TRADER, SOLE_TRADER, CIVIL_LAW_PARTNERSHIP, PUBLIC_INSTITUTION, GMBH, GMBH-I-GR, GGMBH, GMBH-CO-KG, OHG, KG, EV, EG, AG, UG, UG-I-GR, EINZELUNTERNEHMER, EK, PARTNERSCHAFT, GBR, AOR, KOR, STIFTUNG, SE, SCE, OG, OEG, KEG, CH_EINZELUNTERNEHMER, EINFACHE-GESELLSCHAFT, KOLLEKTIVGESELLSCHAFT, OTHER
companyNamestringoptional
Company name. Required for organization customers. limited to 99 characters!
referencestringoptional
Additional reference within the company. i.e. 'Department XYZ'. Can be specified for organization customers. limited to 99 characters!

Request body

{
    "merchantCustomerId": "string",
    "customerType": "string",
    "organizationRegistrationId": "string",
    "organizationVatId": "string",
    "organizationRegistrationRegister": "string",
    "organizationEntityType": "LIMITED_COMPANY",
    "companyName": "string",
    "reference": "string"
}

Responses

200Successful response.optional
- 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.
400Bad value caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while updating customer!
- codenumberoptionalexample: 4003
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Get customer persona

GET /customers/{customerId}/personas/{personaId}

Endpoint to receive a specific persona data referencing the corresponding personaId and customerId.

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)
customerIdstringrequired
ID of the specific customer.
personaIdstringrequired
ID of the specific persona.

Get customer persona

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/personas/%7BpersonaId%7D");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- 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.
404Not found caused by invalid input.optional
- pathstringoptionalexample: /customers/customer_asdfghjk/personas/persona_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while fetching persona!
- codenumberoptionalexample: 8002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "personaId": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "mobile": "string",
    "fax": "string",
    "birthday": 0,
    "gender": "MALE",
    "title": "string"
}

Assign persona to customer

POST /customers/{customerId}/personas

Endpoint to create a persona object and assign it to a specific customer referencing the customerId.

Personas contain person related attributes of a customer which are needed to process some payment methods.

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)
customerIdstringrequired
ID of the specific customer.

Assign persona to customer

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/personas");
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

firstNamestringrequired
The firstname of this persona. limited to 35 characters!
lastNamestringrequired
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.

Request body

{
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "mobile": "string",
    "fax": "string",
    "birthday": 0,
    "gender": "MALE",
    "title": "string"
}

Responses

200Successful response.optional
- 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.
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/personas
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating persona!
- codenumberoptionalexample: 8001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "personaId": "string",
    "createdAt": 0,
    "modifiedAt": 0,
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "mobile": "string",
    "fax": "string",
    "birthday": 0,
    "gender": "MALE",
    "title": "string"
}

Get list of customer persona

GET /customers/{customerId}/personas

Endpoint to receive a list of available personas for a specific customer referencing the customerId.

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)
customerIdstringrequired
ID of the specific customer.

Get list of customer persona

C#
PHP
Node
Shell

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

Responses

200Successful responseoptional
- elementsarrayrequired
  A list of personas.
  - 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.
- totalPagesnumber (int)required
  A counter for the total pages returned.
400Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/personas
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while fetching persona!
- codenumberoptionalexample: 8002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "elements": [
        {
            "personaId": "string",
            "createdAt": 0,
            "modifiedAt": 0,
            "firstName": "string",
            "lastName": "string",
            "phone": "string",
            "mobile": "string",
            "fax": "string",
            "birthday": 0,
            "gender": "MALE",
            "title": "string"
        }
    ],
    "totalPages": 1
}

Get customer address

GET /customers/{customerId}/addresses/{addressId}

Endpoint to receive a specific address data referencing the corresponding personaId and customerId.

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)
customerIdstringrequired
ID of the specific customer.
addressIdstringrequired
ID of the specific address.

Get customer address

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/addresses/%7BaddressId%7D");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- 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.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/addresses/address_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- messagestringoptionalexample: Error while loading address!
- codenumberoptionalexample: 6002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Assign address to customer

POST /customers/{customerId}/addresses

Endpoint to create a new address for a specific customer.

Addresses containing address related attributes of a customer which are needed to process some payment methods.

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)
customerIdstringrequired
ID of the specific customer.

Assign address to customer

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/addresses");
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

firstNamestringrequired
The firstname of this address. limited to 35 characters!
lastNamestringrequired
The lastname of this address. limited to 35 characters!
streetstringrequired
The street of this address.
houseNumberstringoptional
The housenumber of the street.
citystringrequired
The city of the address.
zipstringrequired
The zip of the address.
countrystringrequired
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.

Request body

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

Responses

200Successful response.optional
- 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.
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/addresses
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while creating persona!
- codenumberoptionalexample: 6001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Get list of customer addresses

GET /customers/{customerId}/addresses

Endpoint to receive a list of available addresses for a specific customer referencing the customerId.

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)
customerIdstringrequired
ID of the specific customer.

Get list of customer addresses

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/addresses");
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 addresses.
  - 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.
- totalPagesnumber (int)required
  A counter for the total pages returned.
400Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/addresses
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while loading address!
- codenumberoptionalexample: 6002
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "elements": [
        {
            "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"
        }
    ],
    "totalPages": 1
}

Assign payment instrument to customer

POST /customers/{customerId}/payment-instruments

Endpoint to assign a payment instrument to a specific customer referencing the customerId.

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)
customerIdstringrequired
ID of the specific customer.

Assign payment instrument to customer

C#
PHP
Node
Shell

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

paymentInstrumentIdstringrequired
The identifier of a paymentinstrument which will be connected to the customer.

Request body

{
    "paymentInstrumentId": "string"
}

Responses

204Successful response.optional
400Not found caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/payment-instruments
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while adding payment instrument association!
- codenumberoptionalexample: 4099
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

400

{
    "path": "v1/customers/customer_asdfghjk/payment-instruments",
    "timestamp": 1603275671582,
    "status": 400,
    "message": "Error while adding payment instrument association!",
    "code": 4099,
    "globalTrackId": "Some Request ID",
    "errors": [
        [
            {
                "code": 4101,
                "field": "customerId",
                "message": "A Customer with specified id can not be found. Expected: A valid string identifier representing a Customer object between 1 and 255 characters."
            },
            {
                "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."
            }
        ]
    ]
}

Get list of customer payment instruments

GET /customers/{customerId}/payment-instruments

Endpoint to receive a list of available payment instruments for a specific customer referencing the customerId.

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)
customerIdstringrequired
ID of the specific customer.

Get list of customer payment instruments

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/customers/{customerId}/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.
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/payment-instruments
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while fetching payment instrument!
- codenumberoptionalexample: 10001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

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

Delete payment instrument from customer

DELETE /customers/{customerId}/payment-instruments/{paymentInstrumentId}

Endpoint to delete a specific payment instrument from a customer.

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)
customerIdstringrequired
ID of the specific customer.
paymentInstrumentIdstringrequired
ID of the specific paymentinstrument.

Delete payment instrument from customer

C#
PHP
Node
Shell

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

Responses

204Successful response.optional
400Bad request caused by invalid input.optional
- pathstringoptionalexample: v1/customers/customer_asdfghjk/payment-instruments/paymentinstrument_asdfghjk
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 400
- messagestringoptionalexample: Error while removing payment instrument association!
- codenumberoptionalexample: 4011
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

400

{
    "path": "v1/customers/customer_asdfghjk/payment-instruments/paymentinstrument_asdfghjk",
    "timestamp": 1603275671582,
    "status": 400,
    "message": "Error while removing payment instrument association!",
    "code": 4011,
    "globalTrackId": "Some Request ID",
    "errors": [
        [
            {
                "code": 4101,
                "field": "customerId",
                "message": "A Customer with specified id can not be found. Expected: A valid string identifier representing a Customer object between 1 and 255 characters."
            },
            {
                "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."
            }
        ]
    ]
}

Get supported installment settings

GET /installment/config

Endpoint to query the supported installment settings.

This service will return the minimum rate and the minimum & maximum monthly term of an installment that are supported based on the merchant configuration.

A merchant can use these parameters as restrictions in case an input form is displayed directly to their customers chosing the available installment options.

This service is not needed in case the Payengine widget is used as this will execute the services automatically in the background.

Parameters

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

Authorization: Bearer merchantId

Get supported installment settings

C#
PHP
Node
Shell

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

Responses

200Successful response.optional
- rateMinNormalintegerrequired
  Minimum rate of a normal installment plan
- monthNumberMinintegerrequired
  Minimum duration of installment plan
- monthNumberMaxintegerrequired
  Maximum duration of installment plan

200

{
    "rateMinNormal": 0,
    "monthNumberMin": 0,
    "monthNumberMax": 0
}

Get installment rate

GET /installment/calculation/rate

Endpoint to receive an installment plan based on the total amount and a selected rate for each installment payment.

Parameters

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

Authorization: Bearer merchantId
amountintegerrequired
Amount to be financed
calculationRateintegerrequired
Contains the rate information

Get installment rate

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/installment/calculation/rate?amount=SOME_INTEGER_VALUE&calculationRate=SOME_INTEGER_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- totalAmountintegerrequired
  Total of amount, interest-amount and service-charge
- amountintegerrequired
  Price that has to be financed
- interestAmountintegerrequired
  Total of all monthly paid interests
- serviceChargeintegerrequired
  Additional costs of financing
- interestRateintegerrequired
  Interest-rate which will be used to calculate the annual percentage rate
- annualPercentageRateintegerrequired
  Interest-rate based on service-charge and interest- rate
- monthlyDebitInterestintegerrequired
  Monthly interest rates based on annual-percentage- rate
- numberOfRatesintegerrequired
  Number of months; duration of the installment plan
- rateintegerrequired
  Monthly rate to be paid by the customer
- lastRateintegerrequired
  Last monthly rate to be paid by the customer

200

{
    "totalAmount": 0,
    "amount": 0,
    "interestAmount": 0,
    "serviceCharge": 0,
    "interestRate": 0,
    "annualPercentageRate": 0,
    "monthlyDebitInterest": 0,
    "numberOfRates": 0,
    "rate": 0,
    "lastRate": 0
}

Get installment plan

GET /installment/calculation/time

Endpoint to receive an installment plan based on the total amount and a selected term of the installment payment (in months).

Parameters

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

Authorization: Bearer merchantId
amountintegerrequired
Amount to be financed
calculationTimeintegerrequired
Contains the duration information of the installment plan

Get installment plan

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/installment/calculation/time?amount=SOME_INTEGER_VALUE&calculationTime=SOME_INTEGER_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- totalAmountintegerrequired
  Total of amount, interest-amount and service-charge
- amountintegerrequired
  Price that has to be financed
- interestAmountintegerrequired
  Total of all monthly paid interests
- serviceChargeintegerrequired
  Additional costs of financing
- interestRateintegerrequired
  Interest-rate which will be used to calculate the annual percentage rate
- annualPercentageRateintegerrequired
  Interest-rate based on service-charge and interest- rate
- monthlyDebitInterestintegerrequired
  Monthly interest rates based on annual-percentage- rate
- numberOfRatesintegerrequired
  Number of months; duration of the installment plan
- rateintegerrequired
  Monthly rate to be paid by the customer
- lastRateintegerrequired
  Last monthly rate to be paid by the customer

200

{
    "totalAmount": 0,
    "amount": 0,
    "interestAmount": 0,
    "serviceCharge": 0,
    "interestRate": 0,
    "annualPercentageRate": 0,
    "monthlyDebitInterest": 0,
    "numberOfRates": 0,
    "rate": 0,
    "lastRate": 0
}

Get list of settlement files

GET /settlements

Endpoint to receive a list of available settlement files.

The following parameters can be used as filter.

settlementId - filter the files by their Id
receivedAt - current time when the file is received
product - filter by different products
downloaded - mark the file after first download as “downloaded”. This is just a state and it doesn’t mean that the file could not be anymore downloaded. The file could be downloaded as many times needed and this state just shows that is downloaded at least ones
receivedAtAfter - filter by received time after
receivedAtBefore - filter by received time before
fileFormat - only csv file format is allowed
excludeFiles - boolean check that excludes the content of the settlement files to be return in the response
settlementType - determine if we wanted to filter by original or unified settlements

The following parameter names can be used for ordering the results.

settlementId
product
downloaded
receivedAt
fileFormat
settlementType

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 settlement files

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/settlements");
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 settlements.
  - idstringoptional
    The identifier of the settlements. Created by payengine
  - settlementsFilestringoptional
    Settlements file.
  - productstringoptional
    Product
  - receivedAtnumber (date-time)optional
    This timestamp indicates the arrival of this settlement.
  - fileNamestringoptional
    Name of the file
  - downloadedbooleanoptional
    Mark the file after first download as “downloaded”. The file could be downloaded as many times needed and this state just shows that is downloaded at least ones.
  - merchantIdstringoptional
    Merchant Id
- totalPagesnumber (int)required
  A counter for the total pages returned.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/settlements
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- codenumberoptionalexample: 50001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "elements": [
        {
            "id": "string",
            "settlementsFile": "string",
            "product": "string",
            "receivedAt": 0,
            "fileName": "string",
            "downloaded": true,
            "merchantId": "string"
        }
    ],
    "totalPages": 1
}

Download settlement file

GET /settlements/download

Endpoint to download specific settlement files.

The files that should be downloaded have to be referenced via the settlementId in the body of the service request.

In case there is a list of settlementIds the files will be returned as a zip file.

In case only one settlementId is referenced the plain file will be returned.

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)
idarrayoptional
List of settlement ids

Download settlement file

C#
PHP
Node
Shell

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

Responses

200Successful response.optional
- idstringoptional
  The identifier of the settlements. Created by payengine
- settlementsFilestringoptional
  Settlements file.
- productstringoptional
  Product
- receivedAtnumber (date-time)optional
  This timestamp indicates the arrival of this settlement.
- fileNamestringoptional
  Name of the file
- downloadedbooleanoptional
  Mark the file after first download as “downloaded”. The file could be downloaded as many times needed and this state just shows that is downloaded at least ones.
- merchantIdstringoptional
  Merchant Id
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/settlements
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- codenumberoptionalexample: 50001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "id": "string",
    "settlementsFile": "string",
    "product": "string",
    "receivedAt": 0,
    "fileName": "string",
    "downloaded": true,
    "merchantId": "string"
}

Get list of transaction report files

GET /report/transaction

Endpoint to receive a list of available transaction report files.

The following parameters can be used as filter.

createdAt
createdAtAfter
createdAtBefore
reportDateAfter
reportDateBefore
reportDate
reportType
fileFormat

The following parameter names can be used for ordering the results.

reportDate
fileFormat

Parameters

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

Authorization: Bearer merchantId

Get list of transaction report files

C#
PHP
Node
Shell

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

Responses

200Successful response.optional
- elementsarrayrequired
  A list of transaction reports.
  - idstringoptional
    The identifier of the transaction report. Created by payengine
  - reportDatenumber (date-time)optional
    Timestamp indicates the date for which the report was generated and includes the transactions
  - fileNamestringoptional
    Name of the file
  - reportTypestringoptional
    The type of the transaction report ['daily', 'monthly']
  - fileFormatstringoptional
    Format of the file ['csv', 'xlsx']
- totalPagesnumber (int)required
  A counter for the total pages returned.
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/report/transaction
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- codenumberoptionalexample: 50001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

{
    "elements": [
        {
            "id": "string",
            "reportDate": 0,
            "fileName": "string",
            "reportType": "string",
            "fileFormat": "string"
        }
    ],
    "totalPages": 1
}

Download transaction report file

GET /report/transaction/download

Endpoint to download specific transactions report files.

The files that should be downloaded have to be referenced via query param transactionReportId.

In case of multiple transactionReportId the files will be returned as a zip file.

In case only one transactionReportId is referenced the plain file will be returned.

Parameters

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

Authorization: Bearer merchantId
idarrayoptional
List of transaction report ids

Download transaction report file

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/report/transaction/download?id=SOME_ARRAY_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
404Not found caused by invalid input.optional
- pathstringoptionalexample: v1/report/transaction
- timestampnumber (date-time)optionalexample: 1603275671582
- statusnumberoptionalexample: 404
- codenumberoptionalexample: 50001
- globalTrackIdstringoptionalexample: Some Request ID
- errorsarrayoptional

404

{
    "path": "v1/report/transaction",
    "timestamp": 1603275671582,
    "status": 404,
    "code": 50001,
    "globalTrackId": "Some Request ID",
    "errors": [
        [
            {
                "code": 50001,
                "message": "A Transaction report with specified id can not be found. Expected: A valid string identifier representing a Transaction report object between 1 and 255 characters."
            }
        ]
    ]
}

Get system health

GET /health

Endpoint to check the health status of the Payengine API.

Parameters

Get system health

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/health");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Responses

200The system health is successfully measured.optional
- systemHealthstringoptional
  The aggregated system health
  
  GOOD, BAD
403optional
The health endpoint is disabled via configuration.

200

{
    "systemHealth": "GOOD"
}

Create Notification

POST /merchant/{merchantId}/notifications

Endpoint to create a new Notification

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)
merchantIdstringrequired
merchantId

Create Notification

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/merchant/{merchantId}/notifications");
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

activebooleanoptional
descriptionstringoptional
event_typesarrayoptional
namestringoptional
notification_typestringoptional
notification_valuestringoptional
versionstringoptional

Request body

{
    "active": true,
    "description": "string",
    "event_types": [
        "string"
    ],
    "name": "string",
    "notification_type": "string",
    "notification_value": "string",
    "version": "string"
}

Responses

200Successful response.optional
- activebooleanoptional
- created_atstring (date-time)optional
- descriptionstringoptional
- event_typesarrayoptional
- namestringoptional
- notification_idstringoptional
- notification_typestringoptional
- notification_valuestringoptional
- updated_atstring (date-time)optional
- versionstringoptional
201Createdoptional
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional

200

{
    "active": true,
    "created_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "event_types": [
        "string"
    ],
    "name": "string",
    "notification_id": "string",
    "notification_type": "string",
    "notification_value": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": "string"
}

Get list of Notifications

GET /merchant/{merchantId}/notifications

Endpoint to receive a list of available Notifications.

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)
merchantIdstringrequired
merchantId
allRequestParamsstringrequired
allRequestParams

Get list of Notifications

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/merchant/{merchantId}/notifications?allRequestParams=SOME_STRING_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- elementsarrayoptional
  - activebooleanoptional
  - created_atstring (date-time)optional
  - descriptionstringoptional
  - event_typesarrayoptional
  - namestringoptional
  - notification_idstringoptional
  - notification_typestringoptional
  - notification_valuestringoptional
  - updated_atstring (date-time)optional
  - versionstringoptional
- totalPagesinteger (int32)optional
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional

200

{
    "elements": [
        {
            "active": true,
            "created_at": "2019-08-24T14:15:22Z",
            "description": "string",
            "event_types": [
                "string"
            ],
            "name": "string",
            "notification_id": "string",
            "notification_type": "string",
            "notification_value": "string",
            "updated_at": "2019-08-24T14:15:22Z",
            "version": "string"
        }
    ],
    "totalPages": 0
}

Get Notification

GET /merchant/{merchantId}/notifications/{notificationId}

Endpoint to receive a specific Notification referencing the notificationId.

Parameters

merchantIdstringrequired
merchantId
notificationIdstringrequired
notificationId

Get Notification

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/merchant/{merchantId}/notifications/%7BnotificationId%7D");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
- activebooleanoptional
- created_atstring (date-time)optional
- descriptionstringoptional
- event_typesarrayoptional
- namestringoptional
- notification_idstringoptional
- notification_typestringoptional
- notification_valuestringoptional
- updated_atstring (date-time)optional
- versionstringoptional
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional

200

{
    "active": true,
    "created_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "event_types": [
        "string"
    ],
    "name": "string",
    "notification_id": "string",
    "notification_type": "string",
    "notification_value": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": "string"
}

Delete Notification

DELETE /merchant/{merchantId}/notifications/{notificationId}

Endpoint to delete an existing Notification referencing the notificationId.

Parameters

merchantIdstringrequired
merchantId
notificationIdstringrequired
notificationId

Delete Notification

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/merchant/{merchantId}/notifications/%7BnotificationId%7D");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
204No Contentoptional
401Unauthorizedoptional
403Forbiddenoptional

Update Notification

PATCH /merchant/{merchantId}/notifications/{notificationId}

Endpoint to update a Notification referencing the notificationId.

Parameters

merchantIdstringrequired
merchantId
notificationIdstringrequired
notificationId

Update Notification

C#
PHP
Node
Shell

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

Request body

activebooleanoptional
descriptionstringoptional
event_typesarrayoptional
namestringoptional
notification_typestringoptional
notification_valuestringoptional
versionstringoptional

Request body

{
    "active": true,
    "description": "string",
    "event_types": [
        "string"
    ],
    "name": "string",
    "notification_type": "string",
    "notification_value": "string",
    "version": "string"
}

Responses

200Successful response.optional
- activebooleanoptional
- created_atstring (date-time)optional
- descriptionstringoptional
- event_typesarrayoptional
- namestringoptional
- notification_idstringoptional
- notification_typestringoptional
- notification_valuestringoptional
- updated_atstring (date-time)optional
- versionstringoptional
204No Contentoptional
401Unauthorizedoptional
403Forbiddenoptional

200

{
    "active": true,
    "created_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "event_types": [
        "string"
    ],
    "name": "string",
    "notification_id": "string",
    "notification_type": "string",
    "notification_value": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": "string"
}

Get list of Event Types

GET /event-types

Endpoint to receive a list of available Event Types.

Parameters

versionstringoptional
version
notification_typestringoptional
notification_type

Get list of Event Types

C#
PHP
Node
Shell

var client = new RestClient("https://apitest.payengine.de/v1/event-types?version=SOME_STRING_VALUE&notification_type=SOME_STRING_VALUE");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Responses

200Successful response.optional
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional

200

[
    "string"
]

Validate Notification

POST /notifications/validate

Endpoint to validate the notification

Parameters

addressstringrequired
address

Validate Notification

C#
PHP
Node
Shell

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

Request body

"string"

Responses

200Successful response.optional
201Createdoptional
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional

200

"string"