Skip to main content

Register

POST 
/transaction/:apiKey/register

A register transaction registers a customer's payment instrument for future use (Debit or Preauthorize).

Request​

Path Parameters

    apiKey stringrequired

    Possible values: <= 50 characters

    API Key of Connector

Body

required

Data which is required to process a register

    merchantTransactionId stringrequired

    Possible values: non-empty and <= 50 characters

    additionalId1 string

    Possible values: non-empty and <= 50 characters

    additionalId2 string

    Possible values: non-empty and <= 50 characters

    extraData

    object

    Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string

    pspPassthroughData

    object

    Object containing key-value pars (string-to-string) to be passed to the PSP.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string
    merchantMetaData string

    Possible values: <= 255 characters

    successUrl uri

    Possible values: <= 4096 characters

    cancelUrl uri

    Possible values: <= 4096 characters

    errorUrl uri

    Possible values: <= 4096 characters

    callbackUrl uri

    Possible values: <= 4096 characters

    transactionToken string

    Possible values: <= 8192 characters

    description string

    Possible values: <= 255 characters

    transactionIndicator string

    Possible values: [SINGLE, INITIAL, RECURRING, FIRST-CARDONFILE, CARDONFILE, CARDONFILE-MERCHANT-INITIATED, MOTO]

    customer

    object

    Information on the customer making a payment.

    Strive to include as much information as possible. This reduces friction and provides the most benefit for risk checks, 3D-secure authentication and other validations.

    identification string

    Possible values: <= 36 characters

    firstName string

    Possible values: <= 50 characters

    First name of the customer.

    lastName string

    Possible values: <= 50 characters

    Last name of the customer.

    birthDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    gender string

    Possible values: [M, F]

    Gender of the customer.

    billingAddress1 string

    Possible values: <= 50 characters

    Line one of the customer's billing address.

    billingAddress2 string

    Possible values: <= 50 characters

    Line two of the customer's billing address.

    billingCity string

    Possible values: <= 50 characters

    City of the customer's billing address.

    billingPostcode string

    Possible values: <= 16 characters

    Postal code of the customer's billing address.

    billingState string

    Possible values: <= 30 characters

    State of the customer's billing address.

    billingCountry Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    billingPhone string

    Possible values: <= 20 characters

    shippingFirstName string

    Possible values: <= 50 characters

    shippingLastName string

    Possible values: <= 50 characters

    shippingCompany string

    Possible values: <= 50 characters

    shippingAddress1 string

    Possible values: <= 50 characters

    shippingAddress2 string

    Possible values: <= 50 characters

    shippingCity string

    Possible values: <= 50 characters

    shippingPostcode string

    Possible values: <= 16 characters

    shippingState string

    Possible values: <= 30 characters

    shippingCountry Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    shippingPhone string

    Possible values: <= 20 characters

    company string

    Possible values: <= 50 characters

    email string

    Possible values: <= 255 characters

    emailVerified boolean
    ipAddress string

    Possible values: <= 50 characters

    nationalId string

    Possible values: <= 20 characters

    extraData

    object

    Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string

    paymentData

    object

    oneOf

    ibanData

    object

    iban string

    Possible values: <= 34 characters

    bic string

    Possible values: <= 11 characters

    mandateId string

    Possible values: <= 50 characters

    mandateDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    schedule

    object

    amount Amount (string)required

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)required

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    periodLength integerrequired

    The length of the duration, measured in periodUnit.

    periodUnit PeriodUnit (string)required

    Possible values: [DAY, WEEK, MONTH, YEAR]

    The unit that the duration is measured in.

    startDateTime date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$

    RFC 3339 Internet Date/Time Format date-time

    merchantMetaData string

    Possible values: <= 255 characters

    The field merchantMetaData is optional and for your internal use only. It can be filled with any string you want, with a maximum length of 255 characters.

    The value has no influence on the transaction process at all and will be returned to you in any postback notification. It may also be included in data exports.

    If you want to add different types of information, we recommend separating them by a character which would not occur in the data value itself, e.g. a pipe character |.

    callbackUrl uri

    Possible values: <= 4096 characters

    Endpoint to receive status notifications.

    customerProfileData

    object

    Reference to a customer profile created with the Customer Profile API.

    Either profileGuid or customerIdentification MUST be provided.

    profileGuid string

    Possible values: <= 36 characters

    The unique customer profile identifier created by the platform.

    Supply this field to register a new payment instrument with an existing customer profile.

    customerIdentification string

    Possible values: <= 36 characters

    The customer profile identifier provided by you.

    Supply this field to create a new customer profile, or register a new payment instrument with an existing customer profiled.

    markAsPreferred boolean

    Mark payment instrument this CustomerProfile is used on as preferred.

    threeDSecureData

    object

    3D-Secure authentication result obtained from the 3DS MPI Provider.

    As explained in 3D Secure — Providing 3-D Secure data you should provide as many data as you have to apply for the 3D Secure 2.0 frictionless flow.

    note
    • All fields from the 3D Secure standard that already match with the transaction or customer data are already automatically filled by the IXOPAY platform, and are not listed here.
    • 3D-Secure 2.0: For 3D-Secure 2.0, the browser* fields below are mandatory. Transaction will not succeed if neither all browser nor all SDK parameters are provided.
    • Browser Data: The browser* fields are filled automatically by the IXOPAY platform if you are using hosted payment pages or payment.js integration. For any other integration flow you will need to provide them.
    3dsecure ThreeDSecureType (string)

    Possible values: [OFF, OPTIONAL, MANDATORY]

    Triggers the 3D Secure authentication for this transaction.

    schemeId string

    Possible values: [CB]

    "Pin" the scheme ID in case of a co-branded card.

    Currently, there is only CB supported.

    channel string

    Possible values: [01, 02, 03]

    Indicates the type of channel interface being used to initiate the transaction.

    • 01 - App-based
    • 02 - Browser
    • 03 - 3DS Requestor Initiated
    authenticationIndicator string

    Possible values: [01, 02, 03, 04, 05, 06]

    Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request.

    • 01 - Payment transaction
    • 02 - Recurring transaction
    • 03 - Installment transaction
    • 04 - Add card
    • 05 - Maintain card
    • 06 - Cardholder verification as part of EMV token ID&V
    cardholderAuthenticationMethod string

    Possible values: [01, 02, 03, 04, 05, 06]

    Mechanism used by the Cardholder to authenticate to the 3DS Requester.

    • 01 - No 3DS Requester authentication occurred (i.e. cardholder "logged in" as guest)
    • 02 - Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials
    • 03 - Login to the cardholder account at the 3DS Requestor system using federated ID
    • 04 - Login to the cardholder account at the 3DS Requestor system using issuer credentials
    • 05 - Login to the cardholder account at the 3DS Requestor system using third-party authentication
    • 06 - Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
    cardholderAuthenticationDateTime date-time

    Date and time in UTC of the cardholder authentication.

    cardHolderAuthenticationData string

    Possible values: <= 1024 characters

    Data that documents and supports a specific authentication process.

    In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.

    challengeIndicator string

    Possible values: [01, 02, 03, 04, 05, 06, 07, 08, 09]

    Indicates whether a challenge is requested for this transaction.

    For example: For 01-PA, a 3DS Requester may have concerns about the transaction, and request a challenge.

    • 01 - No preference
    • 02 - No challenge requested
    • 03 - Challenge requested: 3DS Requestor Preference
    • 04 - Challenge requested: Mandate
    • 05 - No challenge requested (transactional risk analysis is already performed)
    • 06 - No challenge requested (Data share only)
    • 07 - No challenge requested (strong consumer authentication is already performed)
    • 08 - No challenge requested (utilise whitelist exemption if no challenge required)
    • 09 - Challenge requested (whitelist prompt requested if challenge required)
    priorReference string

    Possible values: <= 36 characters

    This data element provides additional information to the ACS to determine the best approach for handling a request.

    Containing ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

    priorAuthenticationMethod string

    Possible values: [01, 02, 03, 04]

    Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.

    • 01 - Frictionless authentication occurred by ACS
    • 02 - Cardholder challenge occurred by ACS
    • 03 - AVS verified
    • 04 - Other issuer methods
    priorAuthenticationDateTime local-date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1])) (([0-1][0-9])|([2][0-3])):([0-5][0-9])$

    RFC 3339 Internet Date/Time Format date " " time without timespec-second, time-fraction, and time-zone.

    priorAuthenticationData string

    Possible values: <= 2048 characters

    Data that documents and supports a specific authentication process.

    In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.

    In future versions of the application, these details are expected to be included.

    cardholderAccountType string

    Possible values: [01, 02, 03, 04]

    Indicates the type of account. For example, for a multi-account card product.

    • 01 - Not applicable
    • 02 - Credit
    • 03 - Debit
    • 04 - JCB specific value for Prepaid
    cardholderAccountAgeIndicator string

    Possible values: [01, 02, 03, 04, 05]

    Length of time that the cardholder has had the account with the 3DS Requester.

    • 01 - No account (guest check-out)
    • 02 - During this transaction
    • 03 - Less than 30 days
    • 04 - 30—60 days
    • 05 - More than 60 days
    cardholderAccountDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    cardholderAccountChangeIndicator string

    Possible values: [01, 02, 03, 04]

    Length of time since the cardholder’s account information with the 3DS Requestor was last changed.

    Includes Billing or Shipping address, new payment account, or new user(s) added.

    • 01 - Changed during this transaction
    • 02 - Less than 30 days
    • 03 - 30—60 days
    • 04 - More than 60 days
    cardholderAccountLastChange date-time

    Date that the cardholder’s account with the 3DS Requestor was last changed. Including Billing or Shipping address, new payment account, or new user(s) added.

    cardholderAccountPasswordChangeIndicator string

    Possible values: [01, 02, 03, 04, 05]

    Length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.

    • 01 - No change
    • 02 - Changed during this transaction
    • 03 - Less than 30 days
    • 04 - 30—60 days
    • 05 - More than 60 days
    cardholderAccountLastPasswordChange date (string)

    Date that cardholder’s account with the 3DS Requestor had a password change or account.

    shippingAddressUsageIndicator string

    Possible values: [01, 02, 03, 04]

    Indicates when the shipping address used for this transaction was first used with the 3DS.

    • 01 - Changed during this transaction
    • 02 - Less than 30 days
    • 03 - 30—60 days
    • 04 - More than 60 days
    shippingAddressFirstUsage date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    transactionActivityDay integer

    Possible values: <= 999

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

    transactionActivityYear integer

    Possible values: <= 999

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

    addCardAttemptsDay integer

    Possible values: <= 999

    Number of Add Card attempts in the last 24 hours.

    purchaseCountSixMonths integer

    Possible values: <= 999

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

    If the Cardholder Account Purchase Count reaches the value 999, it remains set at 999.

    suspiciousAccountActivityIndicator string

    Possible values: [01, 02]

    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

    • 01 - No suspicious activity has been observed
    • 02 - Suspicious activity has been observed
    shippingNameEqualIndicator string

    Possible values: [01, 02]

    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

    • 01 - Account Name identical to shipping name
    • 02 - Account Name different from shipping name
    paymentAccountAgeIndicator string

    Possible values: [01, 02, 03, 04, 05]

    Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

    • 01 - No account (guest check-out)
    • 02 - During this transaction
    • 03 - Less than 30 days
    • 04 - 30—60 days
    • 05 - More than 60 days
    paymentAccountAgeDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    billingAddressLine3 string

    Possible values: <= 128 characters

    Line 3 of customer's billing address.

    billingAddressState string

    Possible values: Value must match regular expression ^[A-Z0-9]{1,3}$

    State of the customer's billing address.

    shippingAddressLine3 string

    Possible values: <= 128 characters

    Line 3 of customer's shipping address.

    shippingAddressState string

    Possible values: Value must match regular expression ^[A-Z0-9]{1,3}$

    State of the customer's shipping address.

    billingShippingAddressMatch string

    Possible values: [Y, N]

    Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.

    • Y - Shipping Address matches Billing Address
    • N - Shipping Address does not match Billing Address
    homePhoneCountryPrefix string

    Possible values: non-empty and <= 3 characters

    Country Code of the home phone, ITU E.164.

    homePhoneNumber string

    Possible values: <= 15 characters

    Subscriber section of the number.

    mobilePhoneCountryPrefix string

    Possible values: non-empty and <= 3 characters

    Country Code of the mobile phone, ITU E.164.

    mobilePhoneNumber string

    Possible values: <= 15 characters

    Subscriber section of the number.

    workPhoneCountryPrefix string

    Possible values: non-empty and <= 3 characters

    Country Code of the work phone, ITU E.164.

    workPhoneNumber string

    Possible values: <= 15 characters

    Subscriber section of the number.

    purchaseInstalData integer

    Possible values: >= 1 and <= 999

    Indicates the maximum number of authorisations permitted for instalment payments.

    The field is required if the Merchant and Cardholder have agreed to installment payments, i.e. if 3DS Requestor Authentication Indicator = 03.

    Omitted if not an installment payment authentication.

    shipIndicator string

    Possible values: [01, 02, 03, 04, 05, 06, 07]

    Indicates shipping method chosen for the transaction.

    Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the code that describes the most expensive item.

    • 01 - Ship to cardholder's billing address
    • 02 - Ship to another verified address on file with merchant
    • 03 - Ship to address that is different from the cardholder's billing address
    • 04 - "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields)
    • 05 - Digital goods (includes online services, electronic gift cards and redemption codes)
    • 06 - Travel and Event tickets, not shipped
    • 07 - Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)
    deliveryTimeframe string

    Possible values: [01, 02, 03, 04]

    Indicates the merchandise delivery timeframe.

    • 01 - Electronic Delivery
    • 02 - Same day shipping
    • 03 - Overnight shipping
    • 04 - Two-day or more shipping
    deliveryEmailAddress string

    Possible values: <= 128 characters

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

    reorderItemsIndicator string

    Possible values: [01, 02]

    Indicates whether the cardholder is reordering previously purchased merchandise.

    • 01 - First time ordered
    • 02 - Reordered
    preOrderPurchaseIndicator string

    Possible values: [01, 02]

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

    • 01 - Merchandise available
    • 02 - Future availability
    preOrderDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    giftCardAmount integer

    Possible values: <= 999999999999999

    For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, "USD 123.45" is 123).

    giftCardCurrency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    giftCardCount integer

    Possible values: >= 1 and <= 99

    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

    purchaseDate local-date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1])) (([0-1][0-9])|([2][0-3])):([0-5][0-9])$

    RFC 3339 Internet Date/Time Format date " " time without timespec-second, time-fraction, and time-zone.

    recurringExpiry date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    recurringFrequency integer

    Possible values: <= 9999

    Indicates the minimum number of days between authorizations.

    This field is required for 01-PA and for 02-NPA, if 3DS Requestor Authentication Indicator = 02 or 03.

    transType string

    Possible values: [01, 03, 10, 11, 28]

    Identifies the type of transaction being authenticated.

    The values are derived from ISO 8583.

    • 01 - Goods / Service purchase
    • 03 - Check Acceptance
    • 10 - Account Funding
    • 11 - Quasi-Cash Transaction
    • 28 - Prepaid activation and Loan
    exemptionIndicator string

    Possible values: [01, 02, 03, 04, 05, 06, 07]

    Requests an SCA exemption for this transaction.

    Possible values are:

    • 01 - Low Value Transaction (amount under 30 EUR)
    • 02 - Low Risk Transaction
    • 03 - Whitelisted transaction, merchant is added as "Trusted Beneficiary" by cardholder
    • 04 - Secure Corporate Payment
    • 05 - Recurring or Merchant-initiated transaction
    • 06 - Mail or Telephone Order
    • 07 - Anonymous payment card
    threeRIIndicator string

    Possible values: [01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12]

    Indicates the type of 3RI request.

    This data element provides additional information to the ACS to determine the best approach for handling a 3RI request. Possible values are:

    • 01 - Recurring transaction
    • 02 - Installment transaction
    • 03 - Add card
    • 04 - Maintain card information
    • 05 - Account verification.
    • 06 - Split/delayed shipment
    • 07 - Top-up
    • 08 - Mail order
    • 09 - Telephone order
    • 10 - Whitelist status check
    • 11 - Other payment
    • 12 - Billing agreement.
    browserChallengeWindowSize string

    Possible values: [01, 02, 03, 04, 05]

    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.

    • 01 - 250x400
    • 02 - 390x400
    • 03 - 500x600
    • 04 - 600x400
    • 05 - Full screen
    browserAcceptHeader string

    Possible values: <= 2048 characters

    Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser

    browserIpAddress string

    Possible values: <= 56 characters

    IP address of the browser as returned by the HTTP headers to the 3DS Requestor.

    • 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. Example: 1.12.123.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: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
    browserJavaEnabled boolean

    Boolean that represents the ability of the cardholder browser to execute Java.

    Value is returned from the navigator.javaEnabled property.

    browserLanguage string

    Possible values: non-empty and <= 8 characters

    Value representing the browser language as defined in IETF BCP47.

    Value is returned from navigator.language property.

    browserColorDepth string

    Possible values: [1, 4, 8, 15, 16, 24, 30, 32, 48]

    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.

    • 1 - 1 bit
    • 4 - 4 bits
    • 8 - 8 bits
    • 15 - 15 bits
    • 16 - 16 bits
    • 24 - 24 bits
    • 32 - 32 bits
    • 48 - 48 bits
    browserScreenHeight integer

    Total height of the Cardholder's screen in pixels.

    Value is returned from the screen.height property.

    browserScreenWidth integer

    Total width of the Cardholder's screen in pixels.

    Value is returned from the screen.width property.

    browserTimezone integer

    Possible values: >= -9999 and <= 9999

    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.

    browserUserAgent string

    Possible values: <= 2048 characters

    Exact content of the HTTP user-agent header.

    browserPlatform string

    Possible values: <= 2048 characters

    Platform on which the cardholder's browser is running. If navigator.platform is not available, omit or pass an empty string.

    See also MDN — navigator: platform property.

    sdkInterface string

    Possible values: [01, 02, 03]

    Specifies all the SDK interface types that the device supports for displaying specific challenge user interfaces within the SDK.

    Accepted values are:

    • 01 - Native
    • 02 - HTML
    • 03 - Both
    sdkUiType string

    Possible values: Value must match regular expression ^(0[1-5]( *, *0[0-5])*)?$

    A comma-separated list of all UI types that the device supports for displaying specific challenge user interfaces within the SDK.

    Accepted values for each UI type are:

    • 01 - Text
    • 02 - Single select
    • 03 - Multi select
    • 04 - OOB
    • 05 - Html Other (valid only for HTML UI)
    sdkAppID string

    Possible values: <= 128 characters

    Universally e created upon all installations and updates of the 3DS Requestor App on a Customer Device.

    sdkEncData string

    Possible values: <= 128 characters

    JWE Object as defined 3DS Specs Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt.

    sdkEphemPubKey string

    Possible values: <= 128 characters

    Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.

    The value should be a JSON string containing the keys kty, crv, x, y,

    sdkMaxTimeout integer

    Possible values: >= 5

    Indicates the maximum amount of time (in minutes) for all exchanges.

    sdkReferenceNumber string

    Possible values: <= 32 characters

    Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.

    sdkTransID string

    Possible values: <= 128 characters

    Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

    payByLink

    object

    Enable generating a link that can be sent to a customer to complete a purchase.

    sendByEmail booleanrequired

    If true send the generated payment link to the customer via email.

    The email specified in customer.email is used as recipient.

    expirationInMinute int32

    Possible values: >= 1

    The generated payment link will expire after the duration specified via this field.

    language string

    Possible values: >= 2 characters and <= 2 characters

    l2l3Data

    object

    Level 2 & level 3 data.

    taxAmount string

    Possible values: <= 15 characters

    vatRegistrationNumber string

    Possible values: <= 255 characters

    nationalTaxIncluded string

    Possible values: <= 5 characters

    discountAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    commodityCode string

    Possible values: <= 255 characters

    freightAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    freightTaxAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    dutyAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    taxDetails

    object[]

    Possible values: <= 10

  • Array [

    • type string

    Possible values: <= 255 characters

    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    rate Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    code string

    Possible values: <= 255 characters

    taxId string

    Possible values: <= 255 characters

    applied string

    Possible values: <= 255 characters

    exemptionCode string

    Possible values: <= 255 characters

  • ]

Responses​

Transaction response

Schema

    success

    string

    required

    Possible values: [true, false]

    Returns true or false depending on whether the request was successful.

    success booleanrequired

    Returns true or false depending on whether the request was successful.

    uuid string

    UUID of the transaction.

    purchaseId string

    Purchase ID of the transaction.

    returnType string

    Possible values: [FINISHED, REDIRECT, HTML, PENDING, ERROR, PENDING_DCC]

    Depending on the returnType a transaction is finished, intermediate, or failed.

    • FINISHED

      The transaction completed and was processed successfully. You can deliver the ordered goods.

    • ERROR

      The transaction failed or was declined. See the error code and message for further details.

      You will find the native error message and code from the payment provider/acquiring bank in the fields adapterMessage and adapterCode.

      Note: Merchant Advice Code

      When supported by an adapter implementation, a merchant advice code can be returned with the ReturnData.

      This code is piped through as received by the gateway.

      If a merchant advice code indicating a hard "do not retry" is returned, the value "doNotResubmit": true will additionally be returned with the error response extra data.

    • REDIRECT

      You must redirect the user to the URL defined in redirectUrl to proceed with the transaction. Afterwards the user will be back redirected to your website (one of the URLs you defined in the API call in successUrl, cancelUrl or errorUrl). In parallel the sends a status notification to you callbackUrl with the final result.

      Note:

      For the final result you should only trust the notification, NOT the back redirection!

    • PENDING

      The transaction was accepted for processing, but is not yet completed. You will receive a status notification to the URL you defined in callbackUrl once it reaches a final state.

      Depending on the payment method, this can take from seconds up to several days.

    redirectType string

    Possible values: [iframe, fullpage]

    Depending on the redirectType the URL from redirectUrl should be displayed either in an <iframe>, in a full page (e.g. via a HTTP 302 redirect with a Location header).

    redirectUrl uri

    Possible values: <= 255 characters

    URL the customer must be redirected to, only set if "returnType": "REDIRECT".

    redirectQRCode string

    QR Code with redirectUrl base64 encoded.

    htmlContent string

    HTML content the customer must be shown, only set if "returnType": "HTML".

    paymentDescriptor string
    paymentMethod string

    Payment method used - if it has already been determined.

    returnData

    object

    _TYPE

    string

    required

    Possible values: [cardData, phoneData, ibanData, walletData, achData]

    type string

    Type of credit card

    firstName string
    lastName string
    country Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    cardHolder string
    expiryMonth string

    Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$

    expiryYear string

    Possible values: Value must match regular expression ^[0-9]{4}$

    binDigits string

    Possible values: Value must match regular expression ^[0-9]{6-8}$

    firstSixDigits string

    Possible values: Value must match regular expression ^[0-9]{6}$

    lastFourDigits string

    Possible values: Value must match regular expression ^[0-9]{4}$

    fingerprint string
    binBrand string
    binBank string
    binType string
    binLevel string
    binCountry string
    threeDSecure ThreeDSecureType (string)

    Possible values: [OFF, OPTIONAL, MANDATORY]

    Triggers the 3D Secure authentication for this transaction.

    eci string
    merchantAdviceCode string

    Pipes through the merchant advice code for failed transactions if supported by the adapter.

    parsedMerchantAdviceCode string

    Possible values: [01, 02, 03]

    Merchant advice code for failed transactions if supported by the adapter.

    • 01 - Additional information needed.
    • 02 - Try again later.
    • 03 - Do not try again.
    schemeTransactionIdentifier string

    The schemeTransactionIdentifier, is a unique reference generated by a card scheme. It serves the purpose of traceability back to the initial transaction.

    It is also referred to as the 'scheme reference ID,' 'scheme transaction ID,' 'trace ID' (for Mastercard), or 'transaction ID' (for VISA).

    scheduleData

    object

    scheduleId string

    ID of schedule which was started with the transaction.

    scheduleStatus ScheduleStatus (string)

    Possible values: [ACTIVE, PAUSED, CANCELLED, ERROR, CREATE-PENDING, NON-EXISTING]

    Status of the schedule.

    scheduledAt date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$

    RFC 3339 Internet Date/Time Format date-time

    merchantMetaData string
    property name* any

    customerProfileData

    object

    profileGuid string

    The unique customer profile identifier generated by the platform.

    customerIdentification string

    The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.

    paymentToken string

    The created payment instrument for the customer profile, use with transactionToken when creating new transactions.

    markAsPreferred boolean

    Whether this payment instrument was marked as preferred for the customer.

    property name* any

    riskCheckData

    object

    riskCheckResult string

    Possible values: [APPROVED, DECLINED, REVIEW]

    riskScore number
    threeDSecureRequired boolean
    property name* any

    errors

    object[]

  • Array [

    • errorMessage string

    Error message.

    While the errorMessage field provides useful context for understanding the nature of the error, it's important to note that the content of this message can vary based on specific circumstances. For consistent and reliable error handling in your application, always base your logic on the errorCode field, not the errorMessage.

    errorCode int32

    Error code.

    For a complete list of error codes and their meanings, please see the appendix on Error codes.

    adapterMessage stringnullable

    Adapter specific error message, passed verbatim from the upstream Adapter.

    adapterCode stringnullable

    Adapter specific error code, passed verbatim from the upstream Adapter.

  • ]

    • adapterMessage string
    adapterCode string

    extraData

    object

    Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string

    dccData

    object

    uuid string
    originalAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    originalCurrency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    convertedAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    convertedCurrency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    conversionRate number
    disclaimer string
    property name* any

    payByLinkData

    object

    payByLink booleandeprecated

    true if this transaction was a Pay-by-Link transaction.

    sendViaEmail boolean

    true if this Pay-by-Link was sent to the transaction customer via email.

    cancelUrl uri

    Endpoint to call to cancel a Pay-by-Link transaction.

    For details, see Pay-by-Link API reference.

    expiresAt date-time

    Indicates at what date time the Pay-by-Link transaction expires.

    property name* any
    property name* any

Callbacks​

POST 
{$request.body#/callbackUrl}

Receive status updates about transactions.

Status changes are posted as callbacks to the callbackUrl defined in the request. See the Callbacks reference for further information about callbacks.

Body

required

The current state of the transaction.

    uuid string

    UUID of the transaction.

    merchantTransactionId string

    Possible values: non-empty and <= 50 characters

    Your unique transaction ID.

    purchaseId string

    Possible values: <= 50 characters

    Purchase ID of the transaction.

    transactionType TransactionType (string)

    Possible values: [DEBIT, CAPTURE, DEREGISTER, PREAUTHORIZE, REFUND, REGISTER, VOID, CHARGEBACK, CHARGEBACK-REVERSAL, PAYOUT, INCREMENTAL-AUTHORIZATION]

    paymentMethod string

    Payment method.

    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    surchargeAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    totalAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    dccData

    object

    remoteIdentifier string

    Possible values: <= 128 characters

    originalAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    originalCurrency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    convertedAmount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    convertedCurrency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    conversionRate number
    selectedCurrency string

    Possible values: <= 32 characters

    markUp number
    referenceUuid string

    Possible values: non-empty and <= 50 characters

    errors

    object[]

  • Array [

    • message string

    Error message.

    While the message field provides useful context for understanding the nature of the error, it's important to note that the content of this message can vary based on specific circumstances. For consistent and reliable error handling in your application, always base your logic on the code field, not the message.

    code string

    Error code.

    For a complete list of error codes and their meanings, please see the appendix on Error codes.

    adapterMessage stringnullable

    Adapter specific error message, passed verbatim from the upstream Adapter.

    adapterCode stringnullable

    Adapter specific error code, passed verbatim from the upstream Adapter.

  • ]

    • chargebackData

    object

    When transactionType is CHARGEBACK this field contains information on the chargeback.

    originalUuid string
    originalMerchantTransactionId string

    Possible values: non-empty and <= 50 characters

    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    reason string
    chargebackDateTime date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$

    RFC 3339 Internet Date/Time Format date-time

    property name* any

    When transactionType is CHARGEBACK this field contains information on the chargeback.

    chargebackReversalData

    object

    When transactionType is CHARGEBACK-REVERSAL this field contains information on the chargeback-reversal.

    originalUuid string
    originalMerchantTransactionId string

    Possible values: non-empty and <= 50 characters

    chargebackUuid string
    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    reason string
    reversalDateTime date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$

    RFC 3339 Internet Date/Time Format date-time

    property name* any

    When transactionType is CHARGEBACK-REVERSAL this field contains information on the chargeback-reversal.

    extraData

    object

    Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string
    merchantMetaData string

    returnData

    object

    _TYPE

    string

    required

    Possible values: [cardData, phoneData, ibanData, walletData, achData]

    type string

    Type of credit card

    firstName string
    lastName string
    country Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    cardHolder string
    expiryMonth string

    Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$

    expiryYear string

    Possible values: Value must match regular expression ^[0-9]{4}$

    binDigits string

    Possible values: Value must match regular expression ^[0-9]{6-8}$

    firstSixDigits string

    Possible values: Value must match regular expression ^[0-9]{6}$

    lastFourDigits string

    Possible values: Value must match regular expression ^[0-9]{4}$

    fingerprint string
    binBrand string
    binBank string
    binType string
    binLevel string
    binCountry string
    threeDSecure ThreeDSecureType (string)

    Possible values: [OFF, OPTIONAL, MANDATORY]

    Triggers the 3D Secure authentication for this transaction.

    eci string
    merchantAdviceCode string

    Pipes through the merchant advice code for failed transactions if supported by the adapter.

    parsedMerchantAdviceCode string

    Possible values: [01, 02, 03]

    Merchant advice code for failed transactions if supported by the adapter.

    • 01 - Additional information needed.
    • 02 - Try again later.
    • 03 - Do not try again.
    schemeTransactionIdentifier string

    The schemeTransactionIdentifier, is a unique reference generated by a card scheme. It serves the purpose of traceability back to the initial transaction.

    It is also referred to as the 'scheme reference ID,' 'scheme transaction ID,' 'trace ID' (for Mastercard), or 'transaction ID' (for VISA).

    payByLinkData

    object

    payByLink booleandeprecated

    true if this transaction was a Pay-by-Link transaction.

    sendViaEmail boolean

    true if this Pay-by-Link was sent to the transaction customer via email.

    cancelUrl uri

    Endpoint to call to cancel a Pay-by-Link transaction.

    For details, see Pay-by-Link API reference.

    expiresAt date-time

    Indicates at what date time the Pay-by-Link transaction expires.

    property name* any

    customer

    object

    identification string

    Possible values: <= 36 characters

    firstName string

    Possible values: <= 50 characters

    lastName string

    Possible values: <= 50 characters

    birthDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    gender string

    Possible values: [M, F]

    billingAddress1 string

    Possible values: <= 50 characters

    billingAddress2 string

    Possible values: <= 50 characters

    billingCity string

    Possible values: <= 50 characters

    billingPostcode string

    Possible values: <= 16 characters

    billingState string

    Possible values: <= 30 characters

    billingCountry Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    billingPhone string

    Possible values: <= 20 characters

    shippingFirstName string

    Possible values: <= 50 characters

    shippingLastName string

    Possible values: <= 50 characters

    shippingCompany string

    Possible values: <= 50 characters

    shippingAddress1 string

    Possible values: <= 50 characters

    shippingAddress2 string

    Possible values: <= 50 characters

    shippingCity string

    Possible values: <= 50 characters

    shippingPostcode string

    Possible values: <= 16 characters

    shippingState string

    Possible values: <= 30 characters

    shippingCountry Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    ISO 3166-1 alpha-2 country code.

    shippingPhone string

    Possible values: <= 20 characters

    company string

    Possible values: <= 50 characters

    email string

    Possible values: <= 255 characters

    emailVerified boolean
    ipAddress string

    Possible values: <= 50 characters

    nationalId string

    Possible values: <= 20 characters

    extraData

    object

    Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.

    Possible values: <= 64.
    Property name: <= 64 characters.
    Property value: <= 8192 characters.

    property name* string

    paymentData

    object

    oneOf

    ibanData

    object

    iban string

    Possible values: <= 34 characters

    bic string

    Possible values: <= 11 characters

    mandateId string

    Possible values: <= 50 characters

    mandateDate date (string)

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$

    RFC 3339 Internet Date/Time Format full-date.

    property name* any

    customerProfileData

    object

    profileGuid string

    The unique customer profile identifier generated by the platform.

    customerIdentification string

    The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.

    paymentToken string

    The created payment instrument for the customer profile, use with transactionToken when creating new transactions.

    markAsPreferred boolean

    Whether this payment instrument was marked as preferred for the customer.

    property name* any

    splits

    object[]

    Possible values: <= 10

  • Array [

    • identification string

    Possible values: <= 11 characters

    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    sellerMerchantGuid string

    Possible values: <= 11 characters

    sellerMerchantExternalId string

    Possible values: <= 128 characters

    commissionFee

    object

    amount Amount (string)

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    Decimal amount separated by ., maximum of 3 decimals.

    currency Currency (string)

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code.

    property name* any

  • ]

    • message string

    Error message.

    While the message field provides useful context for understanding the nature of the error, it's important to note that the content of this message can vary based on specific circumstances. For consistent and reliable error handling in your application, always base your logic on the code field, not the message.

    code string

    Error code.

    For a complete list of error codes and their meanings, please see the appendix on Error codes.

    adapterMessage stringnullable

    Adapter specific error message, passed verbatim from the upstream Adapter.

    adapterCode stringnullable

    Adapter specific error code, passed verbatim from the upstream Adapter.

    result string

    Possible values: [OK, PENDING, ERROR]

    scheduleData

    object[]

  • Array [

    • scheduleId string

    ID of schedule which was started with the transaction.

    scheduleStatus ScheduleStatus (string)

    Possible values: [ACTIVE, PAUSED, CANCELLED, ERROR, CREATE-PENDING, NON-EXISTING]

    Status of the schedule.

    scheduledAt date-time

    Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$

    RFC 3339 Internet Date/Time Format date-time

    merchantMetaData string

  • ]

    • notificationSource string

    Possible values: [reconciliation, settlement]

    In case the transaction status, amount or currency has been changed after reconciliation the parameter can have the following value: reconciliation, settlement.

    originalAmount string

    Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$

    In case the transaction amount has been changed after reconciliation the is parameter will contain the original amount. Decimals separated by ., max. 3 decimals.

    originalCurrency string

    Possible values: Value must match regular expression ^[A-Z]{3}$

    In case the transaction currency has been changed after reconciliation the is parameter will contain the original currency.

    ISO 4217 three-letter currency code.

Callbacks Responses​

Reply with status 200 and body OK if you have received the callback successfully.

Schema

    string

    Possible values: [OK]

Loading...
Last updated on