Skip to main content

Incremental authorization

POST 

https://gateway.ixopay.com/api/v3/transaction/:apiKey/incrementalAuthorization

An incremental authorization increases or prolongs the authorized amount on the customer's payment instrument.

Currently, the incremental authorization is only supported by a few adapters.

A follow-up capture transaction may capture the full amount of the initial transaction and all its subsequent incremental authorizations.

warning

The follow-up capture transaction must refer to the initial preauthorize!

Request

Path Parameters

    apiKey stringrequired

    Possible values: <= 50 characters

    API Key of Connector

Bodyrequired

Data which is required to process incremental auth transactions.

    merchantTransactionIdMerchantTransactionId (string)required

    A unique identifier supplied by the merchant to track transactions within their own systems.

    This field links the platform’s transaction back to the merchant’s system, allowing for easy tracking and reconciliation. Note that while this ID is used within the platform, there is no guarantee that it will be forwarded to the Payment Service Provider (PSP).

    Possible values: non-empty and <= 50 characters

    Example: c5f2accd-2c37-4b2c-bb03-22d168c25a74
    referenceUuidstringrequired

    Possible values: non-empty and <= 50 characters

    additionalId1AdditionalId1 (string)

    A supplementary identifier dependent on the used adapter.

    This field provides additional information that can be used based on the specific adapter and their field mappings. The usage of additionalId1 is contingent upon the support provided by the PSP, which is detailed in the adapter-specific documentation. If this field is supported, its proper usage will be outlined there. If it is not mentioned, it should not be used to avoid integration issues. Always refer to the adapter-specific documentation for guidance on using this additional identifier correctly.

    Possible values: non-empty and <= 50 characters

    additionalId2AdditionalId2 (string)

    A supplementary identifier dependent on the used adapter.

    This field provides additional information that can be used based on the specific adapter and their field mappings. The usage of additionalId2 is contingent upon the support provided by the PSP, which is detailed in the adapter-specific documentation. If this field is supported, its proper usage will be outlined there. If it is not mentioned, it should not be used to avoid integration issues. Always refer to the adapter-specific documentation for guidance on using this additional identifier correctly.

    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
    merchantMetaDatastring

    Possible values: <= 255 characters

    amountAmount (string)required

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)required

    ISO 4217 three-letter currency code.

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

    Example: EUR
    successUrluri

    Possible values: <= 4096 characters

    cancelUrluri

    Possible values: <= 4096 characters

    errorUrluri

    Possible values: <= 4096 characters

    callbackUrluri

    Possible values: <= 4096 characters

    descriptionstring

    Description of your transaction.

    This might show up on a credit-card statement (depends on Adapter and PSP).

    Possible values: <= 255 characters

    items object[]

    List of items sold.

    Maximum JSON size: <= 32768 bytes.

    Possible values: <= 128

  • Array [
  • identificationstring

    Possible values: <= 128 characters

    namestring

    Possible values: <= 256 characters

    descriptionstring

    Possible values: <= 2048 characters

    quantityinteger

    Possible values: >= 1

    priceinteger

    Possible values: >= 1

    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    l2l3Data object
    typestring

    Possible values: <= 32 characters

    unitstring

    Possible values: <= 16 characters

    unitPriceAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    discountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    shippingAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    taxAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    taxRateAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    commodityCodestring

    Possible values: <= 64 characters

    taxDetails object[]

    Possible values: <= 10

  • Array [
  • typestring

    Possible values: <= 255 characters

    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    rateAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    codestring

    Possible values: <= 255 characters

    taxIdstring

    Possible values: <= 255 characters

    appliedstring

    Possible values: <= 255 characters

    exemptionCodestring

    Possible values: <= 255 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
  • ]
  • transactionIndicatorstring

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

    languagestring

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

    l2l3Data object

    Level 2 & level 3 data.

    taxAmountstring

    Possible values: <= 15 characters

    vatRegistrationNumberstring

    Possible values: <= 255 characters

    nationalTaxIncludedstring

    Possible values: <= 5 characters

    discountAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    commodityCodestring

    Possible values: <= 255 characters

    freightAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    freightTaxAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    dutyAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    taxDetails object[]

    Possible values: <= 10

  • Array [
  • typestring

    Possible values: <= 255 characters

    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    rateAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    codestring

    Possible values: <= 255 characters

    taxIdstring

    Possible values: <= 255 characters

    appliedstring

    Possible values: <= 255 characters

    exemptionCodestring

    Possible values: <= 255 characters

  • ]

Responses

Transaction response

Schema
    success booleanrequired

    Possible values: [true, false]

    successbooleanrequired

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

    uuidstring

    UUID of the transaction.

    purchaseIdstring

    Purchase ID of the transaction.

    returnTypestring

    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.

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

    redirectTypestring

    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).

    Possible values: [iframe, fullpage]

    redirectUrluri

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

    Possible values: <= 255 characters

    redirectQRCodestring

    QR Code with redirectUrl base64 encoded.

    htmlContentstring

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

    paymentDescriptorstring
    paymentMethodstring

    Payment method used - if it has already been determined.

    returnData object
    _TYPE ReturnDataType (string)required

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

    typestring

    Type of credit card

    firstNamestring
    lastNamestring
    countryCountry (string)

    ISO 3166-1 alpha-2 country code.

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

    Example: AT
    cardHolderstring
    expiryMonthstring

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

    expiryYearstring

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

    binDigitsstring

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

    firstSixDigitsstring

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

    lastFourDigitsstring

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

    fingerprintstring
    binBrandstring
    binBankstring
    binTypestring
    binLevelstring
    binCountrystring
    threeDSecureThreeDSecureType (string)

    Triggers the 3D Secure authentication for this transaction.

    Possible values: [OFF, OPTIONAL, MANDATORY]

    ecistring
    merchantAdviceCodestring

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

    parsedMerchantAdviceCodestring

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

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

    Possible values: [01, 02, 03]

    schemeTransactionIdentifierstring

    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).

    cardUpdateStatusstringnullable

    Status of the last account updater run.

    Only non-null if the account updater is enabled and has run at least once.

    Possible values: [updated, contact, new-expiry, closed]

    cardUpdatedAtdate (string)nullable

    Last run of the account updater.

    Only non-null if the account updater is enabled and has run at least once. RFC 3339 Internet Date/Time Format full-date.

    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]))$

    Example: 2001-02-03
    scheduleData object
    scheduleIdstring

    ID of schedule which was started with the transaction.

    scheduleStatusScheduleStatus (string)

    Status of the schedule.

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

    scheduledAtdate-time

    RFC 3339 Internet Date/Time Format 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}$

    Example: 2001-02-03T04:05:06+02:00
    merchantMetaDatastring
    property name*any
    customerProfileData object
    profileGuidstring

    The unique customer profile identifier generated by the platform.

    customerIdentificationstring

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

    paymentTokenstring

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

    markAsPreferredboolean

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

    property name*any
    riskCheckData object
    riskCheckResultstring

    Possible values: [APPROVED, DECLINED, REVIEW]

    riskScorenumber
    threeDSecureRequiredboolean
    property name*any
    errors object[]
  • Array [
  • errorMessagestring

    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.

    errorCodeint32

    Error code.

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

    adapterMessagestringnullable

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

    adapterCodestringnullable

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

  • ]
  • adapterMessagestring
    adapterCodestring
    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
    uuidstring
    originalAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    originalCurrencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    convertedAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    convertedCurrencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    conversionRatenumber
    disclaimerstring
    property name*any
    payByLinkData object
    payByLinkbooleandeprecated

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

    sendViaEmailboolean

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

    cancelUrluri

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

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

    expiresAtdate-time

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

    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.

Bodyrequired

The current state of the transaction.

    uuidstring

    UUID of the transaction.

    merchantTransactionIdMerchantTransactionId (string)

    A unique identifier supplied by the merchant to track transactions within their own systems.

    This field links the platform’s transaction back to the merchant’s system, allowing for easy tracking and reconciliation. Note that while this ID is used within the platform, there is no guarantee that it will be forwarded to the Payment Service Provider (PSP).

    Possible values: non-empty and <= 50 characters

    Example: c5f2accd-2c37-4b2c-bb03-22d168c25a74
    purchaseIdstring

    Purchase ID of the transaction.

    Possible values: <= 50 characters

    transactionTypeTransactionType (string)

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

    transactionSubTypeTransactionSubType (string)

    Only present if transaction has a subType.

    Possible values: [cb-resolved, cb-reversal-resolved]

    paymentMethodstring

    Payment method.

    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    surchargeAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    totalAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    dccData object
    remoteIdentifierstring

    Possible values: <= 128 characters

    originalAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    originalCurrencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    convertedAmountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    convertedCurrencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    conversionRatenumber
    selectedCurrencystring

    Possible values: <= 32 characters

    markUpnumber
    referenceUuidstring

    Possible values: non-empty and <= 50 characters

    errors object[]
  • Array [
  • messagestring

    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.

    codestring

    Error code.

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

    adapterMessagestringnullable

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

    adapterCodestringnullable

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

  • ]
  • chargebackData object

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

    originalUuidstring
    originalMerchantTransactionIdstring

    Possible values: non-empty and <= 50 characters

    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    reasonstring
    chargebackDateTimedate-time

    RFC 3339 Internet Date/Time Format 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}$

    Example: 2001-02-03T04:05:06+02:00
    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.

    originalUuidstring
    originalMerchantTransactionIdstring

    Possible values: non-empty and <= 50 characters

    chargebackUuidstring
    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    reasonstring
    reversalDateTimedate-time

    RFC 3339 Internet Date/Time Format 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}$

    Example: 2001-02-03T04:05:06+02:00
    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
    merchantMetaDatastring
    returnData object
    _TYPE ReturnDataType (string)required

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

    typestring

    Type of credit card

    firstNamestring
    lastNamestring
    countryCountry (string)

    ISO 3166-1 alpha-2 country code.

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

    Example: AT
    cardHolderstring
    expiryMonthstring

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

    expiryYearstring

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

    binDigitsstring

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

    firstSixDigitsstring

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

    lastFourDigitsstring

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

    fingerprintstring
    binBrandstring
    binBankstring
    binTypestring
    binLevelstring
    binCountrystring
    threeDSecureThreeDSecureType (string)

    Triggers the 3D Secure authentication for this transaction.

    Possible values: [OFF, OPTIONAL, MANDATORY]

    ecistring
    merchantAdviceCodestring

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

    parsedMerchantAdviceCodestring

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

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

    Possible values: [01, 02, 03]

    schemeTransactionIdentifierstring

    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).

    cardUpdateStatusstringnullable

    Status of the last account updater run.

    Only non-null if the account updater is enabled and has run at least once.

    Possible values: [updated, contact, new-expiry, closed]

    cardUpdatedAtdate (string)nullable

    Last run of the account updater.

    Only non-null if the account updater is enabled and has run at least once. RFC 3339 Internet Date/Time Format full-date.

    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]))$

    Example: 2001-02-03
    payByLinkData object
    payByLinkbooleandeprecated

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

    sendViaEmailboolean

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

    cancelUrluri

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

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

    expiresAtdate-time

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

    property name*any
    customer object
    identificationstring

    Possible values: <= 36 characters

    firstNamestring

    Possible values: <= 50 characters

    lastNamestring

    Possible values: <= 50 characters

    birthDatedate (string)

    RFC 3339 Internet Date/Time Format full-date.

    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]))$

    Example: 2001-02-03
    genderstring

    Possible values: [M, F]

    billingAddress1string

    Possible values: <= 50 characters

    billingAddress2string

    Possible values: <= 50 characters

    billingCitystring

    Possible values: <= 50 characters

    billingPostcodestring

    Possible values: <= 16 characters

    billingStatestring

    Possible values: <= 30 characters

    billingCountryCountry (string)

    ISO 3166-1 alpha-2 country code.

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

    Example: AT
    billingPhonestring

    Possible values: <= 20 characters

    Example: +XX 1234567890
    shippingFirstNamestring

    Possible values: <= 50 characters

    shippingLastNamestring

    Possible values: <= 50 characters

    shippingCompanystring

    Possible values: <= 50 characters

    shippingAddress1string

    Possible values: <= 50 characters

    shippingAddress2string

    Possible values: <= 50 characters

    shippingCitystring

    Possible values: <= 50 characters

    shippingPostcodestring

    Possible values: <= 16 characters

    shippingStatestring

    Possible values: <= 30 characters

    shippingCountryCountry (string)

    ISO 3166-1 alpha-2 country code.

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

    Example: AT
    shippingPhonestring

    Possible values: <= 20 characters

    Example: +XX 1234567890
    companystring

    Possible values: <= 50 characters

    emailstring

    Possible values: <= 255 characters

    emailVerifiedboolean
    ipAddressstring

    Possible values: <= 50 characters

    nationalIdstring

    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
    ibanstring

    Possible values: <= 34 characters

    bicstring

    Possible values: <= 11 characters

    mandateIdstring

    Possible values: <= 50 characters

    mandateDatedate (string)

    RFC 3339 Internet Date/Time Format full-date.

    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]))$

    Example: 2001-02-03
    property name*any
    customerProfileData object
    profileGuidstring

    The unique customer profile identifier generated by the platform.

    customerIdentificationstring

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

    paymentTokenstring

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

    markAsPreferredboolean

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

    property name*any
    splits object[]

    Possible values: <= 10

  • Array [
  • identificationstring

    Possible values: <= 11 characters

    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    sellerMerchantGuidstring

    Possible values: <= 11 characters

    sellerMerchantExternalIdstring

    Possible values: <= 128 characters

    commissionFee object
    amountAmount (string)

    Decimal amount separated by ., maximum of 3 decimals.

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

    Example: 9.99
    currencyCurrency (string)

    ISO 4217 three-letter currency code.

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

    Example: EUR
    property name*any
  • ]
  • messagestring

    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.

    codestring

    Error code.

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

    adapterMessagestringnullable

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

    adapterCodestringnullable

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

    resultstring

    Possible values: [OK, PENDING, ERROR]

    scheduleData object[]
  • Array [
  • scheduleIdstring

    ID of schedule which was started with the transaction.

    scheduleStatusScheduleStatus (string)

    Status of the schedule.

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

    scheduledAtdate-time

    RFC 3339 Internet Date/Time Format 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}$

    Example: 2001-02-03T04:05:06+02:00
    merchantMetaDatastring
  • ]
  • notificationSourcestring

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

    Possible values: [reconciliation, settlement]

    originalAmountstring

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

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

    originalCurrencystring

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

    ISO 4217 three-letter currency code.

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

    Example: EUR

Callbacks Responses

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

Schema
    stringstring

    Possible values: [OK]

Authorization: http

name: basicAuthtype: httpscheme: basicdescription: To authenticate API requests, the API username and password must be sent as BASIC Authentication in the `Authorization` header,
as defined in [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617).
To achieve this, the username and password are first concatenated with a `:` (colon) separator,
and the resulting string is then Base64 encoded. Here is an example of how this process works:

1. Suppose the API username is `anyApiUser` and the password is `myPassword`.
2. Concatenate the username and password with a `:` separator: `anyApiUser:myPassword`.
3. Base64 encode the concatenated string: `YW55QXBpVXNlcjpteVBhc3N3b3JkCg==`.
4. Finally, include the `Authorization` header in the API request with the Base64 encoded string, like so: `Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3Jk`.

:::tip
Many programming frameworks will automatically handle the BASIC Authentication process for you once you provide the username and password to the appropriate request object.
:::
curl -L 'https://gateway.ixopay.com/api/v3/transaction/:apiKey/incrementalAuthorization' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic PHVzZXJuYW1lPjo8cGFzc3dvcmQ+' \
-d '{
"merchantTransactionId": "c5f2accd-2c37-4b2c-bb03-22d168c25a74",
"referenceUuid": "string",
"additionalId1": "string",
"additionalId2": "string",
"extraData": {},
"merchantMetaData": "string",
"amount": "9.99",
"currency": "EUR",
"successUrl": "string",
"cancelUrl": "string",
"errorUrl": "string",
"callbackUrl": "string",
"description": "string",
"items": [
{
"identification": "string",
"name": "string",
"description": "string",
"quantity": 0,
"price": 0,
"currency": "EUR",
"l2l3Data": {
"type": "string",
"unit": "string",
"unitPrice": "9.99",
"discount": "9.99",
"shippingAmount": "9.99",
"taxAmount": "9.99",
"taxRate": "9.99",
"commodityCode": "string",
"taxDetails": [
{
"type": "string",
"amount": "9.99",
"rate": "9.99",
"code": "string",
"taxId": "string",
"applied": "string",
"exemptionCode": "string"
}
]
},
"extraData": {}
}
],
"transactionIndicator": "SINGLE",
"language": "string",
"l2l3Data": {
"taxAmount": "string",
"vatRegistrationNumber": "string",
"nationalTaxIncluded": "string",
"discountAmount": "9.99",
"commodityCode": "string",
"freightAmount": "9.99",
"freightTaxAmount": "9.99",
"dutyAmount": "9.99",
"taxDetails": [
{
"type": "string",
"amount": "9.99",
"rate": "9.99",
"code": "string",
"taxId": "string",
"applied": "string",
"exemptionCode": "string"
}
]
}
}'
Request Collapse all
Base URL
https://gateway.ixopay.com/api/v3
Auth
Parameters
— pathrequired
Body required
{
  "merchantTransactionId": "c5f2accd-2c37-4b2c-bb03-22d168c25a74",
  "referenceUuid": "string",
  "additionalId1": "string",
  "additionalId2": "string",
  "extraData": {},
  "merchantMetaData": "string",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "string",
  "cancelUrl": "string",
  "errorUrl": "string",
  "callbackUrl": "string",
  "description": "string",
  "items": [
    {
      "identification": "string",
      "name": "string",
      "description": "string",
      "quantity": 0,
      "price": 0,
      "currency": "EUR",
      "l2l3Data": {
        "type": "string",
        "unit": "string",
        "unitPrice": "9.99",
        "discount": "9.99",
        "shippingAmount": "9.99",
        "taxAmount": "9.99",
        "taxRate": "9.99",
        "commodityCode": "string",
        "taxDetails": [
          {
            "type": "string",
            "amount": "9.99",
            "rate": "9.99",
            "code": "string",
            "taxId": "string",
            "applied": "string",
            "exemptionCode": "string"
          }
        ]
      },
      "extraData": {}
    }
  ],
  "transactionIndicator": "SINGLE",
  "language": "string",
  "l2l3Data": {
    "taxAmount": "string",
    "vatRegistrationNumber": "string",
    "nationalTaxIncluded": "string",
    "discountAmount": "9.99",
    "commodityCode": "string",
    "freightAmount": "9.99",
    "freightTaxAmount": "9.99",
    "dutyAmount": "9.99",
    "taxDetails": [
      {
        "type": "string",
        "amount": "9.99",
        "rate": "9.99",
        "code": "string",
        "taxId": "string",
        "applied": "string",
        "exemptionCode": "string"
      }
    ]
  }
}