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

apiKey stringrequired

Possible values: <= 50 characters

API Key of Connector

application/json

Body

required

Data which is required to process a capture

merchantTransactionId stringrequired

Possible values: non-empty and <= 50 characters

additionalId1 string

Possible values: non-empty and <= 50 characters

additionalId2 string

Possible values: non-empty and <= 50 characters

extraData object
Object containing key-value pairs (string-to-string), to be used by either the upstream Adapter, the Risk Engine etc.
Possible values: <= 64.
Property name: <= 64 characters.
Property value: <= 8192 characters.
property name* string
pspPassthroughData object
Object containing key-value pars (string-to-string) to be passed to the PSP.
Possible values: <= 64.
Property name: <= 64 characters.
Property value: <= 8192 characters.
property name* string
merchantMetaData string

Possible values: <= 255 characters

referenceUuid stringrequired

Possible values: non-empty and <= 50 characters

amount stringrequired

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

Decimal amount separated by ., maximum of 3 decimals.

currency stringrequired

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

ISO 4217 three-letter currency code.

description string

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.

Array [

identification string

Possible values: <= 128 characters

name string

Possible values: <= 256 characters

description string

Possible values: <= 2048 characters

quantity integer

Possible values: >= 1

price integer

Possible values: >= 1

currency string

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

ISO 4217 three-letter currency code.

l2l3Data object

type string

Possible values: <= 32 characters

unit string

Possible values: <= 16 characters

unitPrice string

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

Decimal amount separated by ., maximum of 3 decimals.

discount string

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

Decimal amount separated by ., maximum of 3 decimals.

shippingAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

taxAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

taxRate string

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

Decimal amount separated by ., maximum of 3 decimals.

commodityCode string

Possible values: <= 64 characters

taxDetails object[]

Possible values: <= 10

Array [

type string

Possible values: <= 255 characters

amount string

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

Decimal amount separated by ., maximum of 3 decimals.

rate string

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

Decimal amount separated by ., maximum of 3 decimals.

code string

Possible values: <= 255 characters

taxId string

Possible values: <= 255 characters

applied string

Possible values: <= 255 characters

exemptionCode string

Possible values: <= 255 characters

]

extraData object

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

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

property name* string

]

splits object[]

Possible values: <= 10

Array [

identification string

Possible values: <= 11 characters

amount string

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

Decimal amount separated by ., maximum of 3 decimals.

currency string

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

ISO 4217 three-letter currency code.

sellerMerchantGuid string

Possible values: <= 11 characters

sellerMerchantExternalId string

Possible values: <= 128 characters

commissionFee object

amount string

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

Decimal amount separated by ., maximum of 3 decimals.

currency string

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

ISO 4217 three-letter currency code.

]

isFinalCapture boolean
l2l3Data object

Level 2 & level 3 data.

taxAmount string

Possible values: <= 15 characters

vatRegistrationNumber string

Possible values: <= 255 characters

nationalTaxIncluded string

Possible values: <= 5 characters

discountAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

commodityCode string

Possible values: <= 255 characters

freightAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

freightTaxAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

dutyAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

taxDetails object[]

Possible values: <= 10

Array [

type string

Possible values: <= 255 characters

amount string

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

Decimal amount separated by ., maximum of 3 decimals.

rate string

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

Decimal amount separated by ., maximum of 3 decimals.

code string

Possible values: <= 255 characters

taxId string

Possible values: <= 255 characters

applied string

Possible values: <= 255 characters

exemptionCode string

Possible values: <= 255 characters

]

Responses

200

Transaction response

application/json

Schema

Schema

success stringrequired

Possible values: [true, false]

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

true

success booleanrequired

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

uuid string

UUID of the transaction.

purchaseId string

Purchase ID of the transaction.

returnType string

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

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

• FINISHED

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

• ERROR

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

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

  Note: Merchant Advice Code

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

  This code is piped through as received by the gateway.

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

• REDIRECT

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

  Note:

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

• PENDING

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

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

redirectType string

Possible values: [iframe, fullpage]

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

redirectUrl uri

Possible values: <= 255 characters

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

redirectQRCode string

QR Code with redirectUrl base64 encoded.

htmlContent string

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

paymentDescriptor string

paymentMethod string

Payment method used - if it has already been determined.

returnData object

_TYPE stringrequired

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

cardData

type string

Type of credit card

firstName string

lastName string

country string

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

ISO 3166-1 alpha-2 country code.

cardHolder string

expiryMonth string

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

expiryYear string

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

binDigits string

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

firstSixDigits string

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

lastFourDigits string

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

fingerprint string

binBrand string

binBank string

binType string

binLevel string

binCountry string

threeDSecure ThreeDSecureType

Possible values: [OFF, OPTIONAL, MANDATORY]

Triggers the 3D Secure authentication for this transaction.

eci string

merchantAdviceCode string

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

parsedMerchantAdviceCode string

Possible values: [01, 02, 03]

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

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

schemeTransactionIdentifier string

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

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

phoneData

phoneNumber string

country string

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

ISO 3166-1 alpha-2 country code.

operator string

ibanData

accountOwner string

iban string

bic string

mandateId string

mandateDate date (string)

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

RFC 3339 Internet Date/Time Format full-date.

bankName string

bankBranchName string

country string

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

ISO 3166-1 alpha-2 country code.

walletData

walletReferenceId string

Reference ID of the wallet.

walletOwner string

Owner of the wallet.

walletType string

Type of wallet.

walletOwnerFirstName string

First name of wallet owner.

walletOwnerLastName string

Last name of wallet owner.

walletOwnerCountryCode string

Country code of wallet owner.

walletRegistrationId string

UUID of the transaction that initially registered this wallet.

achData

accountHolder string

accountHolderType string

Possible values: [person, company]

accountType string

Possible values: [checking, savings]

accountNumber string

Possible values: <= 17 characters

routingNumber int32

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

scheduleData object

scheduleId string

ID of schedule which was started with the transaction.

scheduleStatus ScheduleStatus

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

Status of the schedule.

scheduledAt date-time

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

RFC 3339 Internet Date/Time Format date-time

merchantMetaData string

property name* any

customerProfileData object

profileGuid string

The unique customer profile identifier generated by the platform.

customerIdentification string

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

paymentToken string

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

markAsPreferred boolean

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

property name* any

riskCheckData object

riskCheckResult string

Possible values: [APPROVED, DECLINED, REVIEW]

riskScore number

threeDSecureRequired boolean

property name* any

errors object[]

Array [

errorMessage string

Error message.

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

errorCode int32

adapterMessage string

adapterCode string

]

adapterMessage string

adapterCode string

extraData object

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

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

property name* string

dccData object

uuid string

originalAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

originalCurrency string

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

ISO 4217 three-letter currency code.

convertedAmount string

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

Decimal amount separated by ., maximum of 3 decimals.

convertedCurrency string

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

ISO 4217 three-letter currency code.

conversionRate number

disclaimer string

property name* any

payByLinkData object

payByLink booleandeprecated

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

sendViaEmail boolean

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

cancelUrl uri

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

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

expiresAt date-time

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

property name* any

false

errorMessage string

Error message.

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

errorCode int32

adapterMessage string

adapterCode string

success booleanrequired

returnType string

Possible values: [ERROR]

errors object[]

Array [

errorMessage string

Error message.

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

errorCode int32

adapterMessage string

adapterCode string

]

property name* any

Example (from schema)

{
  "success": true
}

Finished

"returnType": "FINISHED" indicates a successfully completed capture transaction.

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

Redirect

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"
}

Processing error

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"
    }
  ]
}

General error, e.g. duplicate

{
  "success": false,
  "errorMessage": "The transaction ID '20190823062178' already exists!",
  "errorCode": 3004
}

General error, e.g. validation

{
  "success": false,
  "errorMessage": "root: 'amount' is required",
  "errorCode": 1002
}

Loading...