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.

Example: 00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid> = 36 characters

The Tenant Id.

Example: 00000000-0000-0000-0000-000000000000
x-correlation-id
string

Correlation Id for the request.

Responses
200

OK - Returns the Instruction response.

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
{
  • "_links": {
    • "self": {
      • "href": "/v1/order-management/order1/instruction/instruction1"
      },
    • "financialInstruments": [
      • {
        • "href": "/v1/customer-vault/customer1/financial-instrument/6105540a-1f16-46e0-b16d-0d3cdfe79411",
        • "name": "6105540a-1f16-46e0-b16d-0d3cdfe79411"
        }
      ],
    • "transactions": [
      • {
        • "href": "/v1/customer-vault/customer1/financial-instrument/6105540a-1f16-46e0-b16d-0d3cdfe79411/transaction/a16699d2-454d-6bec-785d-0823cb79e86a",
        • "name": "a16699d2-454d-6bec-785d-0823cb79e86a"
        }
      ]
    },
  • "created": 1662105575226,
  • "lastUpdated": 1662105912747,
  • "direction": "DEBIT",
  • "status": "COMPLETED",
  • "customerRef": "customer1",
  • "amount": 10,
  • "currency": "EUR",
  • "country": "AT",
  • "settledByDate": "2023-12-15",
  • "forecastedSettlementDate": null,
  • "actualSettlementDate": null,
  • "executionTimestamp": null,
  • "financialInstrument": {
    • "financialInstrumentId": "6105540a-1f16-46e0-b16d-0d3cdfe79411",
    • "source": "NONE",
    • "canUpdate": true
    },
  • "scheme": {
    • "schemeId": "EEAB9BBF6F8FA16D711798D14B65E066",
    • "source": "MANUALLY_SET",
    • "canUpdate": true
    },
  • "metadata": {
    • "key1": "payment/1",
    • "key2": "payment/2"
    },
  • "transaction": {
    • "transactionId": "a16699d2-454d-6bec-785d-0823cb79e86a",
    • "financialInstrumentId": "6105540a-1f16-46e0-b16d-0d3cdfe79411",
    • "createdTimestamp": 1662543264053,
    • "lastUpdatedTimestamp": 1662543264006,
    • "amount": 12.34,
    • "netAmount": 10,
    • "status": "PROCESSING",
    • "additionalInformation": "Test",
    • "app": {
      • "appId": "STRIPE",
      • "appTransactionId": "pi_3LfKdwHm8hoYQJyN0lk60ru7",
      • "appBatchId": null,
      • "supportDetails": {
        • "customerId": "cus_MH3lMCEjrZ4O0Q"
        }
      },
    • "refunds": [
      • {
        • "refundId": "07924e91-3470-442d-8c8a-81282b41b74e",
        • "createdTimestamp": 1662543387150,
        • "lastUpdatedTimestamp": 1662543388793,
        • "status": "COMPLETED",
        • "amount": 2.34
        }
      ],
    • "chargebacks": [
      • {
        • "id": "cf223726-7ac8-4294-bb4b-75748b619268",
        • "network": "STRIPE",
        • "status": "PENDING",
        • "amount": 0,
        • "claimed": "0001-01-01",
        • "created": "0001-01-01T00:00:00Z"
        }
      ]
    },
  • "failed": {
    • "failedTimestamp": 0,
    • "errorCode": null,
    • "reason": null
    },
  • "cancelled": {
    • "cancelledTimestamp": 0,
    • "identity": null,
    • "reason": 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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
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 Reward
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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
x-correlation-id
string
Correlation Id for the request.


 
Responses 
201
Created - 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}/authorize-reward
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"
        }
      }
    ]
}
Claim Reward
Role Requirements


tenant-transaction-write or tenant-admin


Description


Claims a Reward by the customerRef and instructionRef.


The response location header value will contain the URL to call while the reward is claimed by the reward provider.


The time taken to claim a reward can vary so we give you a TransactionId to check against while we process the claim in the background.


See Get a Reward by Transaction Id for more information.


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.


 
 Example:  00000000-0000-0000-0000-000000000000
x-tenant-id
required
string <uuid>   = 36 characters 
The Tenant Id.


 
 Example:  00000000-0000-0000-0000-000000000000
x-correlation-id
string
Correlation Id for the request.


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


 
Responses 
202
Accepted - Returns a link in the location header response.


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


    

  • Order not found.
    • 

  • Instruction not found.
    • 

  • Instruction cancelled.
    • 

  • Instruction processing.
    • 

  • Reward id not recognised.
    • 

  • Invalid reward id.
    • 

  • Transaction already exists.
    • 



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
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"
        }
      }
    ]
}
Copyright © Imburse AG 2018-2022. All right reserved.