> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload a document for a payment method
> Upload a document for a payment method, e.g. a signed sepa mandate
Required permissions: `payment-method:write`
## OpenAPI
````yaml post /payment-methods/{id}/document
openapi: 3.1.0
info:
title: Fynn API
description: ''
termsOfService: https://www.fynn.eu/tos
contact:
name: Fynn UG (haftungsbeschränkt)
url: https://www.fynn.eu
email: hi@fynn.eu
license:
name: Proprietary
url: https://www.fynn.eu/license
version: 0.0.0
servers:
- url: https://coreapi.io
description: Production
- url: https://preview.coreapi.io
description: Sandbox
security:
- JWT: []
tags: []
paths:
/payment-methods/{id}/document:
parameters: []
post:
tags:
- PaymentMethod
summary: Upload a document for a payment method
description: |-
Upload a document for a payment method, e.g. a signed sepa mandate
Required permissions: `payment-method:write`
operationId: uploadPaymentMethodDocument
parameters:
- name: id
in: path
description: PaymentMethod identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
requestBody:
description: The new PaymentMethod resource
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
text/html:
schema:
$ref: '#/components/schemas/PaymentMethod'
required: true
responses:
'201':
description: PaymentMethod resource created
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod-PaymentMethodRead'
text/html:
schema:
$ref: '#/components/schemas/PaymentMethod-PaymentMethodRead'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- payment-method:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/payment-methods/{id}/document \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"id": "",
"customer": "https:\/\/example.com\/",
"gatewayName": "",
"type": "",
"referenceId": "",
"customerReferenceId": "",
"default": "",
"status": "active",
"source": "api",
"enabled": "",
"isInternal": "",
"name": "",
"data": [
""
],
"creationDate": "",
"expirationDate": "",
"notifications": [
"https:\/\/example.com\/"
],
"webhookResults": [
"https:\/\/example.com\/"
],
"gateway": "",
"internal": "",
"expired": "",
"verified": "",
"gatewayData": [
""
],
"card": {
"brand": "Visa",
"last4": "4242",
"expMonth": "12",
"expYear": "2022",
"cardHolder": "Max Mustermann"
},
"sepaDebit": {
"iban": "DE8937*********3232",
"bic": "COBADEFFXXX",
"mandateReference": "MNDT-2021-123456",
"signingDate": "2021-01-01T00:00:00+00:00"
},
"paypal": {
"email": "max@mustermann.de",
"billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
},
"expirationInDays": "",
"tenantId": ""
}'
components:
schemas:
PaymentMethod:
type: object
description: >-
Represents a payment method attached to a customer, such as a credit
card, SEPA direct debit, PayPal, or bank transfer.
deprecated: false
properties:
id:
readOnly: true
type: string
description: Unique identifier of the payment method
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
customer:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
description: The ID of the customer that owns this payment method
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used to process the payment method
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
description: The type of the payment method
referenceId:
type:
- string
- 'null'
description: The reference ID of the payment method at the payment gateway
customerReferenceId:
type:
- string
- 'null'
description: The customer reference ID at the payment gateway
default:
type: boolean
description: Whether this is the default payment method for the customer
example: true
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
description: The current status of the payment method
source:
default: api
example: api
type: string
enum:
- checkout
- customerfront
- api
- add_link
description: The source where the payment method was created
enabled:
type: boolean
description: Whether the payment method is enabled for use
example: true
isInternal:
type: boolean
description: Whether this is an internal payment method (e.g. wallet)
example: false
name:
type:
- string
- 'null'
description: Display name of the payment method
example: Visa (4242)
data:
type: array
items:
type: string
description: Additional data associated with the payment method
creationDate:
readOnly: true
type: string
format: date-time
description: The date when the payment method was created
example: '2024-01-15T10:30:00+00:00'
expirationDate:
type:
- string
- 'null'
format: date-time
description: The expiration date of the payment method, if applicable
example: '2026-12-31T23:59:59+00:00'
sepaMandate:
readOnly: true
description: >-
The sepa mandate of the payment method, if the gatewayName is
"payment_sepa"
anyOf:
- $ref: '#/components/schemas/SepaMandate'
- type: 'null'
notifications:
type: array
items:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
description: List of notification IDs associated with this payment method
webhookResults:
type: array
items:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
description: List of webhook result IDs triggered by this payment method
gateway:
readOnly: true
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used (read-only alias of gatewayName)
internal:
readOnly: true
type: boolean
description: >-
Whether this is an internal payment method (read-only alias of
isInternal)
expired:
readOnly: true
type: boolean
description: Whether the payment method has expired
verified:
readOnly: true
type: boolean
description: Whether the payment method has been verified
gatewayData:
writeOnly: true
type: array
items:
type: string
description: Gateway-specific data for the payment method (write-only)
card:
readOnly: true
description: The card data of the payment method, if the type is "card"
type: object
properties:
brand:
type: string
example: Visa
description: The brand of the card
last4:
type: string
example: '4242'
description: The last 4 digits of the card
expMonth:
type: integer
example: 12
description: The expiration month of the card
expYear:
type: integer
example: 2022
description: The expiration year of the card
cardHolder:
type: string
example: Max Mustermann
description: The card holder name
sepaDebit:
readOnly: true
description: >-
The sepa mandate data of the payment method, if the type is
"sepa_debit"
type: object
properties:
iban:
type: string
example: DE8937*********3232
description: The iban of the sepa mandate
bic:
type: string
example: COBADEFFXXX
description: The bic of the sepa mandate
mandateReference:
type: string
example: MNDT-2021-123456
description: The mandate reference of the sepa mandate
signingDate:
type: string
example: '2021-01-01T00:00:00+00:00'
description: The signing date of the sepa mandate
paypal:
readOnly: true
description: The paypal data of the payment method, if the type is "paypal"
type: object
properties:
email:
type: string
example: max@mustermann.de
description: The email of the paypal account
billingAgreementId:
type: string
example: I-1J5gqz2eZvKYlo2C2X2X2X2X
description: The billing agreement id of the paypal account
expirationInDays:
readOnly: true
type:
- integer
- 'null'
description: >-
Number of days until the payment method expires. Null if no
expiration.
example: 365
tenantId:
readOnly: true
type: string
description: The tenant ID this payment method belongs to
PaymentMethod-PaymentMethodRead:
type: object
description: Payment method details returned when reading a payment method.
deprecated: false
properties:
id:
readOnly: true
type: string
description: Unique identifier of the payment method
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
customer:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
description: The ID of the customer that owns this payment method
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used to process the payment method
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
description: The type of the payment method
referenceId:
type:
- string
- 'null'
description: The reference ID of the payment method at the payment gateway
default:
type: boolean
description: Whether this is the default payment method for the customer
example: true
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
description: The current status of the payment method
source:
default: api
example: api
type: string
enum:
- checkout
- customerfront
- api
- add_link
description: The source where the payment method was created
enabled:
type: boolean
description: Whether the payment method is enabled for use
example: true
name:
type:
- string
- 'null'
description: Display name of the payment method
example: Visa (4242)
data:
type: array
items:
type: string
description: Additional data associated with the payment method
creationDate:
readOnly: true
type: string
format: date-time
description: The date when the payment method was created
example: '2024-01-15T10:30:00+00:00'
expirationDate:
type:
- string
- 'null'
format: date-time
description: The expiration date of the payment method, if applicable
example: '2026-12-31T23:59:59+00:00'
sepaMandate:
readOnly: true
description: >-
The sepa mandate of the payment method, if the gatewayName is
"payment_sepa"
anyOf:
- $ref: '#/components/schemas/SepaMandate-PaymentMethodRead'
- type: 'null'
card:
readOnly: true
description: The card data of the payment method, if the type is "card"
type: object
properties:
brand:
type: string
example: Visa
description: The brand of the card
last4:
type: string
example: '4242'
description: The last 4 digits of the card
expMonth:
type: integer
example: 12
description: The expiration month of the card
expYear:
type: integer
example: 2022
description: The expiration year of the card
cardHolder:
type: string
example: Max Mustermann
description: The card holder name
sepaDebit:
readOnly: true
description: >-
The sepa mandate data of the payment method, if the type is
"sepa_debit"
type: object
properties:
iban:
type: string
example: DE8937*********3232
description: The iban of the sepa mandate
bic:
type: string
example: COBADEFFXXX
description: The bic of the sepa mandate
mandateReference:
type: string
example: MNDT-2021-123456
description: The mandate reference of the sepa mandate
signingDate:
type: string
example: '2021-01-01T00:00:00+00:00'
description: The signing date of the sepa mandate
paypal:
readOnly: true
description: The paypal data of the payment method, if the type is "paypal"
type: object
properties:
email:
type: string
example: max@mustermann.de
description: The email of the paypal account
billingAgreementId:
type: string
example: I-1J5gqz2eZvKYlo2C2X2X2X2X
description: The billing agreement id of the paypal account
expirationInDays:
readOnly: true
type:
- integer
- 'null'
description: >-
Number of days until the payment method expires. Null if no
expiration.
example: 365
SepaMandate:
type: object
description: >-
A SEPA direct debit mandate authorizing the collection of payments from
a customer's bank account.
deprecated: false
properties:
id:
readOnly: true
example: ad8f0b9c-0b1a-4e1a-8b0a-0b1a4e1a8b0a
type: string
status:
description: |-
The status of the mandate
Possible values:
* `active`: The mandate is active and can be used for payments
* `revoked`: The customer has revoked the mandate or a payment was rejected by the bank. The mandate can not be used for payments anymore
example: active
enum:
- active
- revoked
creditorIdentifier:
readOnly: true
type: string
mandateReference:
description: The reference of the mandate
example: MNDT-2021-0001
type: string
signatureDate:
description: The date of the mandate signature
example: '2021-01-01'
type: string
format: date-time
bankAccount:
$ref: '#/components/schemas/BankAccount'
description: The bank account of the mandate
sequenceType:
description: |-
The sequence type of the mandate
Possible values:
* `FRST`: The sepa mandate is used for the first time for a recurring payment
* `RCUR`: The sepa mandate was already used the first time and is now used for recurring payments
* `FNAL`: The sepa mandate is used for the last time for a recurring payment
* `OOFF`: The sepa mandate is only allowed to be used for one payment
example: FRST
enum:
- FRST
- RCUR
- FNAL
- OOFF
sepaType:
description: |-
The type of the mandate
Possible values:
* `CORE`: The core scheme is used for payments between consumers and companies
* `B2B`: The B2B scheme is used for payments between companies. No refund is possible
* `COR1`: The COR1 scheme is used for payments between consumers and companies. The payment is processed faster than with the core scheme
example: core
enum:
- CORE
- B2B
- COR1
createdAt:
readOnly: true
description: The date of the creation
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
customer:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
firstSepaDebit:
readOnly: true
type: boolean
tenantId:
readOnly: true
type: string
SepaMandate-PaymentMethodRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f0b9c-0b1a-4e1a-8b0a-0b1a4e1a8b0a
type: string
status:
description: |-
The status of the mandate
Possible values:
* `active`: The mandate is active and can be used for payments
* `revoked`: The customer has revoked the mandate or a payment was rejected by the bank. The mandate can not be used for payments anymore
example: active
enum:
- active
- revoked
creditorIdentifier:
readOnly: true
type: string
mandateReference:
description: The reference of the mandate
example: MNDT-2021-0001
type: string
bankAccount:
$ref: '#/components/schemas/BankAccount-PaymentMethodRead'
description: The bank account of the mandate
sequenceType:
description: |-
The sequence type of the mandate
Possible values:
* `FRST`: The sepa mandate is used for the first time for a recurring payment
* `RCUR`: The sepa mandate was already used the first time and is now used for recurring payments
* `FNAL`: The sepa mandate is used for the last time for a recurring payment
* `OOFF`: The sepa mandate is only allowed to be used for one payment
example: FRST
enum:
- FRST
- RCUR
- FNAL
- OOFF
sepaType:
description: |-
The type of the mandate
Possible values:
* `CORE`: The core scheme is used for payments between consumers and companies
* `B2B`: The B2B scheme is used for payments between companies. No refund is possible
* `COR1`: The COR1 scheme is used for payments between consumers and companies. The payment is processed faster than with the core scheme
example: core
enum:
- CORE
- B2B
- COR1
BankAccount:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f0b9c-4b1e-4e0e-8b9c-4b1e4e0e8b9c
type: string
description: Unique identifier of the bank account
alias:
example: Girokonto
type:
- string
- 'null'
iban:
example: DE12500105170648489890
type: string
description: The IBAN of the bank account
bic:
example: PBNKDEFFXXX
type: string
description: The BIC/SWIFT code of the bank
accountHolder:
example: Max Mustermann
type: string
description: The name of the account holder
bankName:
example: Commerzbank
type: string
description: The name of the bank
source:
description: The source of the bank account. Can be any string.
example: import
type:
- string
- 'null'
asValue:
$ref: '#/components/schemas/BankAccountValue'
readOnly: true
tenantId:
readOnly: true
type: string
BankAccount-PaymentMethodRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f0b9c-4b1e-4e0e-8b9c-4b1e4e0e8b9c
type: string
description: Unique identifier of the bank account
iban:
example: DE12500105170648489890
type: string
description: The IBAN of the bank account
bic:
example: PBNKDEFFXXX
type: string
description: The BIC/SWIFT code of the bank
accountHolder:
example: Max Mustermann
type: string
description: The name of the account holder
bankName:
example: Commerzbank
type: string
description: The name of the bank
BankAccountValue:
type: object
description: ''
deprecated: false
properties:
iban:
type: string
description: The IBAN of the bank account
example: DE89370400440532013000
bic:
type: string
description: The BIC/SWIFT code of the bank
example: COBADEFFXXX
accountHolder:
example: Max Mustermann
type: string
description: The name of the account holder
bankName:
example: Commerzbank
type: string
description: The name of the bank
securitySchemes:
JWT:
type: http
scheme: bearer
````