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
Default: ""

The Order Ref.

instructionRef
required
string
Default: ""

The Instruction Ref.

header Parameters
x-account-id
required
string

The Account Id

x-tenant-id
required
string

The Tenant Id

x-correlation-id
string

Correlation Id for the request

Responses
200

OK - Returns the Instruction response.

401

Unauthorized

403

Forbidden

404

Instruction not found

get/v2/order-management/{orderRef}/instruction/{instructionRef}
Request samples 
Response samples 
application/json
{
  • "_links": { },
  • "created": 1662105575226,
  • "lastUpdated": 1662105912747,
  • "direction": "DEBIT",
  • "status": "COMPLETED",
  • "customerRef": "Some_Ref",
  • "amount": 10,
  • "currency": "EUR",
  • "country": "AT",
  • "settledByDate": "2023-12-15",
  • "forecastedSettlementDate": null,
  • "actualSettlementDate": null,
  • "executionTimestamp": null,
  • "financialInstrument": {
    • "financialInstrumentId": "41045ebe-7c67-4393-855e-f65d1dd0ae07",
    • "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": "a16349d2-454d-6bec-785d-0823cb79e86a",
    • "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
 Default:  ""
The Order Ref.


 
instructionRef
required
string
 Default:  ""
The Instruction Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
financialInstrumentId
string
The financial instrument Id.


 
amount
string
The amount this instruction should collect or payout.


 
currency
string
The currency this Instruction should be processed in.


 
country
string
The country this Instruction is related to.


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


 
schemeId
string
The scheme this instruction will use.


 
object
Metadata is useful for storing additional, structured information on an object.


 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/instruction/{instructionRef}
Request samples 
{
  • "financialInstrumentId": "string",
  • "amount": "string",
  • "currency": "string",
  • "country": "string",
  • "settledByDate": "string",
  • "schemeId": "string",
  • "metadata": {
    • "key1": "string",
    • "key2": "string",
    • "key3": "string"
    }
}
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
 Default:  ""
The Order Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
instructionRef
string
The instruction reference.


 
customerRef
string
The customer reference.


 
direction
string
The direction of the transaction. Either CREDIT or DEBIT.


 
financialInstrumentId
string
The financial instrument Id.


 
amount
string
The amount this instruction should collect or payout.


 
currency
string
The currency this Instruction should be processed in.


 
country
string
The country this Instruction is related to.


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


 
schemeId
string
The scheme this instruction will use.


 
object
Metadata is useful for storing additional, structured information on an object.


 
Responses 
204
No Content.


401
Unauthorized


post/v2/order-management/{orderRef}/instruction
Request samples 
{
  • "instructionRef": "string",
  • "customerRef": "string",
  • "direction": "string",
  • "financialInstrumentId": "string",
  • "amount": "string",
  • "currency": "string",
  • "country": "string",
  • "settledByDate": "string",
  • "schemeId": "string",
  • "metadata": {
    • "key1": "string",
    • "key2": "string",
    • "key3": "string"
    }
}
Cancel Instruction
Role Requirements


tenant-transaction-write or tenant-admin


Description


Cancels an Instruction.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
instructionRef
required
string
 Default:  ""
The Instruction Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
reason
string
Optional cancellation reason.


 
Responses 
204
No Content.


401
Unauthorized


post/v2/order-management/{orderRef}/instruction/{instructionRef}/cancel
Request samples 
{
  • "reason": "string"
}
Get Order
Role Requirements


tenant-transaction-read or tenant-admin


Description


Gets an Order by the orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
200
OK - Returns the Order response.


401
Unauthorized


get/v2/order-management/{orderRef}
Request samples 
Response samples 
application/json
{
  • "_links": { },
  • "created": 0,
  • "instructionRefs": [
    • "string",
    • "string",
    • "string"
    ],
  • "metadata": {
    • "key1": "string",
    • "key2": "string",
    • "key3": "string"
    },
  • "customerDefaults": {
    • "customerRef1": {
      • "financialInstrument": {
        • "financialInstrumentId": "41045ebe-7c67-4393-855e-f65d1dd0ae07",
        • "source": "string"
        },
      • "scheme": {
        • "schemeId": "string",
        • "source": "string"
        },
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • "customerRef2": {
      • "financialInstrument": {
        • "financialInstrumentId": "6c157f58-ac08-44e9-b116-5eae465f4244",
        • "source": "string"
        },
      • "scheme": {
        • "schemeId": "string",
        • "source": "string"
        },
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • "customerRef3": {
      • "financialInstrument": {
        • "financialInstrumentId": "9aba1ffd-7e14-4ab7-852e-8c7e0bd59fed",
        • "source": "string"
        },
      • "scheme": {
        • "schemeId": "string",
        • "source": "string"
        },
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      }
    }
}
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
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
orderRef
string
The order reference.


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


 
object
Metadata is useful for storing additional, structured information on an object.


 
object
Optionally allows you set default property values for your instructions. Note: The key names 'customerRef1', 'customerRef2' etc. need to be changed to match the value of the CustomerRef in your instruction for the defaults to take affect.


 
Responses 
201
Created.


202
Accepted.


401
Unauthorized


post/v2/order-management
Request samples 
{
  • "orderRef": "string",
  • "instructions": [
    • {
      • "instructionRef": "string",
      • "customerRef": "string",
      • "direction": "string",
      • "financialInstrumentId": "string",
      • "amount": "string",
      • "currency": "string",
      • "country": "string",
      • "settledByDate": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • {
      • "instructionRef": "string",
      • "customerRef": "string",
      • "direction": "string",
      • "financialInstrumentId": "string",
      • "amount": "string",
      • "currency": "string",
      • "country": "string",
      • "settledByDate": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • {
      • "instructionRef": "string",
      • "customerRef": "string",
      • "direction": "string",
      • "financialInstrumentId": "string",
      • "amount": "string",
      • "currency": "string",
      • "country": "string",
      • "settledByDate": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      }
    ],
  • "metadata": {
    • "key1": "string",
    • "key2": "string",
    • "key3": "string"
    },
  • "customerDefaults": {
    • "customerRef1": {
      • "financialInstrumentId": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • "customerRef2": {
      • "financialInstrumentId": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      },
    • "customerRef3": {
      • "financialInstrumentId": "string",
      • "schemeId": "string",
      • "metadata": {
        • "key1": "string",
        • "key2": "string",
        • "key3": "string"
        }
      }
    }
}
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
 Default:  ""
The Order Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
property name*
additional property
string
 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/metadata
Request samples 
{
  • "key1": "string",
  • "key2": "string",
  • "key3": "string"
}
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
 Default:  ""
The Order Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
204
No Content.


401
Unauthorized


delete/v2/order-management/{orderRef}/metadata
Request samples 
Update Customer Default by Customer Ref
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates the customerDefaults for the given customerRef on the Order specified by orderRef.


Note - This request allows you to update all the properties at once for the specified customerRef.


You can also call specific endpoints for updating Metadata (see Update Metadata for Customer Default), Scheme Id (see Update Scheme Id for Customer Default), Financial Instrument Id (see Update Financial Instrument Id for Customer Default).


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
customerRef
required
string
 Default:  ""
The Customer Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
financialInstrumentId
string
The financial instrument Id.


 
schemeId
string
The Scheme Id.


 
object
Metadata is useful for storing additional, structured information on an object.


 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/customer-defaults/{customerRef}
Request samples 
{
  • "financialInstrumentId": "string",
  • "schemeId": "string",
  • "metadata": {
    • "key1": "string",
    • "key2": "string",
    • "key3": "string"
    }
}
Delete Customer Default by Customer Ref
Role Requirements


tenant-transaction-write or tenant-admin


Description


Deletes the customerDefaults for the given customerRef on the Order specified by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
customerRef
required
string
 Default:  ""
The Customer Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
204
No Content.


401
Unauthorized


delete/v2/order-management/{orderRef}/customer-defaults/{customerRef}
Request samples 
Update Financial Instrument Id for Customer Default
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates the financialInstrumentId in customerDefaults for the given customerRef on the Order specified by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
customerRef
required
string
 Default:  ""
The Customer Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
financialInstrumentId
string
The financial instrument Id.


 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/customer-defaults/{customerRef}/financial-instrument-id
Request samples 
{
  • "financialInstrumentId": "string"
}
Update Scheme Id for Customer Default
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates the schemeId in customerDefaults for the given customerRef on the Order specified by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
customerRef
required
string
 Default:  ""
The Customer Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
schemeId
string
The scheme Id.


 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/customer-defaults/{customerRef}/scheme-id
Request samples 
{
  • "schemeId": "string"
}
Update Metadata for Customer Default
Role Requirements


tenant-transaction-write or tenant-admin


Description


Updates the metadata in customerDefaults for the given customerRef on the Order specified by orderRef.


Securitybearer 
Request 
path Parameters
orderRef
required
string
 Default:  ""
The Order Ref.


 
customerRef
required
string
 Default:  ""
The Customer Ref.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
property name*
additional property
string
 
Responses 
204
No Content.


401
Unauthorized


put/v2/order-management/{orderRef}/customer-defaults/{customerRef}/metadata
Request samples 
{
  • "key1": "string",
  • "key2": "string",
  • "key3": "string"
}
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
 Default:  ""
The Order Ref value of the Instruction.


 
instructionRef
required
string
 Default:  ""
The Instruction Ref value of the Instruction.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
201
Created - No content.


401
Unauthorized


post/v2/order-management/{orderRef}/instruction/{instructionRef}/authorize-reward
Request samples 
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
 Default:  ""
The Order Ref value of the Instruction.


 
instructionRef
required
string
 Default:  ""
The Instruction Ref value of the Instruction.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
rewardId
string
The reward Id.


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


401
Unauthorized


post/v2/order-management/{orderRef}/instruction/{instructionRef}/claim-reward
Request samples 
{
  • "rewardId": "string"
}
Copyright © Imburse AG 2018-2022. All right reserved.