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
Possible values: non-empty
and <= 50 characters
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
.
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.
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
Transaction response
- application/json
- Schema
- Example (from schema)
- Finished
- Redirect
- Processing error
- General error, e.g. duplicate
- 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 [
]
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
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: 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
.
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
.
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
.
{
"success": true
}
"returnType": "FINISHED"
indicates a successfully completed capture transaction.
{
"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://gateway.ixopay.com/redirect-url",
"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"
}
]
}
{
"success": false,
"errorMessage": "The transaction ID '20190823062178' already exists!",
"errorCode": 3004
}
{
"success": false,
"errorMessage": "root: 'amount' is required",
"errorCode": 1002
}