Skip to main content

Order Management Flow

This document describes the complete lifecycle of Payment Orders and FX Orders, including preparation, initiation, confirmation, and post-processing.

💸 Payment Order Flow​

1. Before Order Initiation​

Prefill order details and get price
POST /api/core/customers/{customerId}/payments/calculate-price
See: Post Calculate Payment Price

List contacts for the requested payment currency:
GET /contacts/customers/{customerId}/contacts?pageNumber=1&pageSize=20&name=&currency=gbp
See: Get Contacts per Customer

(Optional) Upload supporting documents (one by one):
POST / DELETE /transaction-case/customers/{customerId}/file/upload
See: Upload Document / Delete Draft Document

  • Specify DocumentType: NoteDocument
  • Save/cache IDs from the response for later use.

2. Initiate Payment Order​

POST /api/core/customers/{customerId}/payments/initiate
See: Post Initiate Payment Order TIP: If paymentPurpose = "Other", pass free text to the paymentPurposeText field.

Get list of order purposes
GET /api/core/customers/{customerId}/payments/order-purposes
See: Get Order Purposes

(Optional) Attach documents uploaded at the step 1.

3. Confirmation of Payee (CoP) — GBP Payments​

If payment is in GBP, the initiation response includes CoP-related fields.

Implementation recommendations:

  • If "copResponseCode": "match", immediately proceed to the next step.
  • For all other codes except AC01, require explicit confirmation before initiating the transfer.
  • If AC01 is returned (account does not exist in the specified bank), the payment order will be cancelled during initiation.

GET list of CoP responses: /dictionaries/countries
See: Get COP Codes

  • "copNameMatch": null → returned account name is similar to the provided one (matched by the bank).

4. Fraud Alerts Handling​

The response may contain a FraudAlerts array triggered by the anti-fraud system.

  • You must obtain explicit user consent to dismiss these alerts (otherwise order won't be created).
  • Pass a record of such consent during order confirmation for each alert.

5. Confirm Payment Order​

POST /api/core/customers/{customerId}/payments/{orderId}/confirm
See: Post Confirm Order

In your request:

  • Pass list of Fraud Alert IDs.
  • Pass externalMfaConfirmed (boolean).
  • (Optional) Pass your own endToEndTransactionId to track the transaction through the system.

Example Response:

{
  "id": "019751ad-768c-748a-b2ce-cf82424c3a80",
  "createdBy": "732c3dcf-d30e-4bb8-a900-990f6695ac58",
  "createdUtc": "2025-06-08T22:33:32.831148+00:00",
  "debtorAccountId": "0259c921-875d-46ad-84bf-d43b99715443",
  "payeeContactId": "1cb96722-7a66-4fe8-8dde-de7511fbbd62",
  "amount": {
    "currencyCode": "gbp",
    "value": 543
  },
  "currentState": "received",
  "paymentPurposeText": "",
  "reference": "xcvzxcv",
  "endToEndTransactionId": "b6015b84-0268-4673-80c3-40ee69506f9f",
  "fraudAlerts": {
    "019751ad-7dfd-7ee6-a781-d983d4dfca10": "Consider double-checking details with payment receiver using another communication channel!"
  },
  "copResponseCode": "match",
  "copNameMatch": null,
  "standingOrder": null
}

💱 FX Order Flow​

1. Initiate FX Order (Get Quote)​

POST /api/core/customers/{customerId}/forex/initiate
See: Post Initiate Forex Order

  • Specify the customer's accounts and the amount.
  • The response includes:
    • orderId
    • quote
    • quote eligibility (expires_at)

2. Confirm FX Order​

POST /api/core/customers/{customerId}/forex/{orderId}/confirm
See: Post Confirm Forex Order

  • Confirm the received quote before it expires.
  • If it expires, request a new quote by initiating the FX order again.

Example Response:

{
  "id": "019753b3-8efa-75b1-a50c-8b39984466b9",
  "sourceAccountId": "0259c921-875d-46ad-84bf-d43b99715443",
  "targetAccountId": "b730eff7-ea7c-4ed5-b264-6764d2a85932",
  "sourceAmount": {
    "currencyCode": "gbp",
    "value": 555
  },
  "targetAmount": {
    "currencyCode": "usd",
    "value": 749.17
  },
  "state": "new",
  "totalRate": 1.3498559,
  "reason": "",
  "expiresUtc": "2025-06-09T08:02:07.937454+00:00",
  "createdUtc": "2025-06-09T07:59:26.440436+00:00",
  "secondsToExpire": 59
}

📊 Retrieve Orders​

Get List of Customer Orders​

GET /api/core/customers/{customerId}/payments
See: Get List of Customer Orders

Get Order Details by ID​

GET /api/core/customers/{customerId}/payments/{orderId}
See: Get Order by ID