POST
/
payment-methods
curl -X POST \
 /payment-methods \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --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
        }
    }
}'

{
  "status": "action_required",
  "actionRequired": {
    "action": "client_site_action",
    "details": {
      "clientSecret": "test_1234567890",
      "publishableKey": "pk_test_1234567890",
      "accountId": "acct_1234567890"
    }
  },
  "failReason": "<string>",
  "paymentMethod": {
    "id": "<string>",
    "customer": "https://example.com/",
    "gatewayName": "wallet",
    "type": "sepa_debit",
    "referenceId": "<string>",
    "default": true,
    "status": "active",
    "source": "api",
    "enabled": true,
    "name": "<string>",
    "data": [
      "<string>"
    ],
    "creationDate": "2023-11-07T05:31:56Z",
    "expirationDate": "2023-11-07T05:31:56Z",
    "sepaMandate": {
      "id": "ad8f0b9c-0b1a-4e1a-8b0a-0b1a4e1a8b0a",
      "status": "active",
      "creditorIdentifier": "<string>",
      "mandateReference": "MNDT-2021-0001",
      "bankAccount": {
        "id": "ad8f0b9c-4b1e-4e0e-8b9c-4b1e4e0e8b9c",
        "iban": "DE12500105170648489890",
        "bic": "PBNKDEFFXXX",
        "accountHolder": "Max Mustermann",
        "bankName": "Commerzbank"
      },
      "sequenceType": "FRST",
      "sepaType": "core"
    },
    "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": 123
  }
}

Authorizations

​
Authorization
string
header
required

Value for the Authorization header parameter.

Body

The new PaymentMethod resource
​
gateway
enum<string>
required

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")
Available options:
wallet,
sepa_debit,
stripe,
fake_provider,
paypal,
bank_transfer,
go_cardless,
testing
Example:

"stripe"

​
type
enum<string>
required

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
Available options:
sepa_debit,
card,
paypal,
bank_transfer,
wallet,
fake_provider
Example:

"card"

​
customerId
string | null

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"

​
isDefault
boolean
default:true

Determines if this payment method should be used as default payment method for the customer

Example:

true

​
futureUsageAllowed
boolean
default:true

Determines if this payment method is allowed to be used for future payments. Otherwise the payment method is only available for this payment.

Example:

true

​
stripe
object | null

Required when gateway is "stripe". Holds all necessary data for the payment gateway to create the payment method.

​
sepaMandate
object | null

Required when gateway is "sepa_debit". Holds all necessary data for the payment gateway to create the payment method.

​
goCardless
object | null

Optional for gateway "go_cardless". It is only required when you want to migrate, or assign an existing GoCardless customer or mandate to fynn.

​
redirectUrl
string | null

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"

Response

201
application/json
PaymentMethod resource created
​
status
enum<string>

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
Available options:
action_required,
success,
failed
​
actionRequired
object | null

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
Example:
{
  "action": "client_site_action",
  "details": {
    "clientSecret": "test_1234567890",
    "publishableKey": "pk_test_1234567890",
    "accountId": "acct_1234567890"
  }
}
​
failReason
string | null

The fail reason if status is failed

​
paymentMethod
object | null

The created payment method, if status is success