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.