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.

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/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:ACH",
      • "status": "INACTIVE",
      • "displayName": "AC7PA3NTHT",
      • "createdDate": 1687508113388,
      • "details": {
        • "financialInstrumentType": "ACH",
        • "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 Routing number",
        • "hasFirstTransactionBeenSent": "True",
        • "providerName": "Ach",
        • "providerMandateRef": "MXAOQKEJW",
        • "debtorAccountType": "Checking",
        • "authorizationSource": "WEB",
        • "authorizationFrequency": "Monthly"
        },
      • "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",
  • "agreement": {
    • "agreementId": "c64e3604-ff53-4bbb-88ed-eb29c6111b66",
    • "agreementType": "Reuse",
    • "consentedTimestamp": 1704297528100,
    • "consentedWording": "By proceeding you are agreeing for your payment details to be stored for future use by CLIENT_NAME"
    },
  • "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": {
      • "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": [ ]
}
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 .. 140 ] characters [a-zA-Z0-9.&-/ ]
The name of the account holder or beneficiary.


    

  • BACS: 3 to 18 characters
    • 

  • SEPA: 3 to 140 characters
    • 

  • BECS AU: 3 to 18 characters
    • 

  • BECS NZ: 3 to 18 characters
    • 

  • ACH: 3 to 22 characters
    • 



Different PSPs may have different limits.


 
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" "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 140 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.