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.

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

default

All other managed 4xx and 5xx errors

get/v2/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,
      • "details": {
        • "financialInstrumentType": "BECS_AU",
        • "mandateReference": "AC7PA3NTHT",
        • "debtorName": "JOE BLOGGS",
        • "debtorAccountNumber": "000123456",
        • "debtorBranchCode": "082082",
        • "debtorBankName": "Bank of Imburse",
        • "debtorSignatoryName": "JOE BLOGGS",
        • "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
        }
      }
    ]
}

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.

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
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/v2/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.

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

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/v2/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>

The Financial Instrument Id.

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 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/v2/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>

The Financial Instrument Id.

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

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/v2/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>

The Financial Instrument Id.

transactionId
required
string <uuid>

The Transaction Id.

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 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/v2/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": {
      • "status": ""
      }
    },
  • "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": [ ]
}

Add International Bank Account Financial InstrumentDeprecated

Role Requirements

tenant-transaction-write or tenant-admin

Description

Create an International Bank Account financial instrument.

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.

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
name
string

The name of the account holder or beneficiary

iban
required
string

The International Bank Account Number. It's format is specified by ISO 13616 and consists of the country code, 2 letters (ISO 3166), 2 check digits and up to 30 alphanumeric characters that represent the Basic Bank Account Number.

bic
string

The Bank Identifier Code, the SWIFT address assigned to the bank that holds the account. It consists of a 4 character bank code, 2 character country code (ISO 3166), 2 character location code for the bank's head office and an optional 3 character code for the branch location

Responses
201

Created.

400

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

  • Iban is required.
default

All other managed 4xx and 5xx errors

post/v2/customer-vault/{customerRef}/international-bank-account
Request samples
application/json
{
  • "name": "John Doe",
  • "iban": "GB09KDUX86642922629868",
  • "bic": "CGDITLD3"
}
Response samples
application/json
{
  • "_links": {
    • "property1": { },
    • "property2": { }
    },
  • "id": "string"
}

Add UK Bank Account Financial InstrumentDeprecated

Role Requirements

tenant-transaction-write or tenant-admin

Description

Create a UK Bank Account financial instrument.

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.

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
accountHolderName
string

The name of the account holder or beneficiary Must be all uppercase, between 3 - 18 in length with only [A-Z0-9.&∕] and whitespace characters.

accountNumber
string

The number of the account.

sortCode
string

The 6 digits comprising an account's sort-code.

Responses
201

Created.

400

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

  • AccountHolderName is required.
  • AccountHolderName is invalid. It must only include [A-Z 0-9 - . & /] and whitespace.
  • AccountHolderName out of range. It must be less than or equal to 18 characters.
default

All other managed 4xx and 5xx errors

post/v2/customer-vault/{customerRef}/uk-bank-account
Request samples
application/json
{
  • "accountHolderName": "JOHN DOE",
  • "accountNumber": "99999911",
  • "sortCode": "111211"
}
Response samples
application/json
{
  • "_links": {
    • "property1": { },
    • "property2": { }
    },
  • "id": "string"
}

Add Bank Account Financial Instrument

Role Requirements

tenant-transaction-write or tenant-admin

Description

Create a Bank Account financial instrument.

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.

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
type
required
string (BankAccountType)

The type of bank account to create.

Enum: "UK" "IBAN" "AU" "NZ" "US"
accountHolderName
required
string [ 3 .. 22 ] characters [a-zA-Z0-9.&-]

The name of the account holder or beneficiary.

accountNumber
required
string [ 6 .. 30 ] characters [A-Z0-9]

The number of the account.

extraCode
string <= 11 characters [A-Z0-9]

Information about routing number, BIC, BSB or Sortcode depending on the type of Bank Account.

Mandatory for UK, AU, US bank account types.

Mandatory on IBAN bank account type, if the country code is a non-EEA country.

accountType
string

Required for US account type

The type of bank account.

Enum: "Checking" "General Ledger" "Savings"
authorizationSource
string

Required for US account type

The authorization code indicates how the account authorization was obtained.

Enum: "CCD" "PPD"
Responses
201

Created.

400

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

  • Type is invalid. It must be one of UK, IBAN, AU, NZ or US.
  • AccountHolderName is required.
  • AccountHolderName is invalid. It must only include [A-Z 0-9 - . & /] and whitespace.
  • AccountHolderName out of range. It must be between 3 and 22 characters.
  • AccountNumber is required.
  • AccountNumber is invalid. It must only include [A-Z 0-9].
  • AccountNumber out of range. It must be between 6 and 30 characters.
default

All other managed 4xx and 5xx errors

post/v2/customer-vault/{customerRef}/bank-account
Request samples
application/json

UK (BACS) Bank Account

{
  • "type": "UK",
  • "accountHolderName": "GEORGE DOE",
  • "accountNumber": "55779911",
  • "extraCode": "200000"
}
Response samples
application/json
{
  • "_links": {
    • "property1": { },
    • "property2": { }
    },
  • "id": "string"
}

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>

The Financial Instrument Id.

transactionId
required
string <uuid>

The Transaction Id.

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
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/v2/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>

The Financial Instrument Id.

transactionId
required
string <uuid>

The Transaction Id.

refundId
required
string <uuid> (RefundId)

The system generated refund identifier

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

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/v2/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 2024 Duck Creek Technologies. All Rights Reserved.