Transaction API (v2)

Download OpenAPI specification:Download

Imburse Support: support@imbursepayments.com License: Imburse AG. Terms of Service

Order Management

Get Instruction

Role Requirements

tenant-transaction-read or tenant-admin

Description

Gets an Order Instruction by the orderRef and instructionRef.

Securitybearer
Request
path Parameters
orderRef
required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$

The Order reference.

instructionRef
required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$

The Instruction reference.

header Parameters
x-account-id
required
string <uuid> = 36 characters

The Account Id (lowercase and hyphenated).

Example: 1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id (lowercase and hyphenated).

Example: ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string

Correlation Id for the request.

Responses
200

OK - Returns the Instruction response. - Instruction response for Card Payment using Stripe with Refund - Instruction response for Bacs Direct Debit using Bottomline with Chargeback

400

Bad Request - Validation error response, containing errors such as:

  • Order not found.
  • Instruction not found.
default

All other managed 4xx and 5xx errors

get/v2/order-management/{orderRef}/instruction/{instructionRef}
Request samples 
Response samples 
application/json
Card payment with refund


{
  • "_links": {
    • "self": {
      • "href": "/v1/order-management/ZNMiwTzYnl/instruction/QA-PWA4NqEu_RR8"
      },
    • "financialInstruments": [
      • {
        • "href": "/v1/customer-vault/UYxKotbKg/financial-instrument/fdadd310-cbeb-0d30-da0f-f33c36e35b96",
        • "name": "fdadd310-cbeb-0d30-da0f-f33c36e35b96"
        }
      ],
    • "transactions": [
      • {
        • "href": "/v1/customer-vault/UYxKotbKg/financial-instrument/fdadd310-cbeb-0d30-da0f-f33c36e35b96/transaction/47325e85-0118-4f47-a52e-3b933935c6c3",
        • "name": "47325e85-0118-4f47-a52e-3b933935c6c3"
        }
      ]
    },
  • "created": 1740038685016,
  • "lastUpdated": 1740038722063,
  • "direction": "DEBIT",
  • "status": "COMPLETED",
  • "customerRef": "UYxKotbKg",
  • "amount": 50.01,
  • "currency": "CHF",
  • "country": "CH",
  • "settledByDate": "2025-02-20",
  • "forecastedSettlementDate": "2025-02-20",
  • "actualSettlementDate": "2025-02-20",
  • "executionTimestamp": null,
  • "financialInstrument": {
    • "financialInstrumentId": "fdadd310-cbeb-0d30-da0f-f33c36e35b96",
    • "source": "TRANSACTION",
    • "canUpdate": false,
    • "sourceFlow": "OnSession"
    },
  • "scheme": {
    • "schemeId": "093199805B8A74CE118F2544B0AA391A",
    • "source": "TRANSACTION",
    • "canUpdate": false
    },
  • "metadata": {
    • "paymentDescriptorField1": "ABC"
    },
  • "transaction": {
    • "transactionId": "47325e85-0118-4f47-a52e-3b933935c6c3",
    • "financialInstrumentId": "fdadd310-cbeb-0d30-da0f-f33c36e35b96",
    • "createdTimestamp": 1740038717184,
    • "lastUpdatedTimestamp": 1740038717184,
    • "amount": 50.01,
    • "netAmount": 26.01,
    • "status": "SUCCESS",
    • "additionalInformation": "",
    • "app": {
      • "appId": "STRIPE",
      • "appTransactionId": "pi_3QuUkoHm8hoYQJyN1I8rzoXy",
      • "appBatchId": null,
      • "supportDetails": {
        • "paymentDescriptorField1": "ABC",
        • "customerId": "cus_Ro6yDv5DZsnHW7"
        }
      },
    • "refunds": [
      • {
        • "refundId": "a42ad429-345e-404d-af14-4d9892d3a752",
        • "createdTimestamp": 1740038724213,
        • "lastUpdatedTimestamp": 1740038724213,
        • "status": "Completed",
        • "amount": 24,
        • "refundReason": "On session refund success",
        • "failureReasonCode": null,
        • "failureDescription": null
        }
      ],
    • "chargebacks": [ ],
    • "processingDetails": {
      • "channel": "eCom",
      • "authenticationFlow": "3DS Challenge"
      }
    },
  • "failed": null,
  • "cancelled": null
}
Update Instruction
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates a new Instruction by orderRef and instructionRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
instructionRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Instruction reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
financialInstrumentId
string <uuid>  (FinancialInstrumentId) 
The system generated Financial Instrument identifier.


 
amount
number <decimal>  (Amount) 
Currency amount. The number of decimal digits is validated against the currency code of the payment.


 
currency
string (Currency) ^[A-Z]{3}$
ISO 4217 code (3 uppercase letters) for the chosen currency.


 
country
string (Country) ^[A-Z]{2}$
The ISO 3166-1 alpha 2 country code (2 letter code) for the chosen country of the future transaction.


 
settledByDate
string <date> 
The date in which a payment is to be settled by, or, if automated, will be taken on.


 
schemeId
string (SchemeId) 
The Payout or Collect scheme Id from the tenant portal.


 
object or null (Metadata) 
A collection of key-value pairs defined by the client. 
This object is subject to the following limits:


    

  • Maximum of 15 keys.
    • 

  • Keys have a maximum length of 64 characters.
    • 

  • Values have a maximum length of 256 characters.
    • 



 
Responses 
204
No Content.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found
    • 

  • Instruction not found
    • 

  • Instruction cancelled
    • 

  • Instruction processing
    • 



default
All other managed 4xx and 5xx errors


put/v2/order-management/{orderRef}/instruction/{instructionRef}
Request samples 
application/json
{
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "amount": 20,
  • "currency": "GBP",
  • "country": "GB",
  • "settledByDate": "2019-08-24",
  • "schemeId": "ef1c9dbe-017b-4011-8bd1-352897f8dfef",
  • "metadata": {
    • "customKey1": "custom string 1"
    }
}
Response samples 
application/json
Order {orderRef} does not exist.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_NOT_FOUND",
      • "message": "Order [orderRef] does not exist.",
      • "messageTemplate": "Order {orderRef} does not exist.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Create Instruction
Role Requirements


tenant-transaction-write or tenant-admin


Description


Create a new Order Instruction for the specified orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
instructionRef
required
string (InstructionRef)   <= 50 characters ^[a-zA-Z0-9-_\.]+$
The instruction reference. [Required].


 
customerRef
required
string (CustomerRef)   <= 50 characters ^[a-zA-Z0-9-_\.]+$
The client defined unique Customer Reference.


 
direction
required
string (Direction) 
The direction of the instruction: Debit or Credit.
The Scheme used must match this direction.


 Enum: "DEBIT" "CREDIT"  
financialInstrumentId
string <uuid>  (FinancialInstrumentId) 
The system generated Financial Instrument identifier.


 
amount
required
number <decimal>  (Amount) 
Currency amount. The number of decimal digits is validated against the currency code of the payment.


 
currency
required
string (Currency) ^[A-Z]{3}$
ISO 4217 code (3 uppercase letters) for the chosen currency.


 
country
required
string (Country) ^[A-Z]{2}$
The ISO 3166-1 alpha 2 country code (2 letter code) for the chosen country of the future transaction.


 
settledByDate
required
string <date> 
The date in which a payment is to be settled by, or, if automated, will be taken on.


 
schemeId
string (SchemeId) 
The Payout or Collect scheme Id from the tenant portal.


 
object or null (Metadata) 
A collection of key-value pairs defined by the client. 
This object is subject to the following limits:


    

  • Maximum of 15 keys.
    • 

  • Keys have a maximum length of 64 characters.
    • 

  • Values have a maximum length of 256 characters.
    • 



 
Responses 
204
No Content.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found.
    • 

  • InstructionRef is required.
    • 

  • Instruction already exists.
    • 

  • CustomerRef is required.
    • 

  • Direction is required.
    • 

  • Amount is required.
    • 

  • Amount out of range. It must be greater than zero.
    • 

  • Amount is invalid.
    • 

  • Currency is required.
    • 

  • Currency length out of range. It must be in ISO 4217 currency code.
    • 

  • Country is required.
    • 

  • Country length out of range. It must be an ISO 3166 Alpha-2 code.
    • 

  • SettledByDate is required.
    • 

  • SettledByDate is invalid. It must be in the format YYYY-MM-DD.
    • 

  • SchemeId not recognised.
    • 



default
All other managed 4xx and 5xx errors


post/v2/order-management/{orderRef}/instruction
Request samples 
application/json
{
  • "instructionRef": "instruction1",
  • "customerRef": "customer1",
  • "direction": "DEBIT",
  • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
  • "amount": 20,
  • "currency": "GBP",
  • "country": "GB",
  • "settledByDate": "2019-08-24",
  • "schemeId": "ef1c9dbe-017b-4011-8bd1-352897f8dfef",
  • "metadata": {
    • "customKey1": "custom string 1"
    }
}
Response samples 
application/json
Order {orderRef} does not exist.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_NOT_FOUND",
      • "message": "Order [orderRef] does not exist.",
      • "messageTemplate": "Order {orderRef} does not exist.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Cancel Instruction
Role Requirements


tenant-transaction-write or tenant-admin


Description


Cancels an Instruction.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
instructionRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Instruction reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
reason
string  <= 256 characters 
Optional cancellation reason.


 
Responses 
204
No Content.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found.
    • 

  • Instruction not found.
    • 

  • Instruction cancelled.
    • 

  • Instruction processing.
    • 



default
All other managed 4xx and 5xx errors


post/v2/order-management/{orderRef}/instruction/{instructionRef}/cancel
Request samples 
application/json
{
  • "reason": "Subscription cancelled."
}
Response samples 
application/json
Order {orderRef} does not exist.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_NOT_FOUND",
      • "message": "Order [orderRef] does not exist.",
      • "messageTemplate": "Order {orderRef} does not exist.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Get Order
Role Requirements


tenant-transaction-read or tenant-admin


Description


Gets an Order by the orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Responses 
200
OK - Returns the Order response.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found.
    • 



default
All other managed 4xx and 5xx errors


get/v2/order-management/{orderRef}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "self": {
      • "href": "/v1/order-management/order1"
      },
    • "instructions": [
      • {
        • "href": "/v1/order-management/order1/instruction/instruction1",
        • "name": "instruction1"
        }
      ]
    },
  • "created": 1691752640673,
  • "instructionRefs": [
    • "instruction1"
    ],
  • "metadata": {
    • "customKey1": "custom string 1"
    }
}
Create Order
Role Requirements


tenant-transaction-write or tenant-admin


Description


Create a new Order.


If you create the Order without any instructions then the response will be 201 - Created.
If you create the Order with instructions then the response will be 202 - Accepted.


Securitybearer 
Request 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
orderRef
required
string (OrderRef)   <= 50 characters ^[a-zA-Z0-9-_\.]+$
The order reference. [Required].


 
Array of objects (CreateInstructionRequest) 
A optional list of the instructions to create against the order.


 
object or null (Metadata) 
A collection of key-value pairs defined by the client. 
This object is subject to the following limits:


    

  • Maximum of 15 keys.
    • 

  • Keys have a maximum length of 64 characters.
    • 

  • Values have a maximum length of 256 characters.
    • 



 
Responses 
201
Created.


202
Accepted.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order already exists.
    • 

  • OrderRef is required.
    • 

  • InstructionRef is required.
    • 

  • CustomerRef is required.
    • 

  • Direction is required.
    • 

  • Amount is required.
    • 

  • Amount out of range. It must be greater than zero.
    • 

  • Amount is invalid.
    • 

  • Currency is required.
    • 

  • Currency length out of range. It must be in ISO 4217 currency code.
    • 

  • Country is required.
    • 

  • Country length out of range. It must be an ISO 3166 Alpha-2 code.
    • 

  • SettledByDate is required.
    • 

  • SettledByDate is invalid. It must be in the format YYYY-MM-DD.
    • 

  • SchemeId not recognised.
    • 



default
All other managed 4xx and 5xx errors


post/v2/order-management
Request samples 
application/json
{
  • "orderRef": "order1",
  • "instructions": [
    • {
      • "instructionRef": "instruction1",
      • "customerRef": "customer1",
      • "direction": "DEBIT",
      • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
      • "amount": 20,
      • "currency": "GBP",
      • "country": "GB",
      • "settledByDate": "2019-08-24",
      • "schemeId": "ef1c9dbe-017b-4011-8bd1-352897f8dfef",
      • "metadata": {
        • "customKey1": "custom string 1"
        }
      },
    • {
      • "instructionRef": "instruction2",
      • "customerRef": "customer1",
      • "direction": "DEBIT",
      • "financialInstrumentId": "35596f91-fea9-4297-b70b-01fdad24e25a",
      • "amount": 5,
      • "currency": "GBP",
      • "country": "GB",
      • "settledByDate": "2019-08-24",
      • "schemeId": "ef1c9dbe-017b-4011-8bd1-352897f8dfef",
      • "metadata": {
        • "customKey1": "custom string 1"
        }
      }
    ],
  • "metadata": {
    • "customKey1": "custom string 1"
    }
}
Response samples 
application/json
Order {orderRef} already exists.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_ALREADY_EXISTS",
      • "message": "Order [orderRef] already exists.",
      • "messageTemplate": "Order {orderRef} already exists.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Update Order Metadata
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates the Orders metadata by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
property name*
additional property
string  <= 256 characters  <= 15 properties 
 
Responses 
204
No Content.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found
    • 



default
All other managed 4xx and 5xx errors


put/v2/order-management/{orderRef}/metadata
Request samples 
application/json
{
  • "customKey1": "custom string 1",
  • "customKey2": "custom string 2",
  • "customKey3": "custom string 3"
}
Response samples 
application/json
Order {orderRef} does not exist.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_NOT_FOUND",
      • "message": "Order [orderRef] does not exist.",
      • "messageTemplate": "Order {orderRef} does not exist.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Delete Order Metadata
Role Requirements


tenant-transaction-write or tenant-admin


Description


Deletes the Orders metadata by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Responses 
204
No Content.


400
Bad Request - Validation error response, containing errors such as:


    

  • Order not found.
    • 



default
All other managed 4xx and 5xx errors


delete/v2/order-management/{orderRef}/metadata
Request samples 
Response samples 
application/json
Order {orderRef} does not exist.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "ORDER_NOT_FOUND",
      • "message": "Order [orderRef] does not exist.",
      • "messageTemplate": "Order {orderRef} does not exist.",
      • "metadata": {
        • "orderRef": "orderRef"
        }
      }
    ]
}
Authorize RewardDeprecated
Role Requirements


tenant-transaction-write or tenant-admin


Description


Authorizes a Reward by the customerRef and instructionRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
instructionRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Instruction reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Responses 
410
Gone.


default
All other managed 4xx and 5xx errors


post/v2/order-management/{orderRef}/instruction/{instructionRef}/authorize-reward
Request samples 
Response samples 
application/json
{
  • "status": 401,
  • "title": "Unauthorized",
  • "detail": "Invalid token",
  • "type": "https://httpproblems.com/http-status/401",
  • "instance": "/v1/customer-vault/customer1/international-bank-account/",
  • "trace": {
    • "timestamp": "2023-01-31T23:56:21Z",
    • "requestId": "4487062e-52db-4d89-b46b-7035d681cb40"
    }
}
Claim RewardDeprecated
Role Requirements


tenant-transaction-write or tenant-admin


Description


Claims a Reward by the customerRef and instructionRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Order reference.


 
instructionRef
required
string  <= 50 characters ^[a-zA-Z0-9-_\.]+$
The Instruction reference.


 
header Parameters
x-account-id
required
string <uuid>   = 36 characters 
The Account Id (lowercase and hyphenated).


 
 Example:  1aa81e1e-b072-4e64-b1ec-fdcc54f2d08c
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id (lowercase and hyphenated).


 
 Example:  ef848af6-4d8f-4b62-88c4-4856dd2aec02
x-correlation-id
string
Correlation Id for the request.


 
Request Body schema: application/json
rewardId
required
string <uuid> 
The Reward Id.


 
Responses 
410
Gone.


default
All other managed 4xx and 5xx errors


post/v2/order-management/{orderRef}/instruction/{instructionRef}/claim-reward
Request samples 
application/json
{
  • "rewardId": "3a15d6a9-82bb-4ffe-83c4-4435038d5367"
}
Response samples 
application/json
{
  • "status": 401,
  • "title": "Unauthorized",
  • "detail": "Invalid token",
  • "type": "https://httpproblems.com/http-status/401",
  • "instance": "/v1/customer-vault/customer1/international-bank-account/",
  • "trace": {
    • "timestamp": "2023-01-31T23:56:21Z",
    • "requestId": "4487062e-52db-4d89-b46b-7035d681cb40"
    }
}
Copyright 2025 Duck Creek Technologies. All Rights Reserved.