Skip to main content

Release 2026-06-01

This release introduces payment-method-specific statement descriptors.

statement_descriptor is removed from checkout and payment creation requests and replaced with method-specific fields for cards and SEPA Direct Debit.

Statement descriptor per payment method​

Field statement_descriptor is now payment-method-specific.

This allows each payment method to use its own capabilities, length, and supported characters instead of being limited by the most restrictive method.

For example, if the same field were reused for cards and SEPA Direct Debit, SEPA Direct Debit values (up to 140 characters) would be limited by the cards constraint (18 characters).

warning

Breaking change: statement_descriptor is no longer supported in checkout and payment creation request payloads.

What changes​

  • Checkout creation POST api.getpaid.io/v2/checkouts
    • Request
      • Breaking: statement_descriptor field is removed.
      • New payment_methods.options.cards.dynamic_descriptor field for cards.
      • New payment_methods.options.sepa_direct_debit.remittance_info field for SEPA Direct Debit.
    • Response:
      • Breaking: statement_descriptor field is removed and it is no longer returned on checkout creation.
  • Checkout details GET api.getpaid.io/v2/checkouts/{checkout_id}
    • Breaking: statement_descriptor is no longer returned.
    • New payment_methods.options block is returned if sent in the creation request.
  • Payment creation POST api.getpaid.io/v2/payments
    • Request:
      • Breaking: statement_descriptor field is removed.
      • New method block for requests.
      • New method.dynamic_descriptor field for cards when method.type is card.
      • New method.remittance_info field for SEPA Direct Debit when method.type is sepa_direct_debit.
    • Response:
      • statement_descriptor maximum length is now 140.
  • Payment details GET api.getpaid.io/v2/payments/{payment_id}
    • statement_descriptor maximum length is now 140.

Migration checklist​

  1. Remove statement_descriptor from checkout and payment creation request payloads.
  2. Stop reading statement_descriptor in checkout creation responses.
  3. If needed, start reading the payment_methods.options block in the checkout details response.
  4. Set method-specific fields in request payloads:
    1. Checkouts: payment_methods.options.cards.dynamic_descriptor and/or payment_methods.options.sepa_direct_debit.remittance_info.
    2. Payments: method.dynamic_descriptor or method.remittance_info depending on the method.type.
  5. Update request validation rules:
    1. Cards dynamic_descriptor: ^[a-zA-Z0-9 *\._-]{1,18}$.
    2. SEPA Direct Debit remittance_info: maximum of 140 characters.
  6. Keep reading statement_descriptor in payment creation and payment detail responses and expect a maximum of 140 characters.

Detailed changes​

Checkout creation​

Changes in the checkout creation request and response (POST api.getpaid.io/v2/checkouts endpoint).

Before:

Before change - POST api.getpaid.io/v2/checkouts
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // Removed. Use instead:
  // "payment_methods.options.cards.dynamic_descriptor" for cards
  // "payment_methods.options.sepa_direct_debit.remittance_info" for SDDs
  "statement_descriptor": "TITAN*202510-0232",
  [...]
}
Before change - 200 OK - POST api.getpaid.io/v2/checkouts
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // Removed. The buyer-visible statement descriptor is calculated
  // once the payment method is known, in the payment details
  "statement_descriptor": "GPD*TITAN*202510-0232",
  [...]
}

After:

After change - POST api.getpaid.io/v2/checkouts
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  "payment_methods": {
    // "options" is available for any payment methods strategy
    // selection: "explicit", "default", etc.
    "type": "default",
    [...],
    "options": {
      "cards": {
        // Value will be prefixed with "GPD*" in the payment statement descriptor
        "dynamic_descriptor": "TITAN*202510-0232"
      },
      "sepa_direct_debit": {
        "remittance_info": "Titan Auto Parts Ord. #0232 Inv. #202500632"
      }
    }
  },
  [...]
}

Checkout details​

statement_descriptor field is removed and replaced by the payment_methods.options block in checkout details (GET api.getpaid.io/v2/checkouts/{checkout_id} endpoint).

Before:

Before change - 200 OK - GET api.getpaid.io/v2/checkouts/{checkout_id}
{
  [...],
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // Removed. The buyer-visible statement descriptor is calculated
  // once the payment method is known, in the payment details
  "statement_descriptor": "GPD*TITAN*202510-0232",
  [...]
}

After:

After change - 200 OK - GET api.getpaid.io/v2/checkouts/{checkout_id}
{
  [...],
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  "payment_methods": {
    "type": "default",
    [...],
    "options": {
      "cards": {
        "dynamic_descriptor": "TITAN*202510-0232"
      },
      "sepa_direct_debit": {
        "remittance_info": "Titan Auto Parts Ord. #0232 Inv. #202500632"
      }
    }
  },
  [...]
}

Payment creation​

Changes in the payment creation request (POST api.getpaid.io/v2/payments endpoint).

Before:

Before change - POST api.getpaid.io/v2/payments
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // Removed. Use instead:
  // "method.dynamic_descriptor" for cards
  // "method.remittance_info" for SEPA Direct Debit
  "statement_descriptor": "TITAN*202510-0232",
  [...]
}

After (cards):

After change - Cards - POST api.getpaid.io/v2/payments
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  "method": {
    "type": "card",
    "dynamic_descriptor": "TITAN*202510-0232"
  },
  [...]
}

After (SEPA Direct Debit):

After change - SEPA Direct Debit - POST api.getpaid.io/v2/payments
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  "method": {
    "type": "sepa_direct_debit",
    "remittance_info": "Titan Auto Parts Ord. #0232 Inv. #202500632"
  },
  [...]
}

Payment creation response and details​

statement_descriptor is computed and returned as the buyer sees it in their bank account in both the payment creation response (POST api.getpaid.io/v2/payments endpoint) and payment details (GET api.getpaid.io/v2/payments/{payment_id} endpoint).

Cards
{
  [...],
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // For cards, it is the "method.dynamic_descriptor"
  // preceded by the prefix "GPD*"
  "statement_descriptor": "GPD*TITAN*202510-0232",
  [...]
}
SEPA Direct Debit
{
  "reference": "ORD-202510-0232",
  "amount": 10000,
  "currency": "EUR",
  "description": "Order #202510-0232",
  // For SEPA Direct Debit, it is the "method.remittance_info"
  "statement_descriptor": "Titan Auto Parts Ord. #0232 Inv. #202500632",
  [...]
}