Payment instructions — FiscalRail documentation

Payment Instructions are mutable account configuration. The first supported type, bank_transfer, stores a beneficiary, IBAN, and optional BIC. The label is internal and is not printed on invoices.

IBANs are normalized to uppercase without whitespace and validated against the registered country length and check digits.

Add instruction IDs to the account's ordered default_payment_instructions array, or select them per invoice with payment_terms.options. The first selected instruction is preferred. Issuance copies the resolved details and invoice-number reference into the immutable Invoice object, so changing or deleting the source later cannot rewrite an issued invoice.

Defaults apply only to ordinary invoices with a positive payable amount. FiscalRail leaves payment terms empty on zero-value invoices, negative invoices, and credit notes.

An instruction configured as an account default cannot be deleted. Remove it from default_payment_instructions first. An instruction already used by an invoice may be changed or deleted because the invoice retains its snapshot.

The Payment Instruction object

Properties

id string

Opaque identifier for a payment instruction.

object string

String identifying this as a Payment Instruction object. Always payment_instruction.

live boolean

True when the object belongs to the live environment; false for test data.

account string

Account that owns the instruction.

label string

Internal label used to distinguish reusable instructions. It is not copied onto invoices.

type string

Discriminator for the type-specific instruction object. Always bank_transfer.

bank_transfer object

Bank account to show when this instruction is selected.

Show child propertiesHide child properties

beneficiary string

Name of the bank-account beneficiary shown to the payer.

iban string

Valid normalized IBAN without spaces.

bic string or null

Optional BIC or SWIFT code, normalized to uppercase.

created_at string

When the payment instruction was created.

updated_at string

When the mutable instruction was last updated.

Payment Instruction object

{
  "id": "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
  "object": "payment_instruction",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "label": "Main EUR account",
  "type": "bank_transfer",
  "bank_transfer": {
    "beneficiary": "Example supplier",
    "iban": "ES9121000418450200051332",
    "bic": "CAIXESBBXXX"
  },
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Create a payment instruction

POST/v1/payment-instructions

Creates a reusable bank-transfer instruction. It is not added to account defaults automatically.

Request body

label string required

Internal label used to distinguish the instruction.

type string required

Creates a bank-transfer instruction. Always bank_transfer.

bank_transfer object required

Bank details used when rendering future invoice payment options.

Show child propertiesHide child properties

beneficiary string required

Name of the bank-account beneficiary.

iban string required

IBAN. FiscalRail removes whitespace, uppercases it, and validates its registered country length and check digits.

bic string or null

Optional BIC or SWIFT code. FiscalRail removes whitespace and uppercases it.

Responses

201 A Payment Instruction object. JSON

Example request


  
  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

payment_instruction = client.payment_instructions.create(
    label="Primary EUR account",
    type="bank_transfer",
    bank_transfer={
        "beneficiary": "Example supplier",
        "iban": "ES9121000418450200051332",
        "bic": "CAIXESBBXXX",
    },
)

  
  curl --request POST \
  'https://api.fiscalrail.com/v1/payment-instructions' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "label": "Primary EUR account",
  "type": "bank_transfer",
  "bank_transfer": {
    "beneficiary": "Example supplier",
    "iban": "ES9121000418450200051332",
    "bic": "CAIXESBBXXX"
  }
}'

Example response — 201

{
  "id": "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
  "object": "payment_instruction",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "label": "Main EUR account",
  "type": "bank_transfer",
  "bank_transfer": {
    "beneficiary": "Example supplier",
    "iban": "ES9121000418450200051332",
    "bic": "CAIXESBBXXX"
  },
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Retrieve a payment instruction

GET/v1/payment-instructions/{id}

Path parameters

id string required

The opaque ID of the payment instruction.

Responses

200 A Payment Instruction object. JSON

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

payment_instruction = client.payment_instructions.retrieve(
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
)

  curl --request GET \
  'https://api.fiscalrail.com/v1/payment-instructions/pay_ins_14Vxtqm9KHu4rP3eZyN8gT' \
  --header "Authorization: Bearer ak_test_..."

Example response — 200

{
  "id": "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
  "object": "payment_instruction",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "label": "Main EUR account",
  "type": "bank_transfer",
  "bank_transfer": {
    "beneficiary": "Example supplier",
    "iban": "ES9121000418450200051332",
    "bic": "CAIXESBBXXX"
  },
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Update a payment instruction

PATCH/v1/payment-instructions/{id}

Updates future uses of the instruction. Issued invoice snapshots are unaffected.

Path parameters

id string required

The opaque ID of the payment instruction.

Request body

label string

New internal label.

bank_transfer object

Bank-detail fields to change for future invoice payment options.

Show child propertiesHide child properties

beneficiary string

New beneficiary name.

iban string

New IBAN to use for future invoices. Its registered country length and check digits are validated.

bic string or null

New BIC, or null to clear it.

Responses

200 The updated Payment Instruction object. JSON

Example request


  
  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

payment_instruction = client.payment_instructions.update(
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
    label="New primary EUR account",
    bank_transfer={
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
    },
)

  
  curl --request PATCH \
  'https://api.fiscalrail.com/v1/payment-instructions/pay_ins_14Vxtqm9KHu4rP3eZyN8gT' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "label": "New primary EUR account",
  "bank_transfer": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  }
}'

Example response — 200

{
  "id": "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
  "object": "payment_instruction",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "label": "Main EUR account",
  "type": "bank_transfer",
  "bank_transfer": {
    "beneficiary": "Example supplier",
    "iban": "ES9121000418450200051332",
    "bic": "CAIXESBBXXX"
  },
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Delete a payment instruction

DELETE/v1/payment-instructions/{id}

Deletes an instruction that is not configured as an account default. Issued invoices retain their snapshots.

Path parameters

id string required

The opaque ID of the payment instruction.

Responses

204 The payment instruction was deleted. The response has no body.

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

client.payment_instructions.delete(
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
)

  curl --request DELETE \
  'https://api.fiscalrail.com/v1/payment-instructions/pay_ins_14Vxtqm9KHu4rP3eZyN8gT' \
  --header "Authorization: Bearer ak_test_..."

List payment instructions

GET/v1/payment-instructions

Returns reusable payment instructions in reverse chronological ID order.

Query parameters

limit integer

Maximum number of resources to return. Defaults to 25.

starting_after string

Return payment instructions older than this instruction ID. Cannot be combined with ending_before.

ending_before string

Return payment instructions newer than this instruction ID. Cannot be combined with starting_after.

Responses

200 A list of Payment Instruction objects. JSON

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

payment_instructions = client.payment_instructions.list(
    limit=25,
)

  curl --request GET \
  'https://api.fiscalrail.com/v1/payment-instructions?limit=25' \
  --header "Authorization: Bearer ak_test_..."

Example response — 200

{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
      "object": "payment_instruction",
      "live": true,
      "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
      "label": "Main EUR account",
      "type": "bank_transfer",
      "bank_transfer": {
        "beneficiary": "Example supplier",
        "iban": "ES9121000418450200051332",
        "bic": "CAIXESBBXXX"
      },
      "created_at": "2026-07-31T09:00:00Z",
      "updated_at": "2026-07-31T09:00:00Z"
    }
  ]
}