Incremental authorization
POSThttps://gateway.ixopay.com/api/v3/transaction/:apiKey/incrementalAuthorization
An incremental authorization increases or prolongs the authorized amount on the customer's payment instrument.
Currently, the incremental authorization is only supported by a few adapters.
A follow-up capture transaction may capture the full amount of the initial transaction and all its subsequent incremental authorizations.
The follow-up capture transaction must refer to the initial preauthorize!
Request
Path Parameters
Possible values: <= 50 characters
API Key of Connector
- application/json
Bodyrequired
Data which is required to process incremental auth transactions.
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
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.
Possible values: non-empty
and <= 50 characters
extraData object
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
ISO 4217 three-letter currency code.
Possible values: Value must match regular expression ^[A-Z]{3}$
EUR
Possible values: <= 4096 characters
Possible values: <= 4096 characters
Possible values: <= 4096 characters
Possible values: <= 4096 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[]
Possible values: [SINGLE
, INITIAL
, RECURRING
, FIRST-CARDONFILE
, CARDONFILE
, CARDONFILE-MERCHANT-INITIATED
, MOTO
]
Possible values: >= 2 characters
and <= 2 characters
l2l3Data object
Responses
- 200
- 400
- 422
Transaction response
- application/json
- Schema
- Example (auto)
- 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.
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
scheduleData object
customerProfileData object
riskCheckData object
errors object[]
extraData object
dccData object
payByLinkData 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.
Possible values: [ERROR
]
errors object[]
{
"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://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"
}
]
}
Transaction error response
- application/json
- Schema
- Example (auto)
- 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.
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
scheduleData object
customerProfileData object
riskCheckData object
errors object[]
extraData object
dccData object
payByLinkData 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.
Possible values: [ERROR
]
errors object[]
{
"success": true
}
{
"success": false,
"errorMessage": "The transaction ID '20190823062178' already exists!",
"errorCode": 3004
}
Transaction error response
- application/json
- Schema
- Example (auto)
- 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.
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
scheduleData object
customerProfileData object
riskCheckData object
errors object[]
extraData object
dccData object
payByLinkData 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.
Possible values: [ERROR
]
errors object[]
{
"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
The current state of the transaction.
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: non-empty
and <= 50 characters
errors object[]
chargebackData object
chargebackReversalData object
extraData object
returnData object
payByLinkData object
customer object
customerProfileData object
splits 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.
Possible values: [OK
, PENDING
, ERROR
]
scheduleData object[]
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
- Example (auto)
- Success
Schema
Possible values: [OK
]
"OK"
OK
Callback processing failed and retries will be performed.
See the Response handling — Acknowledging callback receipt reference for further information.
Authorization: http
name: basicAuthtype: httpscheme: basicdescription: To authenticate API requests, the API username and password must be sent as BASIC Authentication in the `Authorization` header, as defined in [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617). To achieve this, the username and password are first concatenated with a `:` (colon) separator, and the resulting string is then Base64 encoded. Here is an example of how this process works: 1. Suppose the API username is `anyApiUser` and the password is `myPassword`. 2. Concatenate the username and password with a `:` separator: `anyApiUser:myPassword`. 3. Base64 encode the concatenated string: `YW55QXBpVXNlcjpteVBhc3N3b3JkCg==`. 4. Finally, include the `Authorization` header in the API request with the Base64 encoded string, like so: `Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3Jk`. :::tip Many programming frameworks will automatically handle the BASIC Authentication process for you once you provide the username and password to the appropriate request object. :::
- curl
- python
- go
- nodejs
- php
- java
- CURL
curl -L 'https://gateway.ixopay.com/api/v3/transaction/:apiKey/incrementalAuthorization' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic PHVzZXJuYW1lPjo8cGFzc3dvcmQ+' \
-d '{
"merchantTransactionId": "c5f2accd-2c37-4b2c-bb03-22d168c25a74",
"referenceUuid": "string",
"additionalId1": "string",
"additionalId2": "string",
"extraData": {},
"merchantMetaData": "string",
"amount": "9.99",
"currency": "EUR",
"successUrl": "string",
"cancelUrl": "string",
"errorUrl": "string",
"callbackUrl": "string",
"description": "string",
"items": [
{
"identification": "string",
"name": "string",
"description": "string",
"quantity": 0,
"price": 0,
"currency": "EUR",
"l2l3Data": {
"type": "string",
"unit": "string",
"unitPrice": "9.99",
"discount": "9.99",
"shippingAmount": "9.99",
"taxAmount": "9.99",
"taxRate": "9.99",
"commodityCode": "string",
"taxDetails": [
{
"type": "string",
"amount": "9.99",
"rate": "9.99",
"code": "string",
"taxId": "string",
"applied": "string",
"exemptionCode": "string"
}
]
},
"extraData": {}
}
],
"transactionIndicator": "SINGLE",
"language": "string",
"l2l3Data": {
"taxAmount": "string",
"vatRegistrationNumber": "string",
"nationalTaxIncluded": "string",
"discountAmount": "9.99",
"commodityCode": "string",
"freightAmount": "9.99",
"freightTaxAmount": "9.99",
"dutyAmount": "9.99",
"taxDetails": [
{
"type": "string",
"amount": "9.99",
"rate": "9.99",
"code": "string",
"taxId": "string",
"applied": "string",
"exemptionCode": "string"
}
]
}
}'