Download OpenAPI specification:Download
Role Requirements
tenant-transaction-read or tenant-admin
Description
Gets an Order Instruction by the orderRef and instructionRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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.
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} curl JavaScript C# Java Node.js Python Go PHP
Copy
Expand all Collapse all { "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" :
{ } , "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" ,
"refunds" :
[ { "refundId" : "07924e91-3470-442d-8c8a-81282b41b74e" ,
"createdTimestamp" : 1662543387150 ,
"lastUpdatedTimestamp" : 1662543388793 ,
"status" : "COMPLETED" ,
"amount" : 2.34 ,
"refundReason" : "Card has insufficient funds." ,
"failureReasonCode" : "INSUFFICIENT_FUNDS" ,
"failureDescription" : "Refund is pending due to insufficient funds and has crossed the pending refund expiry window."
} ] , "chargebacks" :
[ { "id" : "cf223726-7ac8-4294-bb4b-75748b619268" ,
"network" : "STRIPE" ,
"status" : "PENDING" ,
"amount" : 9.31 ,
"claimed" : "2024-01-21" ,
"created" : "2024-01-21T09:20:31Z" ,
"lastUpdatedAt" : "2024-01-22T10:05:40Z" ,
"payingBankReference" : "CMRSA04KG0J" ,
"reasonCode" : "MD06" ,
"description" : "Disputed authorized transaction"
} ] , } , "failed" : null ,
"cancelled" : null
}
Role Requirements
tenant-transaction-write or tenant-admin
Description
Updates a new Instruction by orderRef and instructionRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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 string <uuid> (FinancialInstrumentId)
The system generated Financial Instrument identifier.
number <decimal> (Amount)
Currency amount. The number of decimal digits is validated against the currency code of the payment.
string (Currency) ^[A-Z]{3}$
ISO 4217 code (3 uppercase letters) for the chosen currency.
string (Country) ^[A-Z]{2}$
The ISO 3166-1 alpha 2 country code (2 letter code) for the chosen country of the future transaction.
string <date>
The date in which a payment is to be settled by, or, if automated, will be taken on.
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.
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} Payload curl JavaScript C# Java Node.js Python Go PHP 4 more Node.js Python Go PHP 4 more Copy
Expand all Collapse all { "financialInstrumentId" : "35596f91-fea9-4297-b70b-01fdad24e25a" ,
"amount" : 20 ,
"currency" : "GBP" ,
"country" : "GB" ,
"settledByDate" : "2019-08-24" ,
"schemeId" : "ef1c9dbe-017b-4011-8bd1-352897f8dfef" ,
}
Order not found Instruction not found Instruction cancelled Instruction processing Order not found Order {orderRef} does not exist.
Copy
Expand all Collapse all { "timestamp" : 1692016778499 ,
"correlationId" : "0HMB2TA322CA7:00000001" ,
"errors" :
[ { "errorCode" : "ORDER_NOT_FOUND" ,
"message" : "Order [orderRef] does not exist." ,
"messageTemplate" : "Order {orderRef} does not exist." ,
} ] }
Role Requirements
tenant-transaction-write or tenant-admin
Description
Create a new Order Instruction for the specified orderRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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 required
string (InstructionRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$
The instruction reference. [Required].
required
string (CustomerRef) <= 50 characters ^[a-zA-Z0-9-_\.]+$
The client defined unique Customer Reference.
required
string (Direction)
The direction of the instruction: Debit or Credit.
The Scheme used must match this direction.
Enum: "DEBIT" "CREDIT" string <uuid> (FinancialInstrumentId)
The system generated Financial Instrument identifier.
required
number <decimal> (Amount)
Currency amount. The number of decimal digits is validated against the currency code of the payment.
required
string (Currency) ^[A-Z]{3}$
ISO 4217 code (3 uppercase letters) for the chosen currency.
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.
required
string <date>
The date in which a payment is to be settled by, or, if automated, will be taken on.
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.
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 Payload curl JavaScript C# Java Node.js Python Go PHP 4 more Node.js Python Go PHP 4 more Copy
Expand all Collapse all { "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" ,
}
Order not found InstructionRef is required Instruction already exists CustomerRef is required Direction is required Amount is required Amount out of range Amount is invalid Currency is required Currency length out of range Country is required Country length out of range SettledByDate is required SettledByDate is invalid SchemeId not recognised Order not found Order {orderRef} does not exist.
Copy
Expand all Collapse all { "timestamp" : 1692016778499 ,
"correlationId" : "0HMB2TA322CA7:00000001" ,
"errors" :
[ { "errorCode" : "ORDER_NOT_FOUND" ,
"message" : "Order [orderRef] does not exist." ,
"messageTemplate" : "Order {orderRef} does not exist." ,
} ] }
Role Requirements
tenant-transaction-write or tenant-admin
Description
Cancels an Instruction.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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 string <= 256 characters
Optional cancellation reason.
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 Payload curl JavaScript C# Java Node.js Python Go PHP 4 more Node.js Python Go PHP 4 more
Order not found Instruction not found Instruction cancelled Instruction processing Order not found Order {orderRef} does not exist.
Copy
Expand all Collapse all { "timestamp" : 1692016778499 ,
"correlationId" : "0HMB2TA322CA7:00000001" ,
"errors" :
[ { "errorCode" : "ORDER_NOT_FOUND" ,
"message" : "Order [orderRef] does not exist." ,
"messageTemplate" : "Order {orderRef} does not exist." ,
} ] }
Role Requirements
tenant-transaction-read or tenant-admin
Description
Gets an Order by the orderRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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.
200 OK - Returns the Order response.
400 Bad Request - Validation error response, containing errors such as:
default All other managed 4xx and 5xx errors
get /v1/order-management/{orderRef} curl JavaScript C# Java Node.js Python Go PHP
Copy
Expand all Collapse all
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.
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 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.
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
Payload curl JavaScript C# Java Node.js Python Go PHP 4 more Node.js Python Go PHP 4 more Copy
Expand all Collapse all { "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" ,
} ,
{ "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" ,
} ] , }
Order already exists OrderRef is required InstructionRef is required CustomerRef is required Direction is required Amount is required Amount out of range Amount is invalid Currency is required Currency length out of range Country is required Country length out of range SettledByDate is required SettledByDate is invalid SchemeId not recognised Order already exists Order {orderRef} already exists.
Copy
Expand all Collapse all { "timestamp" : 1692016778499 ,
"correlationId" : "0HMB2TA322CA7:00000001" ,
"errors" :
[ { "errorCode" : "ORDER_ALREADY_EXISTS" ,
"message" : "Order [orderRef] already exists." ,
"messageTemplate" : "Order {orderRef} already exists." ,
} ] }
Deprecated Role Requirements
tenant-transaction-write or tenant-admin
Description
Authorizes a Reward by the customerRef and instructionRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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.
default All other managed 4xx and 5xx errors
post /v1/order-management/{orderRef}/instruction/{instructionRef}/authorize-reward curl JavaScript C# Java Node.js Python Go PHP
Copy
Expand all Collapse all { "status" : 401 ,
"title" : "Unauthorized" ,
"detail" : "Invalid token" ,
"instance" : "/v1/customer-vault/customer1/international-bank-account/" ,
} Deprecated Role Requirements
tenant-transaction-write or tenant-admin
Description
Claims a Reward by the customerRef and instructionRef.
path Parameters required
string <= 50 characters ^[a-zA-Z0-9-_\.]+$
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 default All other managed 4xx and 5xx errors
post /v1/order-management/{orderRef}/instruction/{instructionRef}/claim-reward Payload curl JavaScript C# Java Node.js Python Go PHP 4 more Node.js Python Go PHP 4 more
Copy
Expand all Collapse all { "status" : 401 ,
"title" : "Unauthorized" ,
"detail" : "Invalid token" ,
"instance" : "/v1/customer-vault/customer1/international-bank-account/" ,
}