Capture
POST/transaction/:apiKey/capture
A capture transaction completes the payment which was previously authorized with the Preauthorize method.
Depending on the payment method you can even capture only a partial amount of the authorized amount.
Request
Path Parameters
Possible values: <= 50 characters
API Key of Connector
- application/json
Body
required
Data which is required to process a capture
Array [
Array [
]
]
Array [
]
Array [
]
Possible values: non-empty
and <= 50 characters
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
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.
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
.
Possible values: <= 255 characters
Possible values: non-empty
and <= 50 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
Possible values: <= 255 characters
Description of your transaction.
This might show up on a credit-card statement (depends on Adapter and PSP).
items
object[]
Possible values: <= 128
List of items sold.
Maximum JSON size: <= 32768 bytes
.
Possible values: <= 128 characters
Possible values: <= 256 characters
Possible values: <= 2048 characters
Possible values: >= 1
Possible values: >= 1
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
l2l3Data
object
Possible values: <= 32 characters
Possible values: <= 16 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: <= 64 characters
taxDetails
object[]
Possible values: <= 10
Possible values: <= 255 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
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
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
Possible values: <= 11 characters
Possible values: <= 128 characters
commissionFee
object
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
This flag indicates that this capture operation represents the final step, whether it concludes a series of captures or is a standalone capture. It is supported by specific adapters, contingent on the PSP's compatibility with this feature.
If an adapter lacks support for this functionality, no error will be raised, and the flag will be ignored. Importantly, activating this flag doesn't automatically capture any remaining amount.
l2l3Data
object
Level 2 & level 3 data.
Possible values: <= 15 characters
Possible values: <= 255 characters
Possible values: <= 5 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: <= 255 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
taxDetails
object[]
Possible values: <= 10
Possible values: <= 255 characters
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
Possible values: <= 255 characters
Responses
- 200
- 400
- 422
Transaction response
- application/json
- Schema
- Example (from schema)
- Finished
- 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
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [iframe
, fullpage
]
Depending on the redirectType
the URL from redirectUrl
should be displayed either in an <iframe>
,
in a full page (e.g. via a HTTP 302
redirect with a Location
header).
Possible values: <= 255 characters
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
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
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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}$
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Triggers the 3D Secure authentication for this transaction.
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
Merchant advice code for failed transactions if supported by the adapter.
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).
Possible values: [updated
, contact
, new-expiry
, closed
]
Status of the last account updater run.
Only non-null if the account updater is enabled and has run at least once.
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]))$
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 ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$
RFC 3339 Internet Date/Time Format full-date
.
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
Status of the schedule.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$
RFC 3339 Internet Date/Time Format date-time
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
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
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 capture transaction.
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"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
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [iframe
, fullpage
]
Depending on the redirectType
the URL from redirectUrl
should be displayed either in an <iframe>
,
in a full page (e.g. via a HTTP 302
redirect with a Location
header).
Possible values: <= 255 characters
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
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
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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}$
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Triggers the 3D Secure authentication for this transaction.
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
Merchant advice code for failed transactions if supported by the adapter.
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).
Possible values: [updated
, contact
, new-expiry
, closed
]
Status of the last account updater run.
Only non-null if the account updater is enabled and has run at least once.
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]))$
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 ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$
RFC 3339 Internet Date/Time Format full-date
.
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
Status of the schedule.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$
RFC 3339 Internet Date/Time Format date-time
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
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
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
Possible values: [true
, false
]
Returns true
or false
depending on whether the request was successful.
Returns true
or false
depending on whether the request was successful.
UUID of the transaction.
Purchase ID of the transaction.
Possible values: [FINISHED
, REDIRECT
, HTML
, PENDING
, ERROR
, PENDING_DCC
]
Depending on the returnType
a transaction is finished, intermediate, or failed.
Possible values: [iframe
, fullpage
]
Depending on the redirectType
the URL from redirectUrl
should be displayed either in an <iframe>
,
in a full page (e.g. via a HTTP 302
redirect with a Location
header).
Possible values: <= 255 characters
URL the customer must be redirected to, only set if "returnType": "REDIRECT"
.
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
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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}$
Possible values: [OFF
, OPTIONAL
, MANDATORY
]
Triggers the 3D Secure authentication for this transaction.
Pipes through the merchant advice code for failed transactions if supported by the adapter.
Possible values: [01
, 02
, 03
]
Merchant advice code for failed transactions if supported by the adapter.
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).
Possible values: [updated
, contact
, new-expiry
, closed
]
Status of the last account updater run.
Only non-null if the account updater is enabled and has run at least once.
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]))$
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 ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$
RFC 3339 Internet Date/Time Format full-date
.
Possible values: Value must match regular expression ^[A-Z]{2}$
ISO 3166-1 alpha-2 country code.
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.
Possible values: [ACTIVE
, PAUSED
, CANCELLED
, ERROR
, CREATE-PENDING
, NON-EXISTING
]
Status of the schedule.
Possible values: Value must match regular expression ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$
RFC 3339 Internet Date/Time Format date-time
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
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
Decimal amount separated by .
, maximum of 3 decimals.
Possible values: Value must match regular expression ^[A-Z]{3}$
ISO 4217 three-letter currency code.
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
}