Customer Vault

Get a Customer

Role Requirements

tenant-transaction-read or tenant-admin

Description

Securitybearer
Request
path Parameters
customerRef
required
string
Default: ""

The Customer Ref value.

header Parameters
x-account-id
required
string

The Account Id

x-tenant-id
required
string

The Tenant Id

x-correlation-id
string

Correlation Id for the request

Responses
200

OK - Returns the Customer response.

401

Unauthorized

get/v2/customer-vault/{customerRef}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "property1": { },
    • "property2": { }
    },
  • "status": "string",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "financialInstruments": [
    • {
      • "id": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
      • "type": "MANDATE:BACS_DIRECT_DEBIT",
      • "status": "ACTIVE",
      • "displayName": "Bacs direct debit mandate: GHXML21P",
      • "createdTimestamp": 1662106155297,
      • "capabilities": {
        • "valueType": "VARIABLE",
        • "usageType": "MULTIPLE",
        • "canCredit": false,
        • "canDebit": true
        }
      }
    ]
}
Update a Customer
Role Requirements


tenant-transaction-write or tenant-admin


Description


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
The Customer Ref value.


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
object
Metadata is useful for storing additional, structured information on an object.


 
Responses 
202
Accepted.


401
Unauthorized


put/v2/customer-vault/{customerRef}
Request samples 
{
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}
Forget a 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
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
200
Success


401
Unauthorized


post/v2/customer-vault/{customerRef}/forget
Request samples 
Get a Financial Instrument by it's Id
Role Requirements


tenant-transaction-read or tenant-admin


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
financialInstrumentId
required
string <uuid> 
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
200
OK - Returns the financial instrument response.


401
Unauthorized


get/v2/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}
Request samples 
Response samples 
application/json
{
  • "id": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "attempt": 1,
  • "type": "VISA",
  • "createdDate": 1662106112679,
  • "orderRef": "Testing_2",
  • "instructionRef": "PAYMENT-01",
  • "amount": 10,
  • "currency": "EUR"
}
Close financial instrument
Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
financialInstrumentId
required
string <uuid> 
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
reason
string
 
Responses 
200
Success


401
Unauthorized


put/v2/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/close
Request samples 
{
  • "reason": "string"
}
Get a Transaction by it's Financial Instrument Id and Transaction Id
Role Requirements


tenant-transaction-read or tenant-admin


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
financialInstrumentId
required
string <uuid> 
 Default:  ""
 
transactionId
required
string <uuid> 
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
200
OK - Returns the transaction response.


401
Unauthorized


403
Forbidden


404
Transaction not found


get/v2/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/transaction/{transactionId}
Request samples 
Response samples 
application/json
{
  • "_links": {
    • "property1": { },
    • "property2": { }
    },
  • "id": "be4bc9c1-c3fb-43c8-ab1a-908a86123682",
  • "type": "STRIPE",
  • "createdTimestamp": 1662106112679,
  • "settlementDate": "2023-12-15",
  • "lastUpdatedTimestamp": 1662106112679,
  • "status": "COMPLETED",
  • "app": {
    • "appId": "STRIPE",
    • "appTransactionId": "pi_3LdUv5Hm8hoYQJyN1zEjvXpY",
    • "appBatchId": null,
    • "supportDetails": {
      • "property1": "paymentDescriptorField",
      • "property2": "paymentDescriptorField"
      }
    },
  • "orderRef": "Testing_2",
  • "instructionRef": "PAYMENT-01",
  • "amount": 10,
  • "currency": "EUR",
  • "failedErrorCode": null,
  • "failedReason": null,
  • "netAmount": 10,
  • "capabilities": {
    • "isRefundable": true
    },
  • "refunds": [
    • {
      • "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
      • "createdTimestamp": 1662106155297,
      • "lastUpdatedTimestamp": 1662106162568,
      • "status": "Failed",
      • "amount": 1.5
      }
    ],
  • "chargebacks": [
    • {
      • "id": "e8febe3c-cc7d-49b1-8f54-cbde4341676c",
      • "network": "STRIPE",
      • "status": "FAILED",
      • "amount": 10,
      • "claimed": "2019-08-24T14:15:22Z",
      • "created": "2019-08-24T14:15:22Z"
      }
    ]
}
Add an International Bank Account financial instrument
Role Requirements


tenant-transaction-write or tenant-admin


Description


Create an International Bank Account financial instrument.


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
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


401
Unauthorized


403
Forbidden


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


tenant-transaction-write or tenant-admin


Description


Create a UK Bank Account financial instrument.


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: 
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


401
Unauthorized


403
Forbidden


post/v2/customer-vault/{customerRef}/uk-bank-account
Request samples 
{
  • "accountHolderName": "JOHN DOE",
  • "accountNumber": "99999911",
  • "sortCode": "111211"
}
Response samples 
application/json
{
  • "_links": {
    • "property1": "string",
    • "property2": "string"
    },
  • "id": "string"
}
Create a refund with the  Financial Instrument Id and Transaction Id
Role Requirements


tenant-transaction-read or tenant-admin


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
financialInstrumentId
required
string <uuid> 
 Default:  ""
 
transactionId
required
string <uuid> 
 Default:  ""
 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Request Body schema: application/json-patch+json
amount
required
number <double> 
 
reason
string or null  <= 100 characters 
 
Responses 
200
OK - Returns the created refund response.


400
Bad Request


401
Unauthorized


403
Forbidden


post/v2/customer-vault/{customerRef}/financial-instrument/{financialInstrumentId}/transaction/{transactionId}/refund
Request samples 
application/json-patch+json
{
  • "amount": 0,
  • "reason": "string"
}
Response samples 
application/json
{
  • "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
  • "status": "string"
}
Get a refund with the Financial Instrument Id and Transaction Id
Role Requirements


tenant-transaction-read or tenant-admin


Securitybearer 
Request 
path Parameters
customerRef
required
string
 Default:  ""
 
financialInstrumentId
required
string <uuid> 
 Default:  ""
 
transactionId
required
string <uuid> 
 Default:  ""
 
refundId
required
string <uuid>  (RefundId) 
The system generated refund identifier


 
header Parameters
x-account-id
required
string
The Account Id


 
x-tenant-id
required
string
The Tenant Id


 
x-correlation-id
string
Correlation Id for the request


 
Responses 
200
The Refund object.


401
Unauthorized


403
Forbidden


404
Refund not found


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 © Imburse AG 2018-2022. All right reserved.