# Payment instructions Configure reusable ways for customers to pay invoices. 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` Type: `string` Opaque identifier for a payment instruction. #### `object` Type: `string` String identifying this as a Payment Instruction object. Always `payment_instruction`. #### `live` Type: `boolean` True when the object belongs to the live environment; false for test data. #### `account` Type: `string` Account that owns the instruction. #### `label` Type: `string` Internal label used to distinguish reusable instructions. It is not copied onto invoices. #### `type` Type: `string` Discriminator for the type-specific instruction object. Always `bank_transfer`. #### `bank_transfer` Type: `object` Bank account to show when this instruction is selected. ##### `bank_transfer.beneficiary` Type: `string` Name of the bank-account beneficiary shown to the payer. ##### `bank_transfer.iban` Type: `string` Valid normalized IBAN without spaces. ##### `bank_transfer.bic` Type: `string or null` Optional BIC or SWIFT code, normalized to uppercase. #### `created_at` Type: `string` When the payment instruction was created. #### `updated_at` Type: `string` When the mutable instruction was last updated. ### Example ```json { "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` Type: `string` — required Internal label used to distinguish the instruction. #### `type` Type: `string` — required Creates a bank-transfer instruction. Always `bank_transfer`. #### `bank_transfer` Type: `object` — required Bank details used when rendering future invoice payment options. ##### `bank_transfer.beneficiary` Type: `string` — required Name of the bank-account beneficiary. ##### `bank_transfer.iban` Type: `string` — required IBAN. FiscalRail removes whitespace, uppercases it, and validates its registered country length and check digits. ##### `bank_transfer.bic` Type: `string or null` Optional BIC or SWIFT code. FiscalRail removes whitespace and uppercases it. ### Responses - `201` — [A Payment Instruction object.](#the-payment-instruction-object) Formats: JSON. ### Example requests #### Python ```python 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 ```bash 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 ```json { "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` Type: `string` — required The opaque ID of the payment instruction. ### Responses - `200` — [A Payment Instruction object.](#the-payment-instruction-object) Formats: JSON. ### Example requests #### Python ```python import os from fiscalrail import FiscalRail client = FiscalRail(os.environ["FISCALRAIL_API_KEY"]) payment_instruction = client.payment_instructions.retrieve( "pay_ins_14Vxtqm9KHu4rP3eZyN8gT", ) ``` #### cURL ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/payment-instructions/pay_ins_14Vxtqm9KHu4rP3eZyN8gT' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "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` Type: `string` — required The opaque ID of the payment instruction. ### Request body #### `label` Type: `string` New internal label. #### `bank_transfer` Type: `object` Bank-detail fields to change for future invoice payment options. ##### `bank_transfer.beneficiary` Type: `string` New beneficiary name. ##### `bank_transfer.iban` Type: `string` New IBAN to use for future invoices. Its registered country length and check digits are validated. ##### `bank_transfer.bic` Type: `string or null` New BIC, or null to clear it. ### Responses - `200` — [The updated Payment Instruction object.](#the-payment-instruction-object) Formats: JSON. ### Example requests #### Python ```python 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 ```bash 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 ```json { "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` Type: `string` — required The opaque ID of the payment instruction. ### Responses - `204` — The payment instruction was deleted. The response has no body. ### Example requests #### Python ```python import os from fiscalrail import FiscalRail client = FiscalRail(os.environ["FISCALRAIL_API_KEY"]) client.payment_instructions.delete( "pay_ins_14Vxtqm9KHu4rP3eZyN8gT", ) ``` #### cURL ```bash 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` Type: `integer` Maximum number of resources to return. Defaults to `25`. #### `starting_after` Type: `string` Return payment instructions older than this instruction ID. Cannot be combined with `ending_before`. #### `ending_before` Type: `string` Return payment instructions newer than this instruction ID. Cannot be combined with `starting_after`. ### Responses - `200` — [A list of Payment Instruction objects.](#the-payment-instruction-object) Formats: JSON. ### Example requests #### Python ```python import os from fiscalrail import FiscalRail client = FiscalRail(os.environ["FISCALRAIL_API_KEY"]) payment_instructions = client.payment_instructions.list( limit=25, ) ``` #### cURL ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/payment-instructions?limit=25' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "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" } ] } ```