Customer Vault

Get Customer

Role Requirements

tenant-transaction-read or tenant-admin

Description

Get a customer by the customerRef.

Securitybearer
Request
path Parameters
customerRef
required
string [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$

The Customer 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.

Responses
200

OK - Returns the Customer response.

400

Bad Request - Validation error response, containing errors such as:

  • Metadata value size out of range. It must not exceed 256 in length.
  • CustomerRef contains invalid characters. It must contain only alphanumeric characters or [-_.].
default

All other managed 4xx and 5xx errors

get/v1/customer-vault/{customerRef}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "self": {
      • "href": "/v1/customer-vault/customer1"
      },
    • "financialInstruments": [
      • {
        • "href": "/v1/customer-vault/customer1/financial-instrument/4249b9ae-f238-cce4-474e-49bcd3ab7363",
        • "name": "4249b9ae-f238-cce4-474e-49bcd3ab7363"
        }
      ]
    },
  • "status": "ACTIVE",
  • "metadata": {
    • "customKey1": "custom string 1"
    },
  • "financialInstruments": [
    • {
      • "id": "4249b9ae-f238-cce4-474e-49bcd3ab7363",
      • "type": "MANDATE:BECS_AU",
      • "status": "INACTIVE",
      • "displayName": "AC7PA3NTHT",
      • "createdDate": 1687508113388,
      • "authorizationSource": "WEB",
      • "details": {
        • "financialInstrumentType": "BECS_AU",
        • "mandateReference": "AC7PA3NTHT",
        • "debtorName": "JOE BLOGGS",
        • "debtorAccountNumber": 123456,
        • "debtorBranchCode": 82082,
        • "creditorName": "Imburse",
        • "creditorIdentifier": 123456,
        • "imburseMandateId": "92db029e-7d76-41d4-8c9e-78302f7ca091",
        • "statusReason": "1: Invalid BSB number",
        • "hasFirstTransactionBeenSent": true,
        • "providerName": "GoCardless",
        • "providerMandateRef": null
        },
      • "capabilities": {
        • "valueType": "VARIABLE",
        • "usageType": "MULTIPLE",
        • "canCredit": true,
        • "canDebit": true
        },
      • "agreement": {
        • "agreementType": "Reuse"
        }
      }
    ]
}
Update Customer
Role Requirements


tenant-transaction-write or tenant-admin


Description


Update a customer by the customerRef.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer 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
object or null (MetadataV2) 
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 
202
Accepted.


400
Bad Request - Validation error response, containing errors such as:


    

  • Metadata key size out of range. It must not exceed 64 in length.
    • 

  • Metadata value size out of range. It must not exceed 256 in length.
    • 



default
All other managed 4xx and 5xx errors


put/v1/customer-vault/{customerRef}
Request samples 
application/json
{
  • "metadata": {
    • "customKey1": "custom string 1",
    • "customKey2": "custom string 2",
    • "customKey3": "custom string 3"
    }
}
Response samples 
application/json
Metadata key {key} must not exceed {maxKeySize} in length.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "METADATA_KEY_SIZE_OUT_OF_RANGE",
      • "message": "Metadata key [aaaaaaaaaaaaaaaa...aaaaaaaaaaaaaaaa] must not exceed [64] in length.",
      • "messageTemplate": "Metadata key {key} must not exceed {maxKeySize} in length.",
      • "metadata": {
        • "key": "aaaaaaaaaaaaaaaa...aaaaaaaaaaaaaaaa",
        • "maxKeySize": 64
        }
      }
    ]
}
Forget Customer
Role Requirements


tenant-admin ONLY


Description


This API call will irrecoverably trash any personally identifiable data about a customer in accordance with GDPR.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer 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.


 
Responses 
200
Success


400
Bad Request - Validation error response, containing errors such as:


    

  • Customer has active financial instruments.
    • 



default
All other managed 4xx and 5xx errors


post/v1/customer-vault/{customerRef}/forget
Request samples 
Response samples 
application/json
Cannot forget customer with active financial instruments.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "CUSTOMER_HAS_ACTIVE_FINANCIAL_INSTRUMENTS",
      • "message": "Cannot forget customer with active financial instruments.",
      • "messageTemplate": "Cannot forget customer with active financial instruments.",
      • "metadata": { }
      }
    ]
}
Get Financial Instrument
Role Requirements


tenant-transaction-read or tenant-admin


Description


Get a Financial Instrument by the financialInstrumentId.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer reference.


 
financialInstrumentId
required
string <uuid>   = 36 characters 
The Financial Instrument Id (lowercase and hyphenated).


 
 Example:  d9e44965-60ae-4f8c-bdc0-e17005bfa0a8
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.


 
Responses 
200
OK - Returns the financial instrument response.


400
Bad Request - Validation error response, containing errors such as:


    

  • FinancialInstrumentId is invalid.
    • 



default
All other managed 4xx and 5xx errors


get/v1/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "self": {
      • "href": "/v1/customer-vault/customer1/financial-instrument/701f7a2c-7fba-d2eb-038d-93fc736273af"
      },
    • "transactions": [
      • {
        • "href": "/v1/customer-vault/customer1/financial-instrument/701f7a2c-7fba-d2eb-038d-93fc736273af/transaction/afcf9124-aff6-4ffe-b0c7-3272513840b0",
        • "name": "afcf9124-aff6-4ffe-b0c7-3272513840b0"
        }
      ]
    },
  • "id": "701f7a2c-7fba-d2eb-038d-93fc736273af",
  • "displayName": "12345678",
  • "type": "BANK_ACCOUNT:UK",
  • "status": "ACTIVE",
  • "details": {
    • "financialInstrumentType": "UK",
    • "accountHolderName": "JOE BLOGGS",
    • "accountNumber": "12345678",
    • "sortCode": "123456"
    },
  • "capabilities": {
    • "valueType": "VARIABLE",
    • "usageType": "MULTIPLE",
    • "canCredit": true,
    • "canDebit": false
    },
  • "transactions": [
    • {
      • "id": "afcf9124-aff6-4ffe-b0c7-3272513840b0",
      • "attempt": 1,
      • "type": "BANK_ACCOUNT:UK",
      • "createdDate": 1690883599702,
      • "amount": 10,
      • "currency": "GBP",
      • "orderRef": "order1",
      • "instructionRef": "instruction1"
      }
    ]
}
Close Financial Instrument
Role Requirements


tenant-transaction-write or tenant-admin


Description


Close a financial instrument.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer reference.


 
financialInstrumentId
required
string <uuid>   = 36 characters 
The Financial Instrument Id (lowercase and hyphenated).


 
 Example:  d9e44965-60ae-4f8c-bdc0-e17005bfa0a8
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
reason
string
The reason that the Financial Instrument was closed.


 
Responses 
200
Success


400
Bad Request - Validation error response, containing errors such as:


    

  • FinancialInstrumentId is invalid.
    • 



default
All other managed 4xx and 5xx errors


put/v1/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/close
Request samples 
application/json
{
  • "reason": "Subscription cancelled."
}
Response samples 
application/json
FinancialInstrumentId {financialInstrumentId} is invalid.


{
  • "timestamp": 1692016778499,
  • "correlationId": "0HMB2TA322CA7:00000001",
  • "errors": [
    • {
      • "errorCode": "FINANCIAL_INSTRUMENT_ID_IS_INVALID",
      • "message": "FinancialInstrumentId [fd65d608-9a92-6210-8942-536855e10706] is invalid.",
      • "messageTemplate": "FinancialInstrumentId {financialInstrumentId} is invalid.",
      • "metadata": {
        • "financialInstrumentId": "fd65d608-9a92-6210-8942-536855e10706"
        }
      }
    ]
}
Get Transaction
Role Requirements


tenant-transaction-read or tenant-admin


Description


Get a Transaction by the financialInstrumentId and transactionId.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer reference.


 
financialInstrumentId
required
string <uuid>   = 36 characters 
The Financial Instrument Id (lowercase and hyphenated).


 
 Example:  d9e44965-60ae-4f8c-bdc0-e17005bfa0a8
transactionId
required
string <uuid>   = 36 characters 
The Transaction Id (lowercase and hyphenated).


 
 Example:  8afff6b5-a4f9-465f-b31b-a2702cadeb8b
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.


 
Responses 
200
OK - Returns the transaction response.


400
Bad Request - Validation error response, containing errors such as:


    

  • FinancialInstrumentId is invalid.
    • 

  • Transaction not found.
    • 



default
All other managed 4xx and 5xx errors


get/v1/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/transaction/{transactionId}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "self": {
      • "href": "/v1/customer-vault/customer1/financial-instrument/4249b9ae-f238-cce4-474e-49bcd3ab7363/transaction/792c4c75-36e0-4e1b-9db8-7e5708b36a30"
      }
    },
  • "id": "792c4c75-36e0-4e1b-9db8-7e5708b36a30",
  • "type": "BECS_AU_DIRECT_DEBIT",
  • "createdTimestamp": 1689221842419,
  • "lastUpdatedTimestamp": 1689221894919,
  • "settlementDate": null,
  • "status": "FAILED",
  • "app": {
    • "appId": "IMBURSE",
    • "appTransactionId": "792c4c75-36e0-4e1b-9db8-7e5708b36a30",
    • "appBatchId": "",
    • "supportDetails": {
      • "customerId": "cus_MH3lMCEjrZ4O0Q"
      }
    },
  • "orderRef": "order1",
  • "instructionRef": "instruction1",
  • "amount": 10.03,
  • "currency": "AUD",
  • "failedErrorCode": "INVALID_ACCOUNT_IDENTIFIER",
  • "failedReason": "1 - Invalid BSB number",
  • "netAmount": 10.03,
  • "capabilities": {
    • "isRefundable": false
    },
  • "refunds": [ ],
  • "chargebacks": [ ],
  • "processingDetails": {
    • "channel": "eCom",
    • "authenticationFlow": null
    }
}
Create Refund
Role Requirements


tenant-transaction-write or tenant-admin


Description


Create a refund with the financialInstrumentId and transactionId.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer reference.


 
financialInstrumentId
required
string <uuid>   = 36 characters 
The Financial Instrument Id (lowercase and hyphenated).


 
 Example:  d9e44965-60ae-4f8c-bdc0-e17005bfa0a8
transactionId
required
string <uuid>   = 36 characters 
The Transaction Id (lowercase and hyphenated).


 
 Example:  8afff6b5-a4f9-465f-b31b-a2702cadeb8b
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
amount
required
number <decimal>  (Amount) 
Currency amount. The number of decimal digits is validated against the currency code of the payment.


 
reason
string or null  <= 100 characters 
The reason for the refund.


 
Responses 
200
OK - Returns the created refund response.


400
Bad Request - Validation error response, containing errors such as:


    

  • CustomerRef is required.
    • 

  • CustomerRef length out of range. It exceeds the maximum length 50.
    • 

  • CustomerRef contains invalid characters. It must contain only alphanumeric characters or [-_.].
    • 

  • FinancialInstrumentId is required.
    • 

  • FinancialInstrumentId is invalid.
    • 

  • Amount is required.
    • 

  • Amount out of range. It must be greater than zero.
    • 

  • Refund period expired, according to payment provider and/or payment technology.
    • 

  • Invalid refund amount.
    • 

  • Invalid instruction direction. A transaction that belongs to an instruction with a direction of CREDIT can not be refunded.
    • 

  • Transaction not yet complete.
    • 

  • TransactionId is required.
    • 

  • Reason length out of range. It exceeds the maximum length 100.
    • 



default
All other managed 4xx and 5xx errors


post/v1/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/transaction/{transactionId}/refund
Request samples 
application/json
{
  • "amount": 17.99,
  • "reason": "Subscription cancelled."
}
Response samples 
application/json
{
  • "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
  • "status": "string"
}
Get Refund
Role Requirements


tenant-transaction-read or tenant-admin


Description


Get a refund with the financialInstrumentId, transactionId and refundId.


Securitybearer 
Request 
path Parameters
customerRef
required
string  [ 1 .. 50 ] characters ^[a-zA-Z0-9-_\.]+$
The Customer reference.


 
financialInstrumentId
required
string <uuid>   = 36 characters 
The Financial Instrument Id (lowercase and hyphenated).


 
 Example:  d9e44965-60ae-4f8c-bdc0-e17005bfa0a8
transactionId
required
string <uuid>   = 36 characters 
The Transaction Id (lowercase and hyphenated).


 
 Example:  8afff6b5-a4f9-465f-b31b-a2702cadeb8b
refundId
required
string <uuid>   = 36 characters 
The system generated refund identifier (lowercase and hyphenated).


 
 Example:  1d0e0fef-0a0e-491d-917e-035f31cdc032
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.


 
Responses 
200
The Refund object.


400
Bad Request - Validation error response, containing errors such as:


    

  • FinancialInstrumentId is invalid.
    • 

  • Transaction not found.
    • 



default
All other managed 4xx and 5xx errors


get/v1/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/transaction/{transactionId}/refund/{refundId}
Request samples 
Response samples 
application/json
{
  • "refundId": "1ae4fddd-4cf6-493d-b171-2dbcfd93ec08",
  • "status": "COMPLETED",
  • "amount": 12.34,
  • "currency": "EUR",
  • "refundedTransactionId": "26fc43b3-88a5-426f-bfca-d030a4ba3be6",
  • "reason": "Customer returned purchased item nr 123.",
  • "createdTimestamp": 1636123359241,
  • "lastUpdatedTimestamp": 1636123360,
  • "app": {
    • "appId": "IMBURSE_TESTING_V2",
    • "appTransactionId": "26fc43b3-88a5-426f-bfca-d030a4ba3be6",
    • "supportDetails": { }
    },
  • "failedResponse": null
}
Copyright 2025 Duck Creek Technologies. All Rights Reserved.