Transaction API (v1)

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/v1/order-management/{orderRef}/instruction/{instructionRef}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "self": {
      • "href": "/v1/order-management/order1/instruction/instruction1"
      }
    },
  • "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": 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.


 
 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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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.


 
 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 
410
Gone.


default
All other managed 4xx and 5xx errors


post/v1/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.


 
 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 
410
Gone.


default
All other managed 4xx and 5xx errors


post/v1/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 2024 Duck Creek Technologies. All Rights Reserved.