> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a payout instruction
> Register the bank account Tilta pays out to when a merchant's invoice is captured and financed.
Payout Instructions define the bank account to which Tilta transfers funds once a merchant's invoice is captured and financed. Every approved merchant needs at least one verified payout instruction before their orders can result in a payout.
Create the payout instruction as soon as a merchant is approved, so payouts are not delayed when their first invoice is
captured.
## OpenAPI
````yaml POST /v1/payout_instructions
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/payout_instructions:
post:
tags:
- Payout Instructions
summary: Create a payout instruction
description: >-
Creates a new payout instruction for the merchant referenced in the
body.
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
merchant_external_id:
type: string
description: >-
Unique identifier of the merchant the payout instruction
belongs to.
example: merchant_id1
type:
type: string
enum:
- SEPA
beneficiary_name:
type: string
example: ACME Distribution GmbH
iban:
type: string
example: DE00123456781234567890
bic:
type: string
example: DEUTDEDB
required:
- external_id
- merchant_external_id
- type
- beneficiary_name
- iban
- bic
additionalProperties: false
description: SEPA payout instruction.
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
merchant_external_id:
type: string
description: >-
Unique identifier of the merchant the payout instruction
belongs to.
example: merchant_id1
type:
type: string
enum:
- FPS
beneficiary_name:
type: string
example: ACME Distribution Ltd
sort_code:
type: string
pattern: ^\d{6}$
example: '040004'
account_number:
type: string
pattern: ^\d{8}$
example: '12345678'
required:
- external_id
- merchant_external_id
- type
- beneficiary_name
- sort_code
- account_number
additionalProperties: false
description: >-
Faster Payments (FPS) payout instruction for GBP within the
UK.
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
merchant_external_id:
type: string
description: >-
Unique identifier of the merchant the payout instruction
belongs to.
example: merchant_id1
type:
type: string
enum:
- SWIFT
beneficiary_name:
type: string
example: ACME Distribution GmbH
account_number:
type: string
example: DE00123456781234567890
bic:
type: string
example: DEUTDEDBXXX
bank_name:
type: string
example: Deutsche Bank AG
bank_address:
type: string
example: Taunusanlage 12, 60325 Frankfurt am Main, Germany
required:
- external_id
- merchant_external_id
- type
- beneficiary_name
- account_number
- bic
- bank_name
- bank_address
additionalProperties: false
description: SWIFT payout instruction for cross-border payments.
responses:
'201':
description: ''
content:
application/json:
schema:
oneOf:
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
beneficiary_name:
type: string
is_verified:
type: boolean
description: >-
Whether this payout instruction has been verified by
Tilta and is therefore eligible for use in actual
payouts. Newly created or replaced payout instructions
are unverified and must be verified by Tilta
out-of-band before they can be used operationally.
example: false
created_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
updated_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
type:
type: string
enum:
- SEPA
iban:
type: string
example: DE03500105177178979259
bic:
type: string
example: DEUTDEFF
required:
- external_id
- beneficiary_name
- is_verified
- created_at
- updated_at
- type
- iban
- bic
description: A SEPA payout instruction.
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
beneficiary_name:
type: string
is_verified:
type: boolean
description: >-
Whether this payout instruction has been verified by
Tilta and is therefore eligible for use in actual
payouts. Newly created or replaced payout instructions
are unverified and must be verified by Tilta
out-of-band before they can be used operationally.
example: false
created_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
updated_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
type:
type: string
enum:
- FPS
sort_code:
type: string
pattern: ^\d{6}$
account_number:
type: string
pattern: ^\d{8}$
required:
- external_id
- beneficiary_name
- is_verified
- created_at
- updated_at
- type
- sort_code
- account_number
description: A Faster Payments (FPS) payout instruction.
- type: object
properties:
external_id:
type: string
description: Unique identifier of a payout instruction.
example: 8b9f1f4c-2e2a-4a8c-9d51-1b3a3a2c8e9d
beneficiary_name:
type: string
is_verified:
type: boolean
description: >-
Whether this payout instruction has been verified by
Tilta and is therefore eligible for use in actual
payouts. Newly created or replaced payout instructions
are unverified and must be verified by Tilta
out-of-band before they can be used operationally.
example: false
created_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
updated_at:
type: number
description: Timestamp in unix time (seconds).
example: 1582896122
type:
type: string
enum:
- SWIFT
account_number:
type: string
bic:
type: string
example: DEUTDEFF
bank_name:
type: string
bank_address:
type: string
required:
- external_id
- beneficiary_name
- is_verified
- created_at
- updated_at
- type
- account_number
- bic
- bank_name
- bank_address
description: A SWIFT payout instruction.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````