Debit
POST/transaction/:apiKey/debit
A Debit performs a complete customer initiated customer-to-merchant payment.
Request
Path Parameters
Possible values: <= 50 characters
API Key of Connector
- application/json
Bodyrequired
required
Data which is required to process a debit transaction.
Array [
Array [
]
]
Array [
]
- PaymentIbanData
- PaymentWalletData
- 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. 01
- App-based02
- Browser03
- 3DS Requestor Initiated01
- Payment transaction02
- Recurring transaction03
- Installment transaction04
- Add card05
- Maintain card06
- Cardholder verification as part of EMV token ID&V01
- 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 credentials03
- Login to the cardholder account at the 3DS Requestor system using federated ID04
- Login to the cardholder account at the 3DS Requestor system using issuer credentials05
- Login to the cardholder account at the 3DS Requestor system using third-party authentication06
- Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator01
- No preference02
- No challenge requested03
- Challenge requested: 3DS Requestor Preference04
- Challenge requested: Mandate05
- 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)01
- Frictionless authentication occurred by ACS02
- Cardholder challenge occurred by ACS03
- AVS verified04
- Other issuer methods01
- Not applicable02
- Credit03
- Debit04
- JCB specific value for Prepaid01
- No account (guest check-out)02
- During this transaction03
- Less than 30 days04
- 30—60 days05
- More than 60 days01
- Changed during this transaction02
- Less than 30 days03
- 30—60 days04
- More than 60 days01
- No change02
- Changed during this transaction03
- Less than 30 days04
- 30—60 days05
- More than 60 days01
- Changed during this transaction02
- Less than 30 days03
- 30—60 days04
- More than 60 days01
- No suspicious activity has been observed02
- Suspicious activity has been observed01
- Account Name identical to shipping name02
- Account Name different from shipping name01
- No account (guest check-out)02
- During this transaction03
- Less than 30 days04
- 30—60 days05
- More than 60 daysY
- Shipping Address matches Billing AddressN
- Shipping Address does not match Billing Address01
- Ship to cardholder's billing address02
- Ship to another verified address on file with merchant03
- Ship to address that is different from the cardholder's billing address04
- "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 shipped07
- Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)01
- Electronic Delivery02
- Same day shipping03
- Overnight shipping04
- Two-day or more shipping01
- First time ordered02
- Reordered01
- Merchandise available02
- Future availability01
- Goods / Service purchase03
- Check Acceptance10
- Account Funding11
- Quasi-Cash Transaction28
- Prepaid activation and Loan01
- Low Value Transaction (amount under 30 EUR)02
- Low Risk Transaction03
- Whitelisted transaction, merchant is added as "Trusted Beneficiary" by cardholder04
- Secure Corporate Payment05
- Recurring or Merchant-initiated transaction06
- Mail or Telephone Order07
- Anonymous payment card01
- Recurring transaction02
- Installment transaction03
- Add card04
- Maintain card information05
- Account verification.06
- Split/delayed shipment07
- Top-up08
- Mail order09
- Telephone order10
- Whitelist status check11
- Other payment12
- Billing agreement.01
- 250x40002
- 390x40003
- 500x60004
- 600x40005
- Full screen- 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
1
- 1 bit4
- 4 bits8
- 8 bits15
- 15 bits16
- 16 bits24
- 24 bits32
- 32 bits48
- 48 bits01
- Native02
- HTML03
- Both01
- Text02
- Single select03
- Multi select04
- OOB05
- Html Other (valid only for HTML UI)Array [
]
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
c5f2accd-2c37-4b2c-bb03-22d168c25a74
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
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
.
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
.
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 |
.
Possible values: <= 255 characters
anyValue1|anotherValue2
UUID of an initial transaction.
Possible values: non-empty
and <= 50 characters
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}))$
9.99
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Redirect to URL on success/pending.
Possible values: <= 4096 characters
https://shop.example.org/checkout/success
Redirect to URL on cancel.
Possible values: <= 4096 characters
https://shop.example.org/checkout/cancel
Redirect to URL on error.
Possible values: <= 4096 characters
https://shop.example.org/checkout/error
Endpoint to receive status notifications.
Possible values: <= 4096 characters
https://api.example.org/callback
Token generated via payment.js.
Possible values: <= 8192 characters
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
Possible values: <= 128 characters
Possible values: <= 256 characters
Possible values: <= 2048 characters
Possible values: >= 1
Possible values: >= 1
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
l2l3Data
object
Possible values: <= 32 characters
Possible values: <= 16 characters
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}))$
9.99
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}))$
9.99
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}))$
9.99
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}))$
9.99
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}))$
9.99
Possible values: <= 64 characters
taxDetails
object[]
Possible values: <= 10
Possible values: <= 255 characters
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}))$
9.99
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}))$
9.99
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
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
.
splits
object[]
Possible values: <= 10
Possible values: <= 11 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Possible values: <= 11 characters
Possible values: <= 128 characters
commissionFee
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
If true
, store customer's payment instrument for recurring transactions.
Instructs the acquirer which kind of payment you are planning.
Passing the correct value reduces friction and might increase the likelihood of a 3DS 2.0 frictionless flow.
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.
Possible values: <= 36 characters
First name of the customer.
Possible values: <= 50 characters
Last name of the customer.
Possible values: <= 50 characters
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]))$
2001-02-03
Gender of the customer.
Possible values: [M
, F
]
Line one of the customer's billing address.
Possible values: <= 50 characters
Line two of the customer's billing address.
Possible values: <= 50 characters
City of the customer's billing address.
Possible values: <= 50 characters
Postal code of the customer's billing address.
Possible values: <= 16 characters
State of the customer's billing address.
Possible values: <= 30 characters
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: <= 20 characters
+XX 1234567890
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 16 characters
Possible values: <= 30 characters
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: <= 20 characters
+XX 1234567890
Possible values: <= 50 characters
Possible values: <= 255 characters
Possible values: <= 50 characters
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
.
paymentData
object
oneOf
ibanData
object
Possible values: <= 34 characters
Possible values: <= 11 characters
Possible values: <= 50 characters
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]))$
2001-02-03
walletData
object
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
schedule
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
The length of the duration, measured in periodUnit
.
The unit that the duration is measured in.
Possible values: [DAY
, WEEK
, MONTH
, YEAR
]
MONTH
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}$
2001-02-03T04:05:06+02:00
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 |
.
Possible values: <= 255 characters
Endpoint to receive status notifications.
Possible values: <= 4096 characters
https://api.example.org/callback
customerProfileData
object
Reference to a customer profile created with the Customer Profile API.
Either profileGuid
or customerIdentification
MUST be provided.
The unique customer profile identifier created by the platform.
Supply this field to register a new payment instrument with an existing customer profile.
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.
Possible values: <= 36 characters
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.
Triggers the 3D Secure authentication for this transaction.
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
"Pin" the scheme ID in case of a co-branded card.
Currently, there is only CB supported.
Possible values: [CB
]
CB
Indicates the type of channel interface being used to initiate the transaction.
Possible values: [01
, 02
, 03
]
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.
Possible values: [01
, 02
, 03
, 04
, 05
, 06
]
Mechanism used by the Cardholder to authenticate to the 3DS Requester.
Possible values: [01
, 02
, 03
, 04
, 05
, 06
]
Date and time in UTC of the cardholder authentication.
2001-02-03T04:05:06+02:00
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.
Possible values: <= 1024 characters
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.
Possible values: [01
, 02
, 03
, 04
, 05
, 06
, 07
, 08
, 09
]
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).
Possible values: <= 36 characters
Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
Possible values: [01
, 02
, 03
, 04
]
RFC 3339 Internet Date/Time Format date " " time
without timespec-second
, time-fraction
, and time-zone
.
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])$
2001-02-03 04:05
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.
Possible values: <= 2048 characters
Indicates the type of account. For example, for a multi-account card product.
Possible values: [01
, 02
, 03
, 04
]
Length of time that the cardholder has had the account with the 3DS Requester.
Possible values: [01
, 02
, 03
, 04
, 05
]
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]))$
2001-02-03
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.
Possible values: [01
, 02
, 03
, 04
]
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.
2001-02-03T04:05:06+02:00
Length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
Possible values: [01
, 02
, 03
, 04
, 05
]
Date that cardholder’s account with the 3DS Requestor had a password change or account.
2001-02-03
Indicates when the shipping address used for this transaction was first used with the 3DS.
Possible values: [01
, 02
, 03
, 04
]
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]))$
2001-02-03
Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
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.
Possible values: <= 999
Number of Add Card attempts in the last 24 hours.
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.
Possible values: <= 999
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
Possible values: [01
, 02
]
Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
Possible values: [01
, 02
]
Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Possible values: [01
, 02
, 03
, 04
, 05
]
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]))$
2001-02-03
Line 3 of customer's billing address.
Possible values: <= 128 characters
State of the customer's billing address.
Possible values: Value must match regular expression ^[A-Z0-9]{1,3}$
Line 3 of customer's shipping address.
Possible values: <= 128 characters
State of the customer's shipping address.
Possible values: Value must match regular expression ^[A-Z0-9]{1,3}$
Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.
Possible values: [Y
, N
]
Country Code of the home phone, ITU E.164.
Possible values: non-empty
and <= 3 characters
Subscriber section of the number.
Possible values: <= 15 characters
Country Code of the mobile phone, ITU E.164.
Possible values: non-empty
and <= 3 characters
Subscriber section of the number.
Possible values: <= 15 characters
Country Code of the work phone, ITU E.164.
Possible values: non-empty
and <= 3 characters
Subscriber section of the number.
Possible values: <= 15 characters
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.
Possible values: >= 1
and <= 999
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.
Possible values: [01
, 02
, 03
, 04
, 05
, 06
, 07
]
Indicates the merchandise delivery timeframe.
Possible values: [01
, 02
, 03
, 04
]
For electronic delivery, the email address to which the merchandise was delivered.
Possible values: <= 128 characters
Indicates whether the cardholder is reordering previously purchased merchandise.
Possible values: [01
, 02
]
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
Possible values: [01
, 02
]
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]))$
2001-02-03
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
).
Possible values: <= 999999999999999
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
Possible values: >= 1
and <= 99
RFC 3339 Internet Date/Time Format date " " time
without timespec-second
, time-fraction
, and time-zone
.
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])$
2001-02-03 04:05
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]))$
2001-02-03
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
.
Possible values: <= 9999
Identifies the type of transaction being authenticated.
The values are derived from ISO 8583.
Possible values: [01
, 03
, 10
, 11
, 28
]
Requests an SCA exemption for this transaction.
Possible values are:
Possible values: [01
, 02
, 03
, 04
, 05
, 06
, 07
]
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:
Possible values: [01
, 02
, 03
, 04
, 05
, 06
, 07
, 08
, 09
, 10
, 11
, 12
]
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.
Possible values: [01
, 02
, 03
, 04
, 05
]
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser
Possible values: <= 2048 characters
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
Possible values: <= 56 characters
Boolean that represents the ability of the cardholder browser to execute Java.
Value is returned from the navigator.javaEnabled
property.
Value representing the browser language as defined in IETF BCP47.
Value is returned from navigator.language
property.
Possible values: non-empty
and <= 8 characters
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.
Possible values: [1
, 4
, 8
, 15
, 16
, 24
, 30
, 32
, 48
]
Total height of the Cardholder's screen in pixels.
Value is returned from the screen.height
property.
Total width of the Cardholder's screen in pixels.
Value is returned from the screen.width
property.
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.
Possible values: >= -9999
and <= 9999
Exact content of the HTTP user-agent header.
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.
Possible values: <= 2048 characters
Specifies all the SDK interface types that the device supports for displaying specific challenge user interfaces within the SDK.
Accepted values are:
Possible values: [01
, 02
, 03
]
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:
Possible values: Value must match regular expression ^(0[1-5]( *, *0[0-5])*)?$
01,02,05
Universally e created upon all installations and updates of the 3DS Requestor App on a Customer Device.
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.
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
,
Possible values: <= 128 characters
{"kty":"EC","crv":"P-256","x":"...","y":"..."}
Indicates the maximum amount of time (in minutes) for all exchanges.
Possible values: >= 5
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.
Possible values: <= 32 characters
Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.
Possible values: <= 128 characters
payByLink
object
Enable generating a link that can be sent to a customer to complete a purchase.
If true
send the generated payment link to the customer via email.
The email specified in customer.email
is used as recipient.
The generated payment link will expire after the duration specified via this field.
Possible values: >= 1
1441
Enable direct currency conversion (DCC).
dccData
object
Possible values: <= 128 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Possible values: <= 32 characters
l2l3Data
object
Level 2 & level 3 data.
Possible values: <= 15 characters
Possible values: <= 255 characters
Possible values: <= 5 characters
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}))$
9.99
Possible values: <= 255 characters
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}))$
9.99
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}))$
9.99
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}))$
9.99
taxDetails
object[]
Possible values: <= 10
Possible values: <= 255 characters
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}))$
9.99
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}))$
9.99
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 50 characters
IXHKDJRR462950
Possible values: <= 50 characters
Responses
- 200
- 400
- 422
Transaction response
- application/json
- Schema
- Example (from schema)
- Finished
- Redirect
- Processing error
Schema
- true
- false
-
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
andadapterCode
.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 insuccessUrl
,cancelUrl
orerrorUrl
). In parallel thesends 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.
- cardData
- phoneData
- ibanData
- walletData
- achData
01
- Additional information needed.02
- Try again later.03
- Do not try again.Array [
]
Array [
]
success
string
required
Returns true
or false
depending on whether the request was successful.
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
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
]
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
Possible values: <= 255 characters
QR Code with redirectUrl base64 encoded.
HTML content the customer must be shown, only set if "returnType": "HTML"
.
Payment method used - if it has already been determined.
returnData
object
_TYPE
string
required
Possible values: [cardData
, phoneData
, ibanData
, walletData
, achData
]
Type of credit card
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$
Possible values: Value must match regular expression ^[0-9]{4}$
Possible values: Value must match regular expression ^[0-9]{6-8}$
Possible values: Value must match regular expression ^[0-9]{6}$
Possible values: Value must match regular expression ^[0-9]{4}$
Triggers the 3D Secure authentication for this transaction.
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
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).
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
]
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Reference ID of the wallet.
Owner of the wallet.
Type of wallet.
First name of wallet owner.
Last name of wallet owner.
Country code of wallet owner.
UUID of the transaction that initially registered this wallet.
Possible values: [person
, company
]
Possible values: [checking
, savings
]
Possible values: <= 17 characters
Possible values: >= 9 characters
and <= 9 characters
scheduleData
object
ID of schedule which was started with the transaction.
Status of the schedule.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
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}$
2001-02-03T04:05:06+02:00
customerProfileData
object
The unique customer profile identifier generated by the platform.
The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.
The created payment instrument for the customer profile, use with transactionToken
when creating new transactions.
Whether this payment instrument was marked as preferred for the customer.
riskCheckData
object
Possible values: [APPROVED
, DECLINED
, REVIEW
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
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
.
dccData
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
payByLinkData
object
true
if this transaction was a Pay-by-Link transaction.
true
if this Pay-by-Link was sent to the transaction customer via email.
Endpoint to call to cancel a Pay-by-Link transaction.
For details, see Pay-by-Link API reference.
Indicates at what date time the Pay-by-Link transaction expires.
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
Possible values: [ERROR
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
{
"success": true
}
"returnType": "FINISHED"
indicates a successfully completed debit payment.
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
Redirect indicates that the customer should be redirected to the URL in redirectURL
.
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://psp.example.org/c5f2accd-2c37-4b2c-bb03-22d168c25a74",
"redirectQRCode": "data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"paymentMethod": "Creditcard"
}
An error occurred on the PSPs side.
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20200924-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Dummy",
"errors": [
{
"errorMessage": "Dummy error",
"errorCode": 1003,
"adapterMessage": "Dummy adapter error"
}
]
}
Transaction error response
- application/json
- Schema
- Example (from schema)
- General error, e.g. duplicate
Schema
- true
- false
-
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
andadapterCode
.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 insuccessUrl
,cancelUrl
orerrorUrl
). In parallel thesends 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.
- cardData
- phoneData
- ibanData
- walletData
- achData
01
- Additional information needed.02
- Try again later.03
- Do not try again.Array [
]
Array [
]
success
string
required
Returns true
or false
depending on whether the request was successful.
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
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
]
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
Possible values: <= 255 characters
QR Code with redirectUrl base64 encoded.
HTML content the customer must be shown, only set if "returnType": "HTML"
.
Payment method used - if it has already been determined.
returnData
object
_TYPE
string
required
Possible values: [cardData
, phoneData
, ibanData
, walletData
, achData
]
Type of credit card
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$
Possible values: Value must match regular expression ^[0-9]{4}$
Possible values: Value must match regular expression ^[0-9]{6-8}$
Possible values: Value must match regular expression ^[0-9]{6}$
Possible values: Value must match regular expression ^[0-9]{4}$
Triggers the 3D Secure authentication for this transaction.
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
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).
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
]
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Reference ID of the wallet.
Owner of the wallet.
Type of wallet.
First name of wallet owner.
Last name of wallet owner.
Country code of wallet owner.
UUID of the transaction that initially registered this wallet.
Possible values: [person
, company
]
Possible values: [checking
, savings
]
Possible values: <= 17 characters
Possible values: >= 9 characters
and <= 9 characters
scheduleData
object
ID of schedule which was started with the transaction.
Status of the schedule.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
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}$
2001-02-03T04:05:06+02:00
customerProfileData
object
The unique customer profile identifier generated by the platform.
The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.
The created payment instrument for the customer profile, use with transactionToken
when creating new transactions.
Whether this payment instrument was marked as preferred for the customer.
riskCheckData
object
Possible values: [APPROVED
, DECLINED
, REVIEW
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
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
.
dccData
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
payByLinkData
object
true
if this transaction was a Pay-by-Link transaction.
true
if this Pay-by-Link was sent to the transaction customer via email.
Endpoint to call to cancel a Pay-by-Link transaction.
For details, see Pay-by-Link API reference.
Indicates at what date time the Pay-by-Link transaction expires.
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
Possible values: [ERROR
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
{
"success": true
}
{
"success": false,
"errorMessage": "The transaction ID '20190823062178' already exists!",
"errorCode": 3004
}
Transaction error response
- application/json
- Schema
- Example (from schema)
- General error, e.g. validation
Schema
- true
- false
-
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
andadapterCode
.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 insuccessUrl
,cancelUrl
orerrorUrl
). In parallel thesends 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.
- cardData
- phoneData
- ibanData
- walletData
- achData
01
- Additional information needed.02
- Try again later.03
- Do not try again.Array [
]
Array [
]
success
string
required
Returns true
or false
depending on whether the request was successful.
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
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
]
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
Possible values: <= 255 characters
QR Code with redirectUrl base64 encoded.
HTML content the customer must be shown, only set if "returnType": "HTML"
.
Payment method used - if it has already been determined.
returnData
object
_TYPE
string
required
Possible values: [cardData
, phoneData
, ibanData
, walletData
, achData
]
Type of credit card
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$
Possible values: Value must match regular expression ^[0-9]{4}$
Possible values: Value must match regular expression ^[0-9]{6-8}$
Possible values: Value must match regular expression ^[0-9]{6}$
Possible values: Value must match regular expression ^[0-9]{4}$
Triggers the 3D Secure authentication for this transaction.
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
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).
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
]
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Reference ID of the wallet.
Owner of the wallet.
Type of wallet.
First name of wallet owner.
Last name of wallet owner.
Country code of wallet owner.
UUID of the transaction that initially registered this wallet.
Possible values: [person
, company
]
Possible values: [checking
, savings
]
Possible values: <= 17 characters
Possible values: >= 9 characters
and <= 9 characters
scheduleData
object
ID of schedule which was started with the transaction.
Status of the schedule.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
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}$
2001-02-03T04:05:06+02:00
customerProfileData
object
The unique customer profile identifier generated by the platform.
The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.
The created payment instrument for the customer profile, use with transactionToken
when creating new transactions.
Whether this payment instrument was marked as preferred for the customer.
riskCheckData
object
Possible values: [APPROVED
, DECLINED
, REVIEW
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
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
.
dccData
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
payByLinkData
object
true
if this transaction was a Pay-by-Link transaction.
true
if this Pay-by-Link was sent to the transaction customer via email.
Endpoint to call to cancel a Pay-by-Link transaction.
For details, see Pay-by-Link API reference.
Indicates at what date time the Pay-by-Link transaction expires.
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
Possible values: [ERROR
]
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
{
"success": true
}
{
"success": false,
"errorMessage": "amount: 'amount' is required",
"errorCode": 1002
}
Callbacks
- POST statusChange
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.
- application/json
Bodyrequired
required
The current state of the transaction.
Array [
]
- cardData
- phoneData
- ibanData
- walletData
- achData
01
- Additional information needed.02
- Try again later.03
- Do not try again.- PaymentIbanData
- PaymentWalletData
Array [
]
Array [
]
UUID of the transaction.
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
c5f2accd-2c37-4b2c-bb03-22d168c25a74
Purchase ID of the transaction.
Possible values: <= 50 characters
Possible values: [DEBIT
, CAPTURE
, DEREGISTER
, PREAUTHORIZE
, REFUND
, REGISTER
, VOID
, CHARGEBACK
, CHARGEBACK-REVERSAL
, PAYOUT
, INCREMENTAL-AUTHORIZATION
]
Only present if transaction has a subType
.
Possible values: [cb-resolved
, cb-reversal-resolved
]
Payment method.
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
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}))$
9.99
dccData
object
Possible values: <= 128 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Possible values: <= 32 characters
Possible values: non-empty
and <= 50 characters
errors
object[]
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
chargebackData
object
When transactionType
is CHARGEBACK
this field contains information on the chargeback.
Possible values: non-empty
and <= 50 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}$
2001-02-03T04:05:06+02:00
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.
Possible values: non-empty
and <= 50 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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}$
2001-02-03T04:05:06+02:00
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
.
returnData
object
_TYPE
string
required
Possible values: [cardData
, phoneData
, ibanData
, walletData
, achData
]
Type of credit card
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: Value must match regular expression ^((0[1-9])|(1[0-2]))$
Possible values: Value must match regular expression ^[0-9]{4}$
Possible values: Value must match regular expression ^[0-9]{6-8}$
Possible values: Value must match regular expression ^[0-9]{6}$
Possible values: Value must match regular expression ^[0-9]{4}$
Triggers the 3D Secure authentication for this transaction.
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
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).
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
]
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
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]))$
2001-02-03
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Reference ID of the wallet.
Owner of the wallet.
Type of wallet.
First name of wallet owner.
Last name of wallet owner.
Country code of wallet owner.
UUID of the transaction that initially registered this wallet.
Possible values: [person
, company
]
Possible values: [checking
, savings
]
Possible values: <= 17 characters
Possible values: >= 9 characters
and <= 9 characters
payByLinkData
object
true
if this transaction was a Pay-by-Link transaction.
true
if this Pay-by-Link was sent to the transaction customer via email.
Endpoint to call to cancel a Pay-by-Link transaction.
For details, see Pay-by-Link API reference.
Indicates at what date time the Pay-by-Link transaction expires.
customer
object
Possible values: <= 36 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
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]))$
2001-02-03
Possible values: [M
, F
]
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 16 characters
Possible values: <= 30 characters
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: <= 20 characters
+XX 1234567890
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 50 characters
Possible values: <= 16 characters
Possible values: <= 30 characters
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[A-Z]{2}$
AT
Possible values: <= 20 characters
+XX 1234567890
Possible values: <= 50 characters
Possible values: <= 255 characters
Possible values: <= 50 characters
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
.
paymentData
object
oneOf
ibanData
object
Possible values: <= 34 characters
Possible values: <= 11 characters
Possible values: <= 50 characters
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]))$
2001-02-03
walletData
object
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
customerProfileData
object
The unique customer profile identifier generated by the platform.
The customer profile identifier provided by you when creating the customer profile. Unique within one customer profile container.
The created payment instrument for the customer profile, use with transactionToken
when creating new transactions.
Whether this payment instrument was marked as preferred for the customer.
splits
object[]
Possible values: <= 10
Possible values: <= 11 characters
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Possible values: <= 11 characters
Possible values: <= 128 characters
commissionFee
object
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}))$
9.99
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
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
.
Error code.
For a complete list of error codes and their meanings, please see the appendix on Error codes.
Adapter specific error message, passed verbatim from the upstream Adapter.
Adapter specific error code, passed verbatim from the upstream Adapter.
Possible values: [OK
, PENDING
, ERROR
]
scheduleData
object[]
ID of schedule which was started with the transaction.
Status of the schedule.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
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}$
2001-02-03T04:05:06+02:00
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
]
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}))$
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}$
EUR
Callbacks Responses
- 200
- 500
Reply with status 200 and body OK
if you have received the callback successfully.
- text/plain
- Schema
- Success
Schema
string
Possible values: [OK
]
OK
Callback processing failed and retries will be performed.
See the Response handling — Acknowledging callback receipt reference for further information.