Transaction API (v2)

Download OpenAPI specification:Download

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.