> ## 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.
# Create payment method
> Create a customer's payment method
Required permissions: `payment-method:add`
## OpenAPI
````yaml post /payment-methods
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:
parameters: []
post:
tags:
- PaymentMethod
summary: Create payment method
description: |-
Create a customer's payment method
Required permissions: `payment-method:add`
operationId: createPaymentMethod
parameters: []
requestBody:
description: The new PaymentMethod resource
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod.SetupPaymentMethod'
examples:
stripeCreditCardInit:
summary: Create stripe setup intent
description: >-
The stripe setup intent clientSecret is required to add a
stripe credit card payment method. The clientSecret is
required to collect credit card data with stripe.js elements.
value:
gateway: stripe
type: card
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
stripe:
paymentMethodId: null
customerId: null
stripeCreditCard:
summary: Add stripe credit card
description: >-
The stripe credit card needs to be created on the client side
with stripe.js. To obtain the required clientSecret, see
"Create stripe setup intent token".
value:
gateway: stripe
type: card
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
stripe:
paymentMethodId: pm_1J4X2n2eZvKYlo2C2Q2Q2Q2Q2
customerId: cus_J4X2n2eZvKYlo2C2Q2Q2Q2Q2
paypal:
summary: Add PayPal
description: >-
When adding a paypal payment method, the customer will be
redirected to paypal to login and confirm the billing
agreement. After that, the customer will be redirected back to
the successUrl.
value:
gateway: paypal
type: paypal
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
gocardless:
summary: Add new GoCardless sepa mandate
description: >-
When adding a gocardless payment method, the customer will be
redirected to gocardless to login and create a sepa debit
mandate. After that, the customer will be redirected back to
the successUrl.
value:
gateway: go_cardless
type: sepa_debit
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
gocardlessExisting:
summary: Add existing GoCardless sepa mandate
description: >-
To add an existing gocardless mandate (e.g. when you're
migrating from another system), you need to provide the
mandateId and customerId. No redirect will be performed.
value:
gateway: go_cardless
type: sepa_debit
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
goCardless:
mandateId: MD0000
customerId: CU0000
inhouseSepa:
summary: Add a fynn sepa mandate
description: >-
The sepa mandate allows to perform sepa payments with the
integrated sepa payment gateway. See Generate
sepa xml file for more information.
value:
gateway: sepa_debit
type: sepa_debit
customerId: ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f
isDefault: true
futureUsageAllowed: true
sepaMandate:
iban: DE89370400440532013000
bic: COBADEFFXXX
accountHolder: Max Mustermann
signingDate: '2021-01-01'
type: CORE
sequence: FRST
text/html:
schema:
$ref: '#/components/schemas/PaymentMethod.SetupPaymentMethod'
examples:
stripe_card:
summary: Create Stripe card payment method
value:
gateway: stripe
type: card
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: true
futureUsageAllowed: true
stripe:
paymentMethodId: null
redirectUrl: https://example.com/checkout/confirm
sepa_debit:
summary: Create SEPA direct debit payment method
value:
gateway: sepa_debit
type: sepa_debit
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: true
futureUsageAllowed: true
sepaMandate:
iban: DE89370400440532013000
bic: COBADEFFXXX
accountHolder: Max Mustermann
signingDate: '2024-01-15'
type: CORE
sequence: FRST
paypal:
summary: Create PayPal payment method
value:
gateway: paypal
type: paypal
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: false
futureUsageAllowed: true
redirectUrl: https://example.com/checkout/confirm
go_cardless:
summary: Create GoCardless SEPA payment method
value:
gateway: go_cardless
type: sepa_debit
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: true
futureUsageAllowed: true
goCardless:
customerId: CU123456789
mandateId: MD123456789
bank_transfer:
summary: Create bank transfer payment method
value:
gateway: bank_transfer
type: bank_transfer
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: true
futureUsageAllowed: true
wallet:
summary: Create wallet (credit balance) payment method
value:
gateway: wallet
type: wallet
customerId: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
isDefault: false
futureUsageAllowed: true
required: true
responses:
'201':
description: PaymentMethod resource created
content:
application/json:
schema:
$ref: >-
#/components/schemas/PaymentMethod.PaymentMethodResultOutput-SetupPaymentMethodResult
example:
status: action_required
actionRequired:
action: client_site_action
redirectUrl: null
details:
clientSecret: seti_1N5J2n2eZvKYlo2C_secret_abc123
publishableKey: pk_test_1234567890
accountId: acct_1234567890
failReason: null
paymentMethod: null
text/html:
schema:
$ref: >-
#/components/schemas/PaymentMethod.PaymentMethodResultOutput-SetupPaymentMethodResult
example:
status: action_required
actionRequired:
action: client_site_action
redirectUrl: null
details:
clientSecret: seti_1N5J2n2eZvKYlo2C_secret_abc123
publishableKey: pk_test_1234567890
accountId: acct_1234567890
failReason: null
paymentMethod: null
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- payment-method:add
x-codeSamples:
- lang: bash
label: Create stripe setup intent
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Create stripe setup intent",
"description": "The stripe setup intent clientSecret is required to add a stripe credit card payment method. The clientSecret is required to collect credit card data with stripe.js elements.",
"value": {
"gateway": "stripe",
"type": "card",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true,
"stripe": {
"paymentMethodId": null,
"customerId": null
}
}
}'
- lang: bash
label: Add stripe credit card
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Add stripe credit card",
"description": "The stripe credit card needs to be created on the client side with stripe.js. To obtain the required clientSecret, see \"Create stripe setup intent token\".",
"value": {
"gateway": "stripe",
"type": "card",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true,
"stripe": {
"paymentMethodId": "pm_1J4X2n2eZvKYlo2C2Q2Q2Q2Q2",
"customerId": "cus_J4X2n2eZvKYlo2C2Q2Q2Q2Q2"
}
}
}'
- lang: bash
label: Add PayPal
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Add PayPal",
"description": "When adding a paypal payment method, the customer will be redirected to paypal to login and confirm the billing agreement. After that, the customer will be redirected back to the successUrl.",
"value": {
"gateway": "paypal",
"type": "paypal",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true
}
}'
- lang: bash
label: Add new GoCardless sepa mandate
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Add new GoCardless sepa mandate",
"description": "When adding a gocardless payment method, the customer will be redirected to gocardless to login and create a sepa debit mandate. After that, the customer will be redirected back to the successUrl.",
"value": {
"gateway": "go_cardless",
"type": "sepa_debit",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true
}
}'
- lang: bash
label: Add existing GoCardless sepa mandate
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Add existing GoCardless sepa mandate",
"description": "To add an existing gocardless mandate (e.g. when you're migrating from another system), you need to provide the mandateId and customerId. No redirect will be performed.",
"value": {
"gateway": "go_cardless",
"type": "sepa_debit",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true,
"goCardless": {
"mandateId": "MD0000",
"customerId": "CU0000"
}
}
}'
- lang: bash
label: Add a fynn sepa mandate
source: |
curl -X POST \
/payment-methods \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"summary": "Add a fynn sepa mandate",
"description": "The sepa mandate allows to perform sepa payments with the integrated sepa payment gateway. See Generate sepa xml file<\/a> for more information.",
"value": {
"gateway": "sepa_debit",
"type": "sepa_debit",
"customerId": "ad8f7a8d-8f7a-8d8f-7a8d8f7a8d8f",
"isDefault": true,
"futureUsageAllowed": true,
"sepaMandate": {
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX",
"accountHolder": "Max Mustermann",
"signingDate": "2021-01-01",
"type": "CORE",
"sequence": "FRST"
}
}
}'
components:
schemas:
PaymentMethod.SetupPaymentMethod:
type: object
description: Request body for creating a new payment method for a customer.
deprecated: false
properties:
isMigration:
readOnly: true
type: boolean
gateway:
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: |-
The payment gateway to use to process the given payment method type
Possible values:
* `paypal`: PayPal (supports "paypal")
* `stripe`: Stripe (supports "card")
* `testing`: Testing (supports all)
* `go_cardless`: GoCardless (supports "sepa_debit")
* `bank_transfer`: Bank Transfer (supports "bank_transfer")
* `sepa_debit`: SEPA Credit and Debit with xml file (supports "sepa_debit")
* `wallet`: Credit Balance from Wallet (supports "wallet")
example: stripe
type:
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
description: |-
The payment method type to use for this payment method
Possible values:
* `sepa_debit`: SEPA Debit
* `card`: Credit Card
* `paypal`: PayPal
* `bank_transfer`: Bank Transfer
* `wallet`: Wallet
example: card
customerId:
description: >-
The customer that owns this payment method. If not provided, the
customer will be determined by the authenticated user.
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
type:
- string
- 'null'
isDefault:
description: >-
Determines if this payment method should be used as default payment
method for the customer
default: true
example: true
type: boolean
futureUsageAllowed:
description: >-
Determines if this payment method is allowed to be used for future
payments. Otherwise the payment method is only available for this
payment.
default: true
example: true
type: boolean
stripe:
description: >-
Required when gateway is "stripe". Holds all necessary data for the
payment gateway to create the payment method.
anyOf:
- $ref: '#/components/schemas/CreateStripeResource'
- type: 'null'
sepaMandate:
description: >-
Required when gateway is "sepa_debit". Holds all necessary data for
the payment gateway to create the payment method.
anyOf:
- $ref: '#/components/schemas/CreateSepaMandateResource'
- type: 'null'
goCardless:
description: >-
Optional for gateway "go_cardless". It is only required when you
want to migrate, or assign an existing GoCardless customer or
mandate to fynn.
anyOf:
- $ref: '#/components/schemas/CreateGoCardlessResource'
- type: 'null'
redirectUrl:
description: >-
The redirect url to redirect the customer to after the payment
method was created. This is only required, when you create a payment
method with your own flow, independent from provided
Hosted-Checkout, Hosted-Customerfront or Fynn.JS. Otherwise this has
no effect.
example: https://example.com/checkout/confirm
type:
- string
- 'null'
migration:
readOnly: true
type: boolean
required:
- gateway
- type
PaymentMethod.PaymentMethodResultOutput-SetupPaymentMethodResult:
type: object
description: >-
The result of creating a payment method. Contains the status, any
required actions, and the created payment method.
deprecated: false
properties:
status:
enum:
- action_required
- success
- failed
description: |-
Possible values:
* `action_required`: The payment method requires an action to be taken by the customer
* `success`: The payment method was successfully created
* `failed`: The payment method could not be created
actionRequired:
description: >-
The action required if the payment method requires an action to be
taken by the customer
* redirect_to_gateway: The customer needs to be redirected to the
payment gateway
* client_site_action: The customer needs to take an action on the
client site
type: object
nullable: true
properties:
action:
type: string
enum:
- redirect_to_gateway
- client_site_action
redirectUrl:
type: string
nullable: true
example: https://example.com/redirect
description: >-
The URL to redirect the customer to, if the action is
`redirect_to_gateway`
details:
type: object
nullable: true
description: >-
The details of the action required, if the action is
`client_site_action`
properties:
clientSecret:
type: string
nullable: true
example: test_1234567890
description: >-
The client secret to use for stripe.js, if the payment
gateway is `stripe` and the type is `card`
publishableKey:
type: string
nullable: true
example: pk_test_1234567890
description: >-
The publishable key to use for stripe.js, if the payment
gateway is `stripe` and the type is `card`
accountId:
type: string
nullable: true
example: acct_1234567890
description: >-
The account id to use for stripe.js, if the payment gateway
is `stripe` and the type is `card`
example:
action: client_site_action
details:
clientSecret: test_1234567890
publishableKey: pk_test_1234567890
accountId: acct_1234567890
failReason:
description: The fail reason if status is `failed`
type: string
nullable: true
paymentMethod:
description: The created payment method, if status is `success`
anyOf:
- $ref: '#/components/schemas/PaymentMethod-SetupPaymentMethodResult'
- type: 'null'
CreateStripeResource:
type: object
description: >-
Stripe-specific data required when creating a payment method via the
Stripe gateway.
deprecated: false
properties:
paymentMethodId:
pattern: ^(.*(^(card|pm)_.*$).*)$
description: >-
The Stripe payment method id, which was collected by Fynn.JS or
Stripe.JS
If `null` is provided, you get a `action_required` response, with
the `{SETUP_INTENT_CLIENT_SECRET}` to perform the authorization in
stripe.js, see Confirm
card setup.
example: pm_1J5J2n2eZvKYlo2CJY2n2eZvKYlo2C
type:
- string
- 'null'
customerId:
pattern: ^(cus_.*)$
description: >-
The Stripe customer id, which references the Stripe customer.
If none is provided, the stripe customer id will be used, which was
created automatically by Fynn, during fetching the stripe setup
intent secret.
example: cus_J5J2n2eZvKYlo2CJY2n2eZvKYlo2C
type:
- string
- 'null'
CreateSepaMandateResource:
type: object
description: >-
SEPA mandate data required when creating a payment method via the SEPA
direct debit gateway.
deprecated: false
properties:
mandateReference:
maxLength: 35
description: >-
The mandate reference will be generated automatically, if none is
provided. You can set it when migrating from another payment
provider.
example: MNDT-123456789
type:
- string
- 'null'
iban:
description: The customer's IBAN
externalDocs:
url: https://schema.org/identifier
example: DE89370400440532013000
type:
- string
- 'null'
bic:
description: The customer's BIC
externalDocs:
url: https://schema.org/identifier
example: COBADEFFXXX
type:
- string
- 'null'
accountHolder:
description: The bank account holder's name
example: Max Mustermann
type:
- string
- 'null'
signingDate:
description: >-
The SEPA mandate signing date. If none is provided, the current date
will be used.
externalDocs:
url: https://schema.org/Date
default: today
example: '2021-01-01'
type:
- string
- 'null'
type:
enum:
- CORE
- B2B
- COR1
description: >-
The SEPA mandate type. If none is provided, the default type "CORE"
will be used.
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
default: CORE
example: CORE
sequence:
enum:
- FRST
- RCUR
- FNAL
- OOFF
description: >-
The SEPA mandate sequence. If none is provided, the default sequence
"FRST" will be used.
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
default: FRST
example: FRST
required:
- iban
- bic
- accountHolder
CreateGoCardlessResource:
type: object
description: >-
GoCardless-specific data for migrating or assigning an existing
GoCardless customer or mandate to Fynn.
deprecated: false
properties:
customerId:
pattern: ^(CU.*)$
description: >-
The GoCardless customer id, which references the GoCardless
customer. If none is provided, the GoCardless mandate flow will be
started.
example: CU123456789
type:
- string
- 'null'
mandateId:
pattern: ^(MD.*)$
description: >-
The GoCardless mandate id, which references the GoCardless mandate.
If none is provided, the GoCardless mandate flow will be started.
example: MD123456789
type:
- string
- 'null'
PaymentMethod-SetupPaymentMethodResult:
type: object
description: Payment method details returned after creating a payment method.
deprecated: false
properties:
id:
readOnly: true
type: string
customer:
type: string
format: uuid
example: ad8f3b9e-1b1a-4b9a-9b9a-9b9a9b9a9b9a
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
referenceId:
type:
- string
- 'null'
default:
type: boolean
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
source:
default: api
example: api
type: string
enum:
- checkout
- customerfront
- api
- add_link
enabled:
type: boolean
name:
type:
- string
- 'null'
data:
type: array
items:
type: string
creationDate:
readOnly: true
type: string
format: date-time
expirationDate:
type:
- string
- 'null'
format: date-time
sepaMandate:
readOnly: true
description: >-
The sepa mandate of the payment method, if the gatewayName is
"payment_sepa"
anyOf:
- $ref: '#/components/schemas/SepaMandate-SetupPaymentMethodResult'
- 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'
SepaMandate-SetupPaymentMethodResult:
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-SetupPaymentMethodResult'
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-SetupPaymentMethodResult:
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
securitySchemes:
JWT:
type: http
scheme: bearer
````