---
title: "Approve payment order"
method: POST
path: "/payment_orders/{id}/approve"
tags: ["Payment Orders"]
---

# Approve payment order

`POST /payment_orders/{id}/approve`

Approve a payment order in status `pending_approval`. A payment order must be approved before it is processed and sent to the bank for execution. Approving a payment order updates its status to `approved`.

Approve payment orders in batches using the Bulk actions object.

## Path parameters

- `id` string, required

## Response `200`

200

- PaymentOrderDetails
  - `id` string, uuid, required — The UUID of the payment order.
  - `idempotency_key` string, required — An idempotency key is a unique value sent by the client, which the server uses to recognize subsequent retries of the same request.
  - `object` string, required — Type of the object, `payment_order`.
  - `type` 'ae_aani' | 'ae_uaefts' | 'ae_uaefts_rtgs' | 'ar_coelsa' | 'ar_mep' | 'ar_transfer_30' | 'au_becs' | 'au_npp' | 'au_rits' | 'bacs' | 'becs' | 'bh_benefit' | 'bh_fawri' | 'bh_rtgs' | 'br_pix' | 'br_str' | 'br_ted' | 'ca_eft' | 'ca_lynx' | 'ca_rtr' | 'cbs_transfer' | 'ch_sct' | 'ch_sic' | 'ch_sip' | 'chaps' | 'cl_cca' | 'cl_lbtr' | 'cl_tef' | 'co_ach' | 'co_bre_b' | 'co_cud' | 'fps' | 'icelandic_exp' | 'id_bifast' | 'id_birtgs' | 'id_sknbi' | 'internal_transfer' | 'ke_eft' | 'ke_pesalink' | 'ke_rtgs' | 'mx_spei' | 'my_duitnow' | 'my_ibg' | 'my_rentas' | 'no_nbo' | 'no_nics' | 'no_nics_instant' | 'osko' | 'ph_instapay' | 'ph_pddts' | 'ph_philpass' | 'pl_elixir' | 'pl_express_elixir' | 'pl_sorbnet' | 'rits' | 'ro_regis' | 'ro_sent' | 'ro_sent_instant' | 'sa_sarie' | 'sa_sarie_instant' | 'sa_sarie_rtgs' | 'se_bankgirot' | 'se_rix' | 'se_rix_instant' | 'sepa' | 'sepa_instant' | 'sepa_urgent' | 'sg_giro' | 'sg_meps' | 'sg_paynow' | 'swift' | 'swift_fi_to_fi' | 'target2' | 'target2_fi_to_fi' | 'th_bahtnet' | 'th_nitmx' | 'th_promptpay' | 'tl_ips' | 'tl_rtimor_ach' | 'tl_rtimor_rtgs' | 'treasury' | 'us_ach' | 'us_fednow' | 'us_rtp' | 'us_wire' | 'za_eft' | 'za_rpp' | 'za_samos', required — The type of payment.
  - `direction` 'credit' | 'debit', required — The direction of the payment. Describes the direction the money is flowing. A `credit` moves money from your account to someone else's account. A `debit` moves money from someone else's account to your account.
  - `amount` integer, required — The absolute amount of a payment, in the specified currency's smallest units. For euro payments, the smallest unit is cents. €20 is represented as `2000`.
  - `currency` 'EUR', required — The three-letter ISO 4217 currency code, in lowercase. Only `EUR` is supported for now.
  - `value_date` string, date, required — The value date of the payment order.
  - `status` string, required — The lifecycle stage of this payment order. It will be updated as the payment order is processed.
  - `status_details` string, required — The details of the status of this payment order.
  - `reconciled_amount` integer, required — The reconciled amount.
  - `reconciliation_status` 'partially_reconciled' | 'reconciled' | 'unreconciled' | 'excluded', required — The reconciliation status of the payment order, which is either `unreconciled`, `reconciled`, `partially_reconciled`, or `excluded`.
  - `reference` string, required — The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.
  - `end_to_end_id` string — The end-to-end ID of the payment order. Only supported for specific banks and payment schemes. Contact us to get more details.
  - `connected_account_id` string, uuid, required — The ID of the connected account. The connected account is the account used to trigger the payment order.
  - `originating_account` PaymentOrderOriginatingAccount, required — The account from which the payment originates. This field is required for financial institution customers. For corporate customers, this field is optional. If absent, the originating account is automatically derived from the connected account information. If present, the original account either represents the virtual account attached to the connected account or the 3rd party account.
    - `account_number` string — The account number of the originating account. Mandatory when creating payment orders of types other than `swift_fi_to_fi` or `target2_fi_to_fi`.
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.
    - `bank_code` string, required — The bank code.
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.
    - `fi_bank_code` string — The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`.
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `bank_name` string — The name of the bank holding the account.
    - `bank_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `creditor_identifier` string — The unique reference for organisations collecting payments by SEPA Direct Debit.
    - `organization_identification` OrganizationIdentification
      - `legal_entity_identifier` string — Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
      - `business_identification_code` string — Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - "Banking - Banking telecommunication messages - Business identifier code (BIC)".
      - `default_other_identifier_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
      - `others` object[]
        - `type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown', required — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `value` string, required — Allowed value format depends on the type
    - `private_identification` PrivateIdentification
      - `birth_date` string, date — The person’s birth date.
      - `birth_city` string — The person’s birth city.
      - `birth_country` string — The person's birth country as an ISO 3166 alpha-2 country code.
      - `other` object
        - `identification` string — The person’s identification, such as its passport ID, national ID, driving license ID, etc.
        - `identification_type` 'alien_registration_number' | 'passport_number' | 'customer_identification_number' | 'drivers_license_number' | 'employee_identification_number' | 'national_identity_number' | 'social_security_number' | 'telephone_number' | 'tax_identification_number' | 'person_commercial_identification'
        - `custom_identification_type` string — The person’s custom identification type, if no pre-defined identification has been filled in identification_type.
        - `identification_issuer` string — The identification issuing authority.
  - `originating_account_id` string, uuid — The ID of the `internal_account` sending the payment instruction. This attribute is for financial institution customers only, and should be used with Internal accounts of type “own”.
  - `ultimate_originator` PaymentOrderUltimateOriginator — The ultimate originating account of the payment (sometimes called ultimate debtor for a credit transfer or ultimate creditor for a direct debit).
    - `holder_name` string — The account holder name of the ultimate originator.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `organization_identification` OrganizationIdentification
      - `legal_entity_identifier` string — Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
      - `business_identification_code` string — Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - "Banking - Banking telecommunication messages - Business identifier code (BIC)".
      - `default_other_identifier_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
      - `others` object[]
        - `type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown', required — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `value` string, required — Allowed value format depends on the type
    - `private_identification` PrivateIdentification
      - `birth_date` string, date — The person’s birth date.
      - `birth_city` string — The person’s birth city.
      - `birth_country` string — The person's birth country as an ISO 3166 alpha-2 country code.
      - `other` object
        - `identification` string — The person’s identification, such as its passport ID, national ID, driving license ID, etc.
        - `identification_type` 'alien_registration_number' | 'passport_number' | 'customer_identification_number' | 'drivers_license_number' | 'employee_identification_number' | 'national_identity_number' | 'social_security_number' | 'telephone_number' | 'tax_identification_number' | 'person_commercial_identification'
        - `custom_identification_type` string — The person’s custom identification type, if no pre-defined identification has been filled in identification_type.
        - `identification_issuer` string — The identification issuing authority.
  - `receiving_account` PaymentOrderReceivingAccount, required — The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.
    - `account_number` string — The account number of the receiving account. Mandatory when creating payment orders of types other than `swift_fi_to_fi` or `target2_fi_to_fi`.
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number.
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.
    - `fi_bank_code` string — The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`.
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `bank_name` string — The name of the bank holding the account.
    - `bank_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `organization_identification` OrganizationIdentification
      - `legal_entity_identifier` string — Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
      - `business_identification_code` string — Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - "Banking - Banking telecommunication messages - Business identifier code (BIC)".
      - `default_other_identifier_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
      - `others` object[]
        - `type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown', required — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `value` string, required — Allowed value format depends on the type
    - `private_identification` PrivateIdentification
      - `birth_date` string, date — The person’s birth date.
      - `birth_city` string — The person’s birth city.
      - `birth_country` string — The person's birth country as an ISO 3166 alpha-2 country code.
      - `other` object
        - `identification` string — The person’s identification, such as its passport ID, national ID, driving license ID, etc.
        - `identification_type` 'alien_registration_number' | 'passport_number' | 'customer_identification_number' | 'drivers_license_number' | 'employee_identification_number' | 'national_identity_number' | 'social_security_number' | 'telephone_number' | 'tax_identification_number' | 'person_commercial_identification'
        - `custom_identification_type` string — The person’s custom identification type, if no pre-defined identification has been filled in identification_type.
        - `identification_issuer` string — The identification issuing authority.
  - `receiving_account_id` string, uuid — The ID of the `external_account` receiving the payment instruction.
  - `ultimate_receiver` PaymentOrderUltimateReceiver — The ultimate receiving account of the payment (sometimes called ultimate creditor for a credit transfer or ultimate debtor for a direct debit).
    - `holder_name` string — The account holder name of the ultimate receiver.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `organization_identification` OrganizationIdentification
      - `legal_entity_identifier` string — Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
      - `business_identification_code` string — Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - "Banking - Banking telecommunication messages - Business identifier code (BIC)".
      - `default_other_identifier_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
      - `others` object[]
        - `type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown', required — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `value` string, required — Allowed value format depends on the type
    - `private_identification` PrivateIdentification
      - `birth_date` string, date — The person’s birth date.
      - `birth_city` string — The person’s birth city.
      - `birth_country` string — The person's birth country as an ISO 3166 alpha-2 country code.
      - `other` object
        - `identification` string — The person’s identification, such as its passport ID, national ID, driving license ID, etc.
        - `identification_type` 'alien_registration_number' | 'passport_number' | 'customer_identification_number' | 'drivers_license_number' | 'employee_identification_number' | 'national_identity_number' | 'social_security_number' | 'telephone_number' | 'tax_identification_number' | 'person_commercial_identification'
        - `custom_identification_type` string — The person’s custom identification type, if no pre-defined identification has been filled in identification_type.
        - `identification_issuer` string — The identification issuing authority.
  - `direct_debit_mandate` PaymentOrderDirectDebitMandate — The mandate authorizing the direct debit. This attribute must be filled only when the payment order's `direction` is `debit`. It must be left empty if `direct_debit_mandate_id` parameter is filled.
    - `reference` string — The unique code that is assigned to a mandate. The mandate reference is displayed in the destination account statements when a direct debit is debited.
    - `signature_date` string, date — The signature date of the mandate.
    - `type` 'sepa_core' | 'sepa_b2b' | 'bacs_debit' — The type of the mandate.
    - `sequence` 'one_off' | 'recurring' — Deprecated, use `frequency` instead.
    - `frequency` 'one_off' | 'recurring' — The frequency of the mandate, either `one_off` or `recurring`. Not applicable for `bacs_debit` mandates.
  - `direct_debit_mandate_id` string, uuid — The mandate's ID authorizing the direct debit. This attribute is filled only when the payment order's `direction` is `debit`.
  - `direct_debit_sequence_type` 'first' | 'recurring' | 'final' | 'one_off', nullable — Identifies the direct debit sequence, such as first, recurrent, final or one-off. This field is optional and should only be used when `direct_debit_mandate` or `direct_debit_mandate_id` is provided.
  - `intermediary_agents` object[] — Intermediary financial institution agents via which the payment should be processed. Only applicable to `swift`, `swift_fi_to_fi`, and `chaps` payments.
    - `financial_institution_identification` CommonAgentFinancialInstitutionIdentification, required — ISO 20022 financial institution identification of the agent.
      - `swift_code` string — SWIFT BIC of the agent used as the network identifier (e.g. for SWIFT gpi routing).
      - `bank_code` string — Domestic or scheme-specific bank code of the agent (e.g. BIC for SEPA/Target2, sort code for CHAPS).
      - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — Format of `bank_code` (e.g. `bic`, `other`).
      - `name` string — Name of the agent's financial institution.
      - `legal_entity_identifier` string — Legal entity identifier (LEI) of the agent.
      - `postal_address` CommonAddress — The address of the account holder, as an address object.
        - `line_1` string — Line 1.
        - `line_2` string — Line 2.
        - `building_number` string — Building number.
        - `street_name` string — Street name.
        - `postal_code` string — Postal / zip code.
        - `region_state` string — Region or state.
        - `city` string — City.
        - `country` string — ISO 3166 alpha-2 country code.
        - `department` string, nullable — Department name or code.
        - `sub_department` string, nullable — Sub-department name.
        - `building_name` string, nullable — Name of the building.
        - `floor` string, nullable — Floor number or identifier.
        - `postal_box` string, nullable — Postal box.
        - `room` string, nullable — Room number.
        - `city_location_name` string, nullable — Specific city location or landmark.
        - `district_name` string, nullable — District name or administrative region.
      - `other` CommonAgentOtherIdentification
        - `identification` string — Identification value.
        - `identification_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `custom_identification_type` string — Proprietary identification type, used when `identification_type` does not cover the use case.
        - `identification_issuer` string — Entity that issued the identification.
    - `account_number` string — Account number held at the intermediary agent.
    - `account_number_format` string — Format of `account_number` (e.g. `iban`, `bban`).
    - `organization_identification` object
      - `name` string — Name of the intermediary agent.
      - `bank_code` string — Bank code of the intermediary agent.
      - `legal_entity_identifier` string — Legal entity identifier (LEI) of the intermediary agent.
      - `other` string — Other identification of the intermediary agent.
    - `postal_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `previous_instructing_agents` object[] — Applicable to `swift`, `swift_fi_to_fi`, `chaps`, and `target2_fi_to_fi` payments.
    - `financial_institution_identification` CommonAgentFinancialInstitutionIdentification, required — ISO 20022 financial institution identification of the agent.
      - `swift_code` string — SWIFT BIC of the agent used as the network identifier (e.g. for SWIFT gpi routing).
      - `bank_code` string — Domestic or scheme-specific bank code of the agent (e.g. BIC for SEPA/Target2, sort code for CHAPS).
      - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — Format of `bank_code` (e.g. `bic`, `other`).
      - `name` string — Name of the agent's financial institution.
      - `legal_entity_identifier` string — Legal entity identifier (LEI) of the agent.
      - `postal_address` CommonAddress — The address of the account holder, as an address object.
        - `line_1` string — Line 1.
        - `line_2` string — Line 2.
        - `building_number` string — Building number.
        - `street_name` string — Street name.
        - `postal_code` string — Postal / zip code.
        - `region_state` string — Region or state.
        - `city` string — City.
        - `country` string — ISO 3166 alpha-2 country code.
        - `department` string, nullable — Department name or code.
        - `sub_department` string, nullable — Sub-department name.
        - `building_name` string, nullable — Name of the building.
        - `floor` string, nullable — Floor number or identifier.
        - `postal_box` string, nullable — Postal box.
        - `room` string, nullable — Room number.
        - `city_location_name` string, nullable — Specific city location or landmark.
        - `district_name` string, nullable — District name or administrative region.
      - `other` CommonAgentOtherIdentification
        - `identification` string — Identification value.
        - `identification_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown' — Note: set type to unknown if the type of the value is not in the list provided or unknown.
        - `custom_identification_type` string — Proprietary identification type, used when `identification_type` does not cover the use case.
        - `identification_issuer` string — Entity that issued the identification.
    - `account_number` string — Account number held at the previous instructing agent.
    - `account_number_format` string — Format of `account_number` (e.g. `iban`, `bban`).
    - `organization_identification` object
      - `name` string — Name of the previous instructing agent.
      - `bank_code` string — Bank code of the previous instructing agent.
      - `legal_entity_identifier` string — Legal entity identifier (LEI) of the previous instructing agent.
      - `other` string — Other identification of the previous instructing agent.
    - `postal_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `uetr` string, uuid — Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI.
  - `swift_gpi` PaymentOrderSwiftGpiDetails — Contains details on the Swift GPI tracking of the payment order. Only applicable to Swift payment orders on which Swift GPI is available.
    - `status` 'created' | 'in_progress' | 'received' | 'rejected'
    - `confirmed_at` string, date-time — Date on which the payment has been fully confirmed.
    - `confirmed_amount` integer — Amount which has been settled on the receiving account.
    - `confirmed_currency` string — Currency of the payment which has been settled on the receiving account.
    - `tracking_progress` object[]
      - `id` string, required — Tracking step ID.
      - `processed_at` string, date-time, required — Tracking step processing date.
      - `status` 'executed' | 'received' | 'rejected', required — Tracking step status, either `executed`, `received`, or `rejected`.
      - `status_details` string — Tracking step status details and reason codes (for instance ACCC, AC04, G005, etc.).
      - `bank_code` string, required — BIC of the bank or financial institution processing the payment.
      - `fee_amount` integer, required — Potential fee applied on the processing of the payment.
      - `fee_currency` string, required — Currency of the potential fee applied on the processing of the payment.
  - `purpose` string — The purpose code of the payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to `swift` and `chaps` payment types.
  - `category_purpose_code` string — The category purpose of the payment. Recommended for CHAPS payments.
  - `fee_option` 'originator' | 'receiver' | 'shared' — Network payment fee preference. Only applicable to Swift payments. Supported values include `originator` (fee paid by the originating party), `receiver` (paid by the receiving party), or `shared` (fee split between the originating and the receiving party).
  - `routing_instruction` string — Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to `swift` payments.
  - `requested_execution_date` string, date — The requested execution date of the payment order.
  - `auto_approval` boolean, required — The `auto_approval` flag determines whether a payment requires human intervention before execution. When `true`: The system bypasses all manual approval steps. - If a validation rule applies, the payment starts as `pending_approval`. - If no rules apply, the payment is immediately `approved`. When `false`: The payment always starts as `pending_approval` and requires a manual user action. If a validation rule is also attached, it must be successfully completed before the payment can reach the final `approved` status.
  - `payment_validation` object — Information about the payment validation, like the validation rules and validation statuses. `null` if no payment validation rule is attached to the payment order.
    - `status` 'in_progress' | 'successful' | 'failed', required — The aggregated status of payment validation for this payment.
    - `validation_results` CommonPaymentValidationResult[], required — Array of objects detailing the results of payment validation for a given payment validation rule. If the payment order has 2 rules attached, then this array will contain 2 objects.
      - `payment_validation_rule_id` string, uuid, required — The ID of the payment validation rule.
      - `status` 'in_progress' | 'successful' | 'failed', required — The aggregated status of the payment validation contained in this rule.
      - `validations` array[], required — Array of array of objects detailing the result of one given payment validation.
        - object[]
          - `type` 'internal_account_is_active' | 'direct_debit_mandate_is_active' | 'liquidity_screening' | 'sanctions_screening' | 'risk_screening' | 'limits_screening' | 'mambu_authorization', required — The type of the payment validation.
          - `status` 'queued' | 'in_progress' | 'successful' | 'failed' | 'canceled' | 'pending_investigation' | 'pending_retry' | 'technical_error', required — The status of the payment validation.
          - `status_details` string — Details about the status.
          - `resource_id` string — ID of the resource used to perform the payment validation.
          - `resource_url` string — URL of the resource used to perform the payment validation.
          - `mode` 'pre_built' | 'custom' — The mode of the payment validation.
          - `last_updated_at` string, date-time — The UTC timestamp of the last updated time of the payment validation.
          - `retry_details` object, nullable — Tracks the retry context of an individual validation. Exposed only when: - `status` is `pending_retry` (a retry is scheduled), OR - `status` is `failed` after retries have been exhausted (in which case `final_action` was just executed). In every other state this field is `null`. No event is emitted while the validation sits in `pending_retry`; events fire only on transitions in and out of that state.
            - `attempt_count` integer — Number of attempts completed so far, including the initial.
            - `max_attempts` integer — Configured maximum number of attempts (from `retry_policy.max_attempts`).
            - `next_attempt_at` string, date-time, nullable — UTC timestamp of the next scheduled retry. `null` once retries have been exhausted.
            - `final_action` 'approve_payment' | 'cancel_payment' | 'confirm_payment' | 'reject_payment' | 'set_payment_to_received' | 'set_payment_to_pending_confirmation' | 'suspend_payment' — Action that will be (or has been) executed once retries are exhausted. Mirrors the outcome's `action` field from the matching `payment_validation_rule`.
  - `cbs_data` CommonCbsData
    - `transaction_id` string, uuid — The ID of the transaction booked in the core banking system.
    - `authorization_id` string — The ID of the authorization hold acquired in the core banking system.
    - `transactions` CommonCbsTransaction[] — List of all transactions on core banking system for the payment.
      - `id` string, uuid — The ID of the transaction booked in the core banking system.
      - `type` 'deposit' | 'withdrawal' | 'disbursement' | 'repayment' | 'adjustment' — Type of the transaction.
      - `context` 'deposit' | 'suspense' | 'disbursement' | 'repayment' — Context of the transaction.
      - `payment_validation_type` 'internal_account_is_active' | 'direct_debit_mandate_is_active' | 'liquidity_screening' | 'sanctions_screening' | 'risk_screening' | 'limits_screening' | 'mambu_authorization' — The type of the payment validation associated with transaction (key value in `suspense` context).
      - `account_id` string — Account ID on the core banking system used for the transaction.
      - `authorization_id` string — The ID of the authorization hold acquired in the core banking system.
      - `external_id` string — External ID used on the transaction.
      - `channel` string — Channel on the core banking system used for the transaction.
      - `booked_at` string, date-time — The UTC timestamp that the transaction has been booked on the core banking system.
  - `retry_details` PaymentOrderRetryDetails — All relevant information about the payment order retries.
    - `payment_retry_rule_id` string — The ID of the payment retry rule attached to the payment order. See [payment retry rule](https://docs.numeral.io/reference/payment-retry-rule-object).
    - `original_payment_id` string — The ID of the original payment order that led to the current object through a chain of retries.
    - `retried_from_payment_id` string — The ID of the payment order the payment order has been retried from, in case the payment order is a retry.
    - `retried_to_payment_id` string — The ID of the payment order the payment order has been retried to, in case the payment order has been retried.
    - `retry_scheduled_at` string, date-time — The UTC timestamp of the expected retry.
  - `treasury_option` 'local' | 'international' | 'relocated' | 'safeguarding' — The `treasury_option` attribute is used to specify the type of treasury payments (type = `treasury`). It can take the following values, `local` (for instance payments from a French account to another French internal account), `international` (French to German accounts), `relocated` (to send payments from another partner bank), and `safeguarding` (only applicable to financial institutions, to send funds from their settlement account to their safeguarding account and vice versa).
  - `confidentiality_option` 'payroll' — Used in case of a confidential payment. Only `payroll` confidential payments are supported for now.
  - `settlement_method` 'cover' | 'instructed_agent' | 'instructing_agent' — The `settlement_method` attribute is mandatory when creating Swift payment orders (type = `swift`) with a connected account of type `financial_institution`. For all other payment orders, this attribute - if provided - is simply ignored when creating bank files.
  - `settlement_information` PaymentOrderSettlementInformation — Settlement details for the payment. Only applicable to financial institution payments.
    - `settlement_account` string, required — Settlement or nostro account to be used for the payment. Only applicable to financial institution payments.
  - `fi_to_fi_option` 'advi' | 'core' | 'cover' — The `fi_to_fi_option` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`.
  - `related_payment_id` string, uuid — Mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi` and fi_to_fi_option = `cover`.
  - `related_payment_type` string — Auto-filled based on the `related_payment_id`.
  - `metadata` object, required — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
  - `custom_fields` CommonCustomFields, required — Custom fields in JSON `key:value` format. See [Custom fields](https://docs.numeral.io/reference/custom-fields).
  - `bank_data` object, required — Bank data, such as message and transaction IDs, in JSON format.
    - `file_id` string, uuid, required
    - `message_id` string, required
    - `transaction_id` string, required
    - `end_to_end_id` string, required
  - `initiated_at` string, date-time — The UTC timestamp this payment order was initiated. This value marks the start of the payment order lifecycle and has millisecond precision (up to 3 digits where trailing zeros are dropped).<br><br>This field is optional when the payment type is `sepa_instant` and the connected account type is `financial_institution`. If included in the request, its value will be reflected in the response. If omitted when optional, the response will include the field with its value defaulting to the current timestamp. In all other scenarios, the field in the response will be `null`.
  - `instructed_agent` string, nullable — Instructed agent of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.
  - `addressee_bank_code` string, nullable — Addressee BIC of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.
  - `created_at` string, date-time, required — The UTC timestamp of the creation of this payment order.

## Other responses

- `404` — The specified resource was not found.
- `409` — Conflict.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/versions/220f101cc2ef/schema)