Retrieving payment methods

To show available payment methods in your UI, or to determine which method to use when creating a checkout session or requesting a quote, you can retrieve the list from the API.

Payment method availability depends on your partner configuration and the user’s country.

Prerequisites

You need a valid JWT token. See Quick start: step 1 for how to authenticate.

Endpoint

GET /api/v1/buy/payment-methods/{type}

The type path parameter controls which payment methods are returned:

• all: returns every payment method available per country. Use this if you want to offer the full range of options.
• preferred: returns only the payment methods relevant to each country. Use this if you know the user’s country and want to show only what makes sense for them (e.g. iDEAL for Dutch users, Bancontact for Belgian users).

Example

curl https://api-sandbox.btcdirect.eu/api/v1/buy/payment-methods/preferred \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

The response contains a flat list of payment methods and a separate list of countries with their available method codes.

{
  "paymentMethods": [
    {
      "code": "creditCard",
      "label": "Credit Card",
      "psp": "adyen",
      "limit": 1000,
      "fee": {
        "fixed": 0.5,
        "percentage": 3
      },
      "expirationPeriod": 300,
      "openInNewTab": false,
      "context": []
    },
    {
      "code": "bankTransfer",
      "label": "Bank Transfer",
      "psp": "bunq",
      "limit": 10000,
      "fee": {
        "fixed": 0,
        "percentage": 0
      },
      "expirationPeriod": 300,
      "openInNewTab": false,
      "context": []
    }
  ],
  "countries": {
    "nl": ["iDeal", "creditCard", "bankTransfer"],
    "be": ["bancontact", "creditCard", "bankTransfer"],
    "fr": ["creditCard", "bankTransfer"]
  }
}

Use the code value (e.g. iDeal, creditCard) when creating a checkout session or requesting a quote. Codes are case-sensitive.

The countries object maps lowercase country codes to the payment methods available in that country. Use this to filter the list based on the user’s location.

For a static overview of all payment method codes, see Payment methods.

See the endpoint specification for the full response schema.