openapi: 3.2.0
info:
title: Kraken Post Business Import API
version: v1
description: APIs for importing additional data after a business has been imported.
servers:
- url: https://api.origin-kraken.energy/v1
description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: post_business_import
x-title: Post Business Import
description: APIs for importing additional data after a business has been imported.
x-documentation-order: 3
paths:
/v1/data-import/business-payment-instruction/create/:
post:
operationId: V1 Create Business Payment Instruction
description: Create a payment instruction for a business after import.
summary: Create a payment instruction for a business after import.
tags:
- post_business_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessPaymentInstruction'
examples:
ExamplePayload:
value:
import_supplier_code: TENTACLE_UTILITIES
external_business_identifier: EXTERNAL-1234
vendor: STRIPE
reference: THIS-IS-A-FAKE-REFERENCE
type: CARD
accounts:
- external_account_number: EXTERNAL-ACCOUNT-123
- external_account_number: EXTERNAL-ACCOUNT-1234
summary: Example payload
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBusinessPaymentInstructionError'
examples:
UnableToCreatePaymentInstruction.:
value:
error_detail: Unable to create payment instruction
external_business_identifier: EXTERNAL-1234
import_supplier_code: SOME_IMPORT_SUPPLIER
reference: THIS-IS-A-FAKE-REFERENCE
summary: Unable to create payment instruction.
description: '
If there are validation errors, the errors will be detailed in the body of the response. To
resolve the error, refer to the field definitions and validation rules.
This error can be returned if we have persistent issues communicating with the upstream payment
vendor (we call their API to verify the instruction exists, and retrieve the details to store in
Kraken). In this case, **the request should not be retried in its current form**.
'
'404':
description: The business import process have not been found. To resolve the error, check that the business has been imported (not just staged) and that the `import_supplier_code` and `external_business_identifier` are correct.
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBusinessPaymentInstructionResponse'
examples:
CreatedBusinessPaymentInstruction:
value:
external_business_identifier: EXTERNAL-1234
reference: THIS-IS-A-FAKE-REFERENCE
summary: Created business payment instruction
description: If the payload is valid, the external business identifier and the reference will be returned.
'401':
description: Authentication credentials were not provided or are invalid.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBusinessPaymentInstructionError'
description: '
This error can be returned if we have intermittent issues communicating with the upstream payment
vendor (we call their API to verify the instruction exists, and retrieve the details to store in
Kraken). In this case, **the request should be retried as-is**.
'
x-doc-alerts: []
components:
schemas:
CreateBusinessPaymentInstructionError:
type: object
properties:
error_detail:
type: string
description: If payment instruction creation failed, then this field will provide details of the error.
external_business_identifier:
type: string
description: The unique identifier of a business in the external system. This id is used to link an imported business in Kraken to the external system
maxLength: 128
import_supplier_code:
enum:
- ORIGIN_SOLARFLEX_INACTIVE
- ORIGIN
- WIN_CONNECT_PARENT
- ORIGIN_CNI
- ORIGIN_BUSINESS
- WIN_CONNECT
- ORIGIN_SOLARFLEX
- ORIGIN_BUSINESS_NO_CONTRACT
type: string
x-spec-enum-id: 9572ea198e3a9787
description: The code of an existing ImportSupplier in the database.
x-enum-descriptions:
ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive
ORIGIN: Origin
WIN_CONNECT_PARENT: Win Connect Parent
ORIGIN_CNI: Origin CNI
ORIGIN_BUSINESS: Origin Zero Business Import Supplier
WIN_CONNECT: WinConnect
ORIGIN_SOLARFLEX: Origin SolarFlex
ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee
reference:
type: string
description: The reference of the mandate as known by the vendor.
maxLength: 128
required:
- error_detail
- external_business_identifier
- import_supplier_code
- reference
x-validators:
- name: Validate that migration is ongoing
description: Validate whether or not an import supplier is open for further data migration.
possible_errors:
- import_supplier_migration_not_ongoing
BusinessPaymentInstruction:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/BusinessPaymentInstructionAccount'
description: Accounts for the business to set preference for.
external_business_identifier:
type: string
description: The unique identifier of a business in the external system. This id is used to link an imported business in Kraken to the external system
maxLength: 128
import_supplier_code:
enum:
- ORIGIN_SOLARFLEX_INACTIVE
- ORIGIN
- WIN_CONNECT_PARENT
- ORIGIN_CNI
- ORIGIN_BUSINESS
- WIN_CONNECT
- ORIGIN_SOLARFLEX
- ORIGIN_BUSINESS_NO_CONTRACT
type: string
x-spec-enum-id: 9572ea198e3a9787
description: The code of an existing ImportSupplier in the database.
x-enum-descriptions:
ORIGIN_SOLARFLEX_INACTIVE: Origin SolarFlex Inactive
ORIGIN: Origin
WIN_CONNECT_PARENT: Win Connect Parent
ORIGIN_CNI: Origin CNI
ORIGIN_BUSINESS: Origin Zero Business Import Supplier
WIN_CONNECT: WinConnect
ORIGIN_SOLARFLEX: Origin SolarFlex
ORIGIN_BUSINESS_NO_CONTRACT: Origin Business - No Contracts e.g. trustee
reference:
type: string
description: The reference of the mandate as known by the vendor.
maxLength: 512
type:
enum:
- BPAY
- CARD
- CUSTOM
- DIRECT_DEBIT
- GMO_REFUND
- PAYMENT_SLIP
type: string
x-spec-enum-id: 601d0b035869d4dd
description: The payment type of the payment instruction.
x-enum-descriptions:
BPAY: BPAY
CARD: Card
CUSTOM: Custom
DIRECT_DEBIT: Direct Debit
GMO_REFUND: GMO Refund
PAYMENT_SLIP: Payment slip
valid_from:
type:
- string
- 'null'
format: date
description: The date from which the payment instruction is valid.
vendor:
enum:
- WESTPAC
type: string
x-spec-enum-id: 19baa89b6ef9d00c
description: The vendor for the payment instruction.
x-enum-descriptions:
WESTPAC: Westpac
required:
- external_business_identifier
- import_supplier_code
- type
- vendor
x-validators:
- name: Validate that migration is ongoing
description: Validate whether or not an import supplier is open for further data migration.
possible_errors:
- import_supplier_migration_not_ongoing
CreateBusinessPaymentInstructionResponse:
type: object
properties:
external_business_identifier:
type: string
description: The unique identifier of a business in the external system. This id is used to link an imported business in Kraken to the external system
maxLength: 128
reference:
type: string
description: The reference of the mandate as known by the vendor.
maxLength: 128
required:
- external_business_identifier
- reference
BusinessPaymentInstructionAccount:
type: object
properties:
external_account_number:
type: string
description: The account number in the source system. This, along with the import_supplier, will be used to find the account in Kraken.
required:
- external_account_number
securitySchemes:
DRFKrakenTokenAuthentication:
type: apiKey
in: header
name: Authorization
description: JWT-based authentication
DataImportViewerAPIKeyAuthentication:
type: apiKey
in: header
name: Authorization
description: Token-based authentication with required prefix "Token "