{"openapi":"3.1.0","info":{"title":"Payments","description":"Automate payments across banks with a single API","version":"1","contact":{"name":"API Support","email":"dev@numeral.io"}},"tags":[{"name":"Payment Orders","description":"Payment orders endpoints"},{"name":"Incoming Payments","description":"Incoming payments endpoints"},{"name":"Returns","description":"Returns endpoints"}],"servers":[{"url":"https://sandbox.numeral.io/v1"}],"components":{"securitySchemes":{"sec0":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"payment_orders.create_parameters.idempotency_key":{"name":"Idempotency-Key","in":"header","description":"An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.","schema":{"type":"string","example":"8A2gcC"}},"list.common_parameters.sort_order":{"name":"sort_order","in":"query","description":"Order is based on attribute `created_at`. If `asc`, results are fetched in chronological order. If `desc`, results are fetched in reversed chronological order. Default order is `desc`.\n","schema":{"type":"string","enum":["asc","desc"]}}},"responses":{"errors.400.validation":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.404.not_found":{"description":"The specified resource was not found."},"errors.409.conflict":{"description":"Conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.415.unsupported_media_type":{"description":"Unsupported Media Type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.500.internal_server_error":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}},"schemas":{"error":{"type":"object","properties":{"error":{"type":"string","example":"validation_error"},"message":{"type":"string","example":"validation errors occurred while processing request"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}}}},"correlation_id":{"type":"string","format":"uuid"}}},"payment_type":{"type":"string","description":"The type of payment.","enum":["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"]},"common.address":{"type":"object","description":"The address of the account holder, as an address object.","properties":{"line_1":{"type":"string","description":"Line 1.","example":"1, place de la Concorde"},"line_2":{"type":"string","description":"Line 2.","example":""},"building_number":{"type":"string","description":"Building number.","example":"1"},"street_name":{"type":"string","description":"Street name.","example":"place de la Concorde"},"postal_code":{"type":"string","description":"Postal / zip code.","example":"75008"},"region_state":{"type":"string","description":"Region or state.","example":""},"city":{"type":"string","example":"Paris","description":"City."},"country":{"type":"string","example":"FR","description":"ISO 3166 alpha-2 country code."},"department":{"type":["string","null"],"description":"Department name or code.","example":"Marketing"},"sub_department":{"type":["string","null"],"description":"Sub-department name.","example":"Content team"},"building_name":{"type":["string","null"],"description":"Name of the building.","example":"Bat. 4"},"floor":{"type":["string","null"],"description":"Floor number or identifier.","example":"3"},"postal_box":{"type":["string","null"],"description":"Postal box.","example":"67b"},"room":{"type":["string","null"],"description":"Room number.","example":"47"},"city_location_name":{"type":["string","null"],"description":"Specific city location or landmark.","example":"Confluences"},"district_name":{"type":["string","null"],"description":"District name or administrative region.","example":"District 9"}}},"common.metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"common.custom_fields":{"type":"object","description":"Custom fields in JSON `key:value` format. See [Custom fields](ref:custom-fields)."},"common.direct_debit_mandate":{"type":["object","null"],"description":"The mandate authorizing the direct debit.","required":["reference","signature_date","type"],"properties":{"reference":{"type":"string","description":"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.","maxLength":35,"example":"REF-783232"},"signature_date":{"type":"string","description":"The signature date of the mandate.","format":"date"},"last_debit_collection_date":{"type":["string","null"],"format":"date","description":"The date of the last direct debit collection processed against this mandate."},"expiry_date":{"type":["string","null"],"format":"date","description":"The date after which the mandate is expired and cannot be used for subsequent direct debit collections."},"type":{"type":"string","description":"The type of the mandate.","enum":["sepa_core","sepa_b2b","bacs_debit"]},"sequence":{"type":"string","description":"Deprecated, use `frequency` instead.","deprecated":true,"enum":["one_off","recurring"],"example":"recurring"},"frequency":{"type":"string","description":"The frequency of the mandate, either `one_off` or `recurring`. Mandatory when type is `sepa_core` or `sepa_b2b`.","enum":["one_off","recurring"],"example":"recurring"}}},"common.payment_validation_result":{"type":"object","required":["payment_validation_rule_id","status","validations"],"properties":{"payment_validation_rule_id":{"type":"string","format":"uuid","description":"The ID of the payment validation rule.","example":"c2c303de-c0f0-4015-801d-6ae24f248092"},"status":{"type":"string","description":"The aggregated status of the payment validation contained in this rule.","enum":["in_progress","successful","failed"]},"validations":{"type":"array","description":"Array of array of objects detailing the result of one given payment validation.","items":{"type":"array","items":{"type":"object","required":["type","status"],"properties":{"type":{"type":"string","description":"The type of the payment validation.","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]},"status":{"type":"string","description":"The status of the payment validation.","enum":["queued","in_progress","successful","failed","canceled","pending_investigation","pending_retry","technical_error"]},"status_details":{"type":"string","description":"Details about the status.","example":"some details"},"resource_id":{"type":"string","description":"ID of the resource used to perform the payment validation.","example":"b29b85ad-b2ef-4978-b27f-e44ae4914756"},"resource_url":{"type":"string","description":"URL of the resource used to perform the payment validation.","example":"https://example.com/b29b85ad-b2ef-4978-b27f-e44ae4914756"},"mode":{"type":"string","description":"The mode of the payment validation.","enum":["pre_built","custom"]},"last_updated_at":{"type":"string","format":"date-time","example":"2022-01-03T11:53:19.568Z","description":"The UTC timestamp of the last updated time of the payment validation."},"retry_details":{"type":"object","nullable":true,"description":"Tracks the retry context of an individual validation.\nExposed only when:\n  - `status` is `pending_retry` (a retry is scheduled), OR\n  - `status` is `failed` after retries have been exhausted\n    (in which case `final_action` was just executed).\nIn every other state this field is `null`.\n\nNo event is emitted while the validation sits in `pending_retry`;\nevents fire only on transitions in and out of that state.\n","properties":{"attempt_count":{"type":"integer","minimum":1,"maximum":5,"description":"Number of attempts completed so far, including the initial.","example":1},"max_attempts":{"type":"integer","minimum":1,"maximum":5,"description":"Configured maximum number of attempts (from `retry_policy.max_attempts`).","example":3},"next_attempt_at":{"type":"string","format":"date-time","nullable":true,"description":"UTC timestamp of the next scheduled retry. `null` once retries\nhave been exhausted.\n","example":"2026-03-27T14:00:00Z"},"final_action":{"type":"string","enum":["approve_payment","cancel_payment","confirm_payment","reject_payment","set_payment_to_received","set_payment_to_pending_confirmation","suspend_payment"],"description":"Action that will be (or has been) executed once retries are exhausted.\nMirrors the outcome's `action` field from the matching `payment_validation_rule`.\n","example":"reject_payment"}}}}}}}}},"common.update_payment_validation":{"type":"object","required":["payment_validation_rule_id","type","status"],"properties":{"payment_validation_rule_id":{"type":"string","format":"uuid","description":"The ID of the payment validation rule.","example":"c2c303de-c0f0-4015-801d-6ae24f248092"},"type":{"type":"string","description":"The type of the payment validation.","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]},"status":{"type":"string","description":"The status of the payment validation.","enum":["successful","failed","pending_investigation"]},"status_details":{"type":"string","maxLength":1000,"description":"Details about the status.","example":"some details"},"resource_id":{"type":"string","maxLength":1000,"description":"ID of the resource used to perform the payment validation.","example":"b29b85ad-b2ef-4978-b27f-e44ae4914756"},"resource_url":{"type":"string","maxLength":1000,"description":"URL of the resource used to perform the payment validation.","example":"https://example.com/b29b85ad-b2ef-4978-b27f-e44ae4914756"}}},"common.agent_other_identification":{"type":"object","properties":{"identification":{"type":"string","maxLength":35,"description":"Identification value.","example":"35664632"},"identification_type":{"type":"string","description":"Type of identification. Use `custom_identification_type` for values not covered by this list.","$ref":"#/components/schemas/organization_identification.others.type"},"custom_identification_type":{"type":"string","maxLength":35,"description":"Proprietary identification type, used when `identification_type` does not cover the use case.","example":"custom_type"},"identification_issuer":{"type":"string","maxLength":35,"description":"Entity that issued the identification.","example":"HMRC"}}},"common.agent_financial_institution_identification":{"type":"object","description":"ISO 20022 financial institution identification of the agent.","properties":{"swift_code":{"type":"string","description":"SWIFT BIC of the agent used as the network identifier (e.g. for SWIFT gpi routing).","example":"SOMEBIC0XXX"},"bank_code":{"type":"string","description":"Domestic or scheme-specific bank code of the agent (e.g. BIC for SEPA/Target2, sort code for CHAPS).","example":"SOMEBIC0XXX"},"bank_code_format":{"type":"string","description":"Format of `bank_code` (e.g. `bic`, `other`).","example":"bic","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"]},"name":{"type":"string","maxLength":140,"description":"Name of the agent's financial institution.","example":"Bank A"},"legal_entity_identifier":{"type":"string","description":"Legal entity identifier (LEI) of the agent.","example":"219200WSGIIZEPF1P999"},"postal_address":{"$ref":"#/components/schemas/common.address","description":"Postal address of the agent."},"other":{"$ref":"#/components/schemas/common.agent_other_identification","description":"Other proprietary identification of the agent."}}},"common.intermediary_agents":{"type":"array","description":"Intermediary financial institution agents via which the payment should be processed. Only applicable to `swift`, `swift_fi_to_fi`, and `chaps` payments.","maxItems":3,"items":{"type":"object","required":["financial_institution_identification"],"properties":{"financial_institution_identification":{"$ref":"#/components/schemas/common.agent_financial_institution_identification"},"account_number":{"type":"string","description":"Account number held at the intermediary agent.","example":"GB7601234567890627967100010"},"account_number_format":{"type":"string","description":"Format of `account_number` (e.g. `iban`, `bban`).","example":"iban"}}}},"common.previous_instructing_agents":{"type":"array","description":"Applicable to `swift`, `swift_fi_to_fi`, `chaps`, and `target2_fi_to_fi` payments.","maxItems":3,"items":{"type":"object","required":["financial_institution_identification"],"properties":{"financial_institution_identification":{"$ref":"#/components/schemas/common.agent_financial_institution_identification"},"account_number":{"type":"string","description":"Account number held at the previous instructing agent.","example":"12345678"},"account_number_format":{"type":"string","description":"Format of `account_number` (e.g. `iban`, `bban`).","example":"iban"}}}},"common.receiving_agent_account":{"type":"object","description":"Account held at the receiving agent. Maps to CdtrAgtAcct for Swift CBPR+. Only applicable to `swift` and `swift_fi_to_fi` payments.","required":["account_number"],"properties":{"account_number":{"type":"string","maxLength":34,"description":"Account number held at the receiving agent.","example":"FR7630006000011234567890189"},"account_number_format":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"}}},"common.cbs_data":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid","description":"The ID of the transaction booked in the core banking system.","example":"c2c303de-c0f0-4015-801d-6ae24f248092","deprecated":true},"authorization_id":{"type":"string","description":"The ID of the authorization hold acquired in the core banking system.","example":"62f87f47-86c6-4b1e-b49d-e6df91922cd7","deprecated":true},"transactions":{"type":"array","description":"List of all transactions on core banking system for the payment.","items":{"$ref":"#/components/schemas/common.cbs_transaction"}}}},"common.cbs_transaction":{"type":"object","description":"Core banking system transaction properties","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the transaction booked in the core banking system.","example":"c2c303de-c0f0-4015-801d-6ae24f248092"},"type":{"type":"string","description":"Type of the transaction.","enum":["deposit","withdrawal","disbursement","repayment","adjustment"],"example":"withdrawal"},"context":{"type":"string","description":"Context of the transaction.","enum":["deposit","suspense","disbursement","repayment"],"example":"deposit"},"payment_validation_type":{"type":"string","description":"The type of the payment validation associated with transaction (key value in `suspense` context).","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]},"account_id":{"type":"string","description":"Account ID on the core banking system used for the transaction."},"authorization_id":{"type":"string","description":"The ID of the authorization hold acquired in the core banking system.","example":"62f87f47-86c6-4b1e-b49d-e6df91922cd7"},"external_id":{"type":"string","description":"External ID used on the transaction."},"channel":{"type":"string","description":"Channel on the core banking system used for the transaction.","example":"cash"},"booked_at":{"type":"string","format":"date-time","example":"2022-01-03T11:53:19.568Z","description":"The UTC timestamp that the transaction has been booked on the core banking system."}}},"common.charges_information_agent":{"type":"object","description":"The financial institution bearing the charges.","properties":{"bank_code":{"type":"string","description":"The bank code of the charge bearer.","example":"SOGEFRPP"},"name":{"type":"string","description":"The name of the charge bearer.","example":"Société Générale"}}},"common.charges_information_item":{"type":"object","description":"Contains the charges or fees that could be included as part of a return.","properties":{"amount":{"type":"integer","format":"int64","description":"The charges amount, expressed in the minimum currency unit.","example":1000},"currency":{"type":"string","description":"The charges currency (ISO 4217 currency code).","example":"EUR"},"agent":{"$ref":"#/components/schemas/common.charges_information_agent","description":"The financial institution bearing the charges."}}},"organization_identification.others.type":{"type":"string","enum":["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"],"description":"Note: set type to unknown if the type of the value is not in the list provided or unknown."},"organization_identification":{"type":"object","properties":{"legal_entity_identifier":{"type":"string","example":"529900T8BM49AURSDO55","description":"Legal Entity Identifier is a code allocated to a party as described in ISO 17442 \"Financial Services - Legal Entity Identifier (LEI)\"."},"business_identification_code":{"type":"string","example":"SOGEFRPP","description":"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":{"$ref":"#/components/schemas/organization_identification.others.type","description":"Optional attribute that defines the default type/value to use in the `others` object. Its value must match an existing type in the others array. If this attribute is `null` or `invalid`, then the content in the `others` object will not be sent to the bank."},"others":{"type":"array","items":{"type":"object","description":"Type value array containing a list of organization identifiers according to its Numeral code","required":["type","value"],"properties":{"type":{"$ref":"#/components/schemas/organization_identification.others.type","example":"siret"},"value":{"type":"string","example":"123456789123","description":"Allowed value format depends on the type"}}}}}},"private_identification.other.identification_type":{"type":"string","enum":["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"],"example":"passport_number"},"private_identification":{"type":"object","properties":{"birth_date":{"type":"string","format":"date","description":"The person’s birth date.","example":"1990-01-01"},"birth_city":{"type":"string","maxLength":35,"description":"The person’s birth city.","example":"Paris"},"birth_country":{"type":"string","maxLength":2,"description":"The person's birth country as an ISO 3166 alpha-2 country code.","example":"FR"},"other":{"type":"object","properties":{"identification":{"type":"string","maxLength":35,"description":"The person’s identification, such as its passport ID, national ID, driving license ID, etc.","example":"123456789"},"identification_type":{"$ref":"#/components/schemas/private_identification.other.identification_type","description":"The person’s identification type, such as its passport ID, national ID, driving license ID, etc."},"custom_identification_type":{"type":"string","maxLength":35,"description":"The person’s custom identification type, if no pre-defined identification has been filled in identification_type.","example":""},"identification_issuer":{"type":"string","maxLength":35,"description":"The identification issuing authority.","example":""}}}}},"payment_order.originating_account":{"type":"object","description":"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.","required":["bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"fi_bank_code":{"type":"string","example":"SOGEFRPP","description":"The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"creditor_identifier":{"type":"string","description":"The unique reference for organisations collecting payments by SEPA Direct Debit.","example":"FR12ZZZ123456","maxLength":35},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.ultimate_originator":{"type":"object","description":"The ultimate originating account of the payment (sometimes called ultimate debtor for a credit transfer or ultimate creditor for a direct debit).","properties":{"holder_name":{"type":"string","example":"SoftwareCo","description":"The account holder name of the ultimate originator."},"holder_address":{"$ref":"#/components/schemas/common.address"},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the ultimate originator. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the ultimate originator account. Not allowed if `organization_identification` is filled."}}},"payment_order.ultimate_receiver":{"type":"object","description":"The ultimate receiving account of the payment (sometimes called ultimate creditor for a credit transfer or ultimate debtor for a direct debit).","properties":{"holder_name":{"type":"string","example":"SoftwareCo","description":"The account holder name of the ultimate receiver."},"holder_address":{"$ref":"#/components/schemas/common.address"},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the ultimate receiver. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the ultimate receiver account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.\n","required":["bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code, for instance BIC / Swift code, UK sort code, or US routing number."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"fi_bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.generic":{"type":"object","description":"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.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.sepa":{"type":"object","description":"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.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.sepa_debit":{"type":"object","description":"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.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"creditor_identifier":{"type":"string","description":"The unique reference for organisations collecting payments by SEPA Direct Debit.","example":"FR12ZZZ123456","maxLength":35},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.uk":{"type":"object","description":"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.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["uk_account_number","iban","tokenized","other"],"example":"uk_account_number"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["uk_sorting_code","bic","tokenized","other"],"example":"uk_sorting_code"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.uk_debit":{"type":"object","description":"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.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["uk_account_number","iban","tokenized","other"],"example":"uk_account_number"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["uk_sorting_code","bic","tokenized","other"],"example":"uk_sorting_code"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"creditor_identifier":{"type":"string","description":"The Service User Number (SUN) or equivalent creditor identifier for BACS Direct Debit.","example":"123456","maxLength":35},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.fi":{"type":"object","description":"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.","required":["fi_bank_code","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"fi_bank_code":{"type":"string","example":"SOGEFRPP","description":"The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.originating_account.other":{"type":"object","description":"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.","required":["bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567890627967100010","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"SOGEFRPP","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"SoftwareCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account.generic":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account.sepa":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account.uk":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.","required":["account_number","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["uk_account_number","tokenized","other"],"example":"uk_account_number"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["uk_sorting_code","tokenized","other"],"example":"uk_sorting_code"},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account.fi":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.","required":["fi_bank_code","bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"fi_bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The `fi_bank_code` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.receiving_account.other":{"type":"object","description":"The account receiving the payment instruction. It must be left empty if `receiving_account_id` or `direct_debit_mandate_id` parameter is filled.","required":["bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"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":{"type":"string","description":"The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`.","enum":["iban","uk_account_number","us_account_number","tokenized","other"],"example":"iban"},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code."},"bank_code_format":{"type":"string","description":"The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/common.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"payment_order.direct_debit_mandate":{"type":"object","description":"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.","properties":{"reference":{"type":"string","maxLength":35,"example":"regmedia-mandate-rz47ash4","description":"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":{"type":"string","format":"date","example":"2022-01-20","description":"The signature date of the mandate."},"type":{"type":"string","enum":["sepa_core","sepa_b2b","bacs_debit"],"example":"sepa_core","description":"The type of the mandate."},"sequence":{"type":"string","enum":["one_off","recurring"],"example":"recurring","description":"Deprecated, use `frequency` instead.","deprecated":true},"frequency":{"type":"string","enum":["one_off","recurring"],"example":"recurring","description":"The frequency of the mandate, either `one_off` or `recurring`. Not applicable for `bacs_debit` mandates."}}},"payment_order.direct_debit_sequence_type":{"type":["string","null"],"description":"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.","enum":["first","recurring","final","one_off"],"example":"recurring"},"payment_order.retry_details":{"type":"object","description":"All relevant information about the payment order retries.","properties":{"payment_retry_rule_id":{"type":"string","description":"The ID of the payment retry rule attached to the payment order. See [payment retry rule](ref:payment-retry-rule-object).","example":"5075f0d2-6a6b-49ea-ae63-b11368873157"},"original_payment_id":{"type":"string","description":"The ID of the original payment order that led to the current object through a chain of retries.","example":"10384f4e-3eef-42a3-bc8d-8d2f35eb279d"},"retried_from_payment_id":{"type":"string","description":"The ID of the payment order the payment order has been retried from, in case the payment order is a retry.","example":"8e91531e-c29c-4e69-ab94-71e04f8d0b55"},"retried_to_payment_id":{"type":"string","description":"The ID of the payment order the payment order has been retried to, in case the payment order has been retried.","example":"58ebd65d-bc3c-4d91-816e-5a011702acbc"},"retry_scheduled_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the expected retry.","example":"2024-05-31T15:42:07.314159Z"}}},"payment_order.settlement_information":{"type":"object","description":"Settlement details for the payment. Only applicable to financial institution payments.","required":["settlement_account"],"properties":{"settlement_account":{"type":"string","description":"Settlement or nostro account to be used for the payment. Only applicable to financial institution payments. For Swift correspondent banking payments, this property is mutually exclusive with the correspondent_bank_account_id attribute.","example":"FR7630006000011234567890189"}}},"payment_order.swift_gpi_details":{"type":"object","description":"Contains details on the Swift GPI tracking of the payment order. Only applicable to Swift payment orders on which Swift GPI is available.","properties":{"status":{"type":"string","enum":["created","in_progress","received","rejected"]},"confirmed_at":{"type":"string","format":"date-time","description":"Date on which the payment has been fully confirmed."},"confirmed_amount":{"type":"integer","format":"int64","description":"Amount which has been settled on the receiving account.","minimum":0,"example":3000},"confirmed_currency":{"type":"string","description":"Currency of the payment which has been settled on the receiving account.","example":"EUR"},"tracking_progress":{"type":"array","items":{"type":"object","description":"Contains Swift GPI tracking steps involved on the processing of the payment.","required":["id","processed_at","status","bank_code","fee_amount","fee_currency"],"properties":{"id":{"type":"string","description":"Tracking step ID.","example":"01"},"processed_at":{"type":"string","format":"date-time","description":"Tracking step processing date."},"status":{"type":"string","description":"Tracking step status, either `executed`, `received`, or `rejected`.","enum":["executed","received","rejected"]},"status_details":{"type":"string","description":"Tracking step status details and reason codes (for instance ACCC, AC04, G005, etc.).","example":"G005"},"bank_code":{"type":"string","description":"BIC of the bank or financial institution processing the payment.","example":"SOMEBIC0XXX"},"fee_amount":{"type":"integer","format":"int64","minimum":0,"example":3000,"description":"Potential fee applied on the processing of the payment."},"fee_currency":{"type":"string","description":"Currency of the potential fee applied on the processing of the payment.","example":"EUR"}}}}}},"payment_order.creation_details":{"type":"object","allOf":[{"not":{"required":["originating_account","originating_account_id"]}},{"not":{"required":["receiving_account","receiving_account_id"]}},{"not":{"required":["receiving_account_id","direct_debit_mandate_id"]}},{"not":{"required":["receiving_account","direct_debit_mandate_id"]}},{"not":{"required":["direct_debit_mandate","direct_debit_mandate_id"]}},{"if":{"required":["direct_debit_mandate_id"]},"then":{"properties":{"direction":{"const":"debit"}}}}],"required":["type","direction","amount","currency","connected_account_id","reference"],"properties":{"type":{"$ref":"#/components/schemas/payment_type"},"direction":{"type":"string","description":"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.","enum":["credit","debit"]},"amount":{"type":"integer","description":"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`.","format":"int64","minimum":0,"example":3000},"currency":{"type":"string","description":"The ISO 4217 currency code of the payment order.","example":"EUR"},"instructed_amount":{"type":"integer","format":"int64","minimum":0,"description":"Instructed amount of the payment order, in the specified currency's smallest units. If not filled, it will contain the same value as the `amount` attribute. Mandatory when `instructed_amount_currency` is filled. Only applicable to `swift` and `target2` payment orders sent from a connected account of type `financial_institution`.","example":3050},"instructed_amount_currency":{"type":"string","description":"Instructed amount currency of the payment order. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes should be used. If not filled, it will contain the same value as the `currency` attribute. Only applicable to `swift` and `target2` payment orders sent from a connected account of type `financial_institution`.","example":"EUR"},"charges_information":{"$ref":"#/components/schemas/payment_order.charges_information"},"reference":{"type":"string","maxLength":140,"description":"The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.","example":"Invoice 1234"},"end_to_end_id":{"type":"string","description":"The end-to-end ID of the payment order. Only supported for specific banks and payment schemes. Contact us to get more details.","maxLength":35,"example":"c3b2d737bc"},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account. The connected account is the account used to trigger the payment order.","example":"24e3157c-4942-11ed-b878-0242ac120002"},"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.generic"},"originating_account_id":{"type":"string","format":"uuid","description":"The ID of the `internal_account` sending the payment instruction. It must be left empty if the `originating_account` parameter is filled.\n","example":"8d97ed83-a6f7-4929-8e90-01b2912fb6a7"},"ultimate_originator":{"$ref":"#/components/schemas/payment_order.ultimate_originator"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.generic"},"receiving_account_id":{"type":"string","format":"uuid","description":"The ID of the `external_account` receiving the payment instruction. It must be left empty if `receiving_account` or `direct_debit_mandate_id` parameter is filled.\n","example":"b38f5318-a389-4278-9cbe-d16116750982"},"ultimate_receiver":{"$ref":"#/components/schemas/payment_order.ultimate_receiver"},"direct_debit_mandate":{"$ref":"#/components/schemas/payment_order.direct_debit_mandate"},"direct_debit_mandate_id":{"type":"string","format":"uuid","description":"The mandate's ID authorizing the direct debit. This attribute must be filled only when the payment order's `direction` is `debit`. It must be left empty if `receiving_account`, `receiving_account_id`, or `direct_debit_mandate` parameter is filled.","example":"15ee5994-9019-478c-b27a-a4edfec17c58"},"direct_debit_sequence_type":{"$ref":"#/components/schemas/payment_order.direct_debit_sequence_type"},"initiated_at":{"type":"string","format":"date-time","example":"2022-01-03T11:53:19.568Z","description":"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 valid and optional when the payment type is `sepa_instant` and the connected account type is `financial_institution`. In all other cases, this field must be omitted from the request."},"intermediary_agents":{"$ref":"#/components/schemas/common.intermediary_agents"},"previous_instructing_agents":{"$ref":"#/components/schemas/common.previous_instructing_agents"},"receiving_agent_account":{"$ref":"#/components/schemas/common.receiving_agent_account"},"uetr":{"type":"string","format":"uuid","description":"Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI."},"purpose":{"type":"string","description":"The purpose code of the payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to `swift` and `chaps` payment types.","example":"SALA"},"category_purpose_code":{"type":"string","description":"The category purpose of the payment. Recommended for `chaps` payments.","example":"B2B"},"fee_option":{"type":"string","enum":["originator","receiver","shared"],"description":"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).","example":"shared"},"routing_instruction":{"type":"string","description":"Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to `swift` payments.","example":"Cross-border routing instructions"},"instructed_agent":{"type":"string","description":"Instructed agent of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, target_2_fi_to_fi, swift and swift_fi_to_fi. If not set, Mambu Payments will resolve this value automatically based on the relevant payment scheme, correspondent bank, or receiving account. This attribute is mutually exclusive with the correspondent_bank_id attribute.","example":"SOMEBIC0XXX"},"addressee_bank_code":{"type":"string","description":"Addressee BIC of the payment order. Can only be set for financial institution payments of type `sepa_instant`, `target2`, `target_2_fi_to_fi`, `swift` and `swift_fi_to_fi`. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme, correspondent bank or receiving account.\n","example":"SOMEBIC0XXX"},"correspondent_bank_id":{"type":"string","format":"uuid","description":"Correspondent bank ID, to override the automatically resolved correspondent bank with another one saved in your correspondent banks. Only applicable to `swift` payment orders created from a swift-direct connected account. Mutually exclusive with `instructed_agent`, which overrides the same correspondent bank with a BIC that is not saved in your correspondent banks, and with `settlement_information.settlement_account`.\n"},"correspondent_bank_account_id":{"type":"string","format":"uuid","description":"Correspondent bank account ID, to override the automatically resolved correspondent bank account. Only applicable to `swift` payment orders created from a swift-direct connected account. Mutually exclusive with `settlement_information.settlement_account`, which overrides the same settlement account with an account number that is not saved in your correspondent bank accounts.\n"},"requested_execution_date":{"type":"string","description":"The requested execution date of the payment order.","format":"date","example":"2022-01-03"},"auto_approval":{"type":"boolean","default":false,"description":"The `auto_approval` flag determines whether a payment requires human intervention before execution.\n\nWhen `true`: The system bypasses all manual approval steps.\n- If a validation rule applies, the payment starts as `pending_approval`.\n- If no rules apply, the payment is immediately `approved`.\n\nWhen `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.\n","example":false},"retry_details":{"type":"object","description":"Information about the payment order retries.","properties":{"payment_retry_rule_id":{"type":"string","description":"The ID of the payment retry rule to be attached to the payment order. See [payment retry rule](ref:payment-retry-rule-object).\n\nThe payment retry rule must be compatible with `payment_type` and `payment_direction`.\n","example":"5075f0d2-6a6b-49ea-ae63-b11368873157"}}},"treasury_option":{"type":"string","enum":["local","international","relocated","safeguarding"],"description":"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).","example":"local"},"confidentiality_option":{"type":"string","enum":["payroll"],"description":"Used in case of a confidential payment. Only `payroll` confidential payments are supported for now.","example":"payroll"},"settlement_method":{"type":"string","enum":["cover","instructed_agent","instructing_agent"],"description":"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.","example":"cover"},"settlement_information":{"$ref":"#/components/schemas/payment_order.settlement_information"},"fi_to_fi_option":{"type":"string","enum":["advi","core","cover"],"description":"The `fi_to_fi_option` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`.","example":"core"},"related_payment_id":{"type":"string","format":"uuid","example":"a815e756-5576-4d40-9fbd-38ec304b856c","description":"Mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi` and fi_to_fi_option = `cover`."},"cbs_transfer_allowed":{"type":"boolean","default":false,"description":"Indicates if the payment type could be promoted to a `cbs_transfer`."},"lending":{"type":"object","description":"Manual lending flow parameters.","properties":{"context":{"type":"string","enum":["disbursement","repayment"],"description":"Context for the lending flow. Disbursements require a credit payment. Repayments require a debit payment."},"credit_arrangement_id":{"type":"string","format":"uuid","description":"The ID of the associated credit arrangement. Mutually exclusive with `loan_ids`."},"loan_ids":{"type":"array","maxLength":1,"description":"The ID of the associated credit arrangement. Only one loan id is allowed. Mutually exclusive with `credit_arrangement_id`.","items":{"type":"string","format":"uuid"}}}},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"custom_fields":{"$ref":"#/components/schemas/common.custom_fields"}}},"payment_order.creation_details.sepa_credit":{"title":"SEPA Credit Transfer (SCT)","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"sepa"},"direction":{"const":"credit"},"currency":{"const":"EUR"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"treasury_option":false,"settlement_method":false,"settlement_information":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.sepa"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.sepa"}}}]},"payment_order.creation_details.sepa_debit":{"title":"SEPA Direct Debit (SDD)","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"sepa"},"direction":{"const":"debit"},"currency":{"const":"EUR"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"treasury_option":false,"settlement_method":false,"settlement_information":false,"fi_to_fi_option":false,"related_payment_id":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.sepa_debit"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.sepa"}}}]},"payment_order.creation_details.sepa_instant":{"title":"SEPA Instant","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"sepa_instant"},"direction":{"const":"credit"},"currency":{"const":"EUR"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"settlement_information":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.sepa"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.sepa"}}}]},"payment_order.creation_details.sepa_urgent":{"title":"SEPA Urgent","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"sepa_urgent"},"direction":{"const":"credit"},"currency":{"const":"EUR"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"settlement_information":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.sepa"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.sepa"}}}]},"payment_order.creation_details.swift":{"title":"Swift","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"swift"},"direction":{"const":"credit"},"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.generic"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.generic"}},"required":["fee_option"]}]},"payment_order.creation_details.swift_fi_to_fi":{"title":"Swift FI-to-FI","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"swift_fi_to_fi"},"direction":{"const":"credit"},"fee_option":false,"routing_instruction":false,"purpose":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.fi"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.fi"}},"required":["fi_to_fi_option"]},{"if":{"properties":{"fi_to_fi_option":{"const":"cover"}},"required":["fi_to_fi_option"]},"then":{"required":["related_payment_id"]}}]},"payment_order.creation_details.target2":{"title":"Target2","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"target2"},"direction":{"const":"credit"},"currency":{"const":"EUR"},"fee_option":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.sepa"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.sepa"}}}]},"payment_order.creation_details.target2_fi_to_fi":{"title":"Target2 FI-to-FI","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"target2_fi_to_fi"},"direction":{"const":"credit"},"currency":{"const":"EUR"},"fee_option":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"initiated_at":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.fi"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.fi"}},"required":["fi_to_fi_option"]},{"if":{"properties":{"fi_to_fi_option":{"const":"cover"}},"required":["fi_to_fi_option"]},"then":{"required":["related_payment_id"]}}]},"payment_order.creation_details.fps":{"title":"FPS","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"fps"},"direction":{"const":"credit"},"currency":{"const":"GBP"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.uk"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.uk"}}}]},"payment_order.creation_details.bacs_debit":{"title":"BACS Direct Debit","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","required":["direct_debit_sequence_type"],"properties":{"type":{"const":"bacs"},"direction":{"const":"debit"},"currency":{"const":"GBP"},"fee_option":false,"uetr":false,"routing_instruction":false,"purpose":false,"category_purpose_code":false,"ultimate_originator":false,"ultimate_receiver":false,"end_to_end_id":false,"intermediary_agents":false,"receiving_agent_account":false,"previous_instructing_agents":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"settlement_information":false,"fi_to_fi_option":false,"related_payment_id":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.uk_debit"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.uk"}}}]},"payment_order.creation_details.chaps":{"title":"CHAPS","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","properties":{"type":{"const":"chaps"},"direction":{"const":"credit"},"currency":{"const":"GBP"},"fee_option":false,"uetr":false,"routing_instruction":false,"initiated_at":false,"instructed_agent":false,"addressee_bank_code":false,"confidentiality_option":false,"treasury_option":false,"settlement_method":false,"fi_to_fi_option":false,"related_payment_id":false,"direct_debit_mandate":false,"direct_debit_mandate_id":false,"direct_debit_sequence_type":false,"receiving_agent_account":false,"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.generic"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.generic"}}}]},"payment_order.creation_details.other":{"title":"Other","allOf":[{"$ref":"#/components/schemas/payment_order.creation_details"},{"type":"object","required":["type"],"properties":{"type":{"enum":["ae_aani","ae_uaefts","ae_uaefts_rtgs","ar_coelsa","ar_mep","ar_transfer_30","au_becs","au_npp","au_rits","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","cl_cca","cl_lbtr","cl_tef","co_ach","co_bre_b","co_cud","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","sg_giro","sg_meps","sg_paynow","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"]},"direction":{"enum":["credit","debit"]},"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account.other"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account.other"},"receiving_agent_account":false}}]},"payment_order.update_details":{"type":"object","properties":{"status":{"type":"string","description":"The new status of this payment order. See [payment order's lifecycle](ref:payment-order-lifecycle).","enum":["executed","rejected","returned"]},"status_details":{"type":"string","description":"The details of the status of this payment order. Required if `status` is provided.","maxLength":1000,"example":"some specific reason"},"retry_details":{"type":"object","description":"Information about the payment order retries.","properties":{"payment_retry_rule_id":{"type":"string","description":"The ID of the payment retry rule to be attached to the payment order. See [payment retry rule](ref:payment-retry-rule-object).\n\nThe payment retry rule must be compatible with `payment_type` and `payment_direction`.\n\nThe payment order must have `pending_approval` status.\n"}}},"metadata":{"<<":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"description":"Additional client data in JSON format. See [Metadata](ref:metadata). Required if `status` is not provided."},"custom_fields":{"$ref":"#/components/schemas/common.custom_fields"}}},"payment_order.manual_retry_creation":{"type":"object","properties":{"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account from which the new payment is sent. Only authorized for SCT, SCT Inst, Bacs and FPS.","example":"24e3157c-4942-11ed-b878-0242ac120002"},"type":{"type":"string","enum":["sepa","sepa_instant","bacs","fps","swift"],"description":"The type of the new payment. An SCT payment can be retried to an SCT Inst, and an SCT Inst payment can be retried to an SCT.","example":"sepa"},"requested_execution_date":{"type":"string","description":"The requested execution date of the new payment. Only authorized for SDD.","format":"date","example":"2022-01-03"}}},"payment_order.charges_information":{"type":"array","maxItems":10,"description":"Charges or fees being applied to the payment order. Only applicable to `swift` and `target2` payment orders sent from a connected account of type `financial_institution`.","items":{"type":"object","required":["amount","currency","agent"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"description":"Charges amount being applied, in the specified currency's smallest units.","example":50},"currency":{"type":"string","description":"Charges currency being applied. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes should be used.","example":"EUR"},"agent":{"type":"object","description":"Agent responsible to bear the charges.","required":["bank_code","bank_code_format"],"properties":{"bank_code":{"type":"string","description":"BIC or domestic bank code of the agent bearing the charges.","example":"SOMEBIC0XXX"},"bank_code_format":{"type":"string","description":"The bank code format of the agent bearing the charges. It determines whether `bank_code` is written as a BIC or as a domestic member ID in the outgoing message. It must match `bank_code` unless the format is `other` or `tokenized`.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"name":{"type":"string","description":"Name of the agent bearing the charges.","example":"Some Bank"}}}}}},"payment_order.details":{"type":"object","required":["id","status","status_details","auto_approval","object","created_at","reconciled_amount","reconciliation_status","type","direction","amount","currency","connected_account_id","originating_account","receiving_account","bank_data","value_date","idempotency_key","reference","metadata","custom_fields"],"properties":{"id":{"type":"string","format":"uuid","example":"b69837bf-e784-4bd1-b0d0-2ad0e61a89b6","description":"The UUID of the payment order."},"idempotency_key":{"type":"string","description":"An idempotency key is a unique value sent by the client, which the server uses to recognize subsequent retries of the same request.","example":"8A2gcC"},"object":{"type":"string","description":"Type of the object, `payment_order`.","default":"payment_order","example":"payment_order"},"type":{"$ref":"#/components/schemas/payment_type"},"direction":{"type":"string","description":"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.","default":"credit","enum":["credit","debit"],"example":"credit"},"amount":{"type":"integer","description":"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`.","format":"int64","minimum":0,"example":2000},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code, in lowercase. Only `EUR` is supported for now.","enum":["EUR"],"example":"EUR"},"instructed_amount":{"type":"integer","format":"int64","minimum":0,"nullable":true,"description":"Instructed amount of the payment order, in the specified currency's smallest units. It may differ from the `amount` when charges are deducted along the payment chain. Only filled for `swift` and `target2` payment orders sent from a connected account of type `financial_institution`, where it defaults to the `amount` attribute.","example":2050},"instructed_amount_currency":{"type":"string","nullable":true,"description":"Instructed amount currency of the payment order ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)). Only filled for `swift` and `target2` payment orders sent from a connected account of type `financial_institution`, where it defaults to the `currency` attribute.","example":"EUR"},"charges_information":{"$ref":"#/components/schemas/payment_order.charges_information"},"value_date":{"type":"string","description":"The value date of the payment order.","format":"date","example":"2022-01-03"},"status":{"type":"string","example":"executed","description":"The lifecycle stage of this payment order. It will be updated as the payment order is processed. See [payment order's lifecycle](ref:payment-order-lifecycle)."},"status_details":{"type":"string","example":"","description":"The details of the status of this payment order."},"reconciled_amount":{"type":"integer","format":"int64","example":2000,"description":"The reconciled amount.","minimum":0},"reconciliation_status":{"type":"string","enum":["partially_reconciled","reconciled","unreconciled","excluded"],"description":"The reconciliation status of the payment order, which is either `unreconciled`, `reconciled`, `partially_reconciled`, or `excluded`.","example":"reconciled"},"reference":{"type":"string","maxLength":140,"description":"The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.","example":"Invoice 1234"},"end_to_end_id":{"type":"string","description":"The end-to-end ID of the payment order. Only supported for specific banks and payment schemes. Contact us to get more details.","maxLength":35,"example":"c3b2d737bc"},"connected_account_id":{"type":"string","format":"uuid","example":"254e3100-afd6-44f2-8084-87e8ae67b554","description":"The ID of the connected account. The connected account is the account used to trigger the payment order."},"originating_account":{"$ref":"#/components/schemas/payment_order.originating_account"},"originating_account_id":{"type":"string","format":"uuid","description":"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”.\n","example":"8d97ed83-a6f7-4929-8e90-01b2912fb6a7"},"ultimate_originator":{"$ref":"#/components/schemas/payment_order.ultimate_originator"},"receiving_account":{"$ref":"#/components/schemas/payment_order.receiving_account"},"receiving_account_id":{"type":"string","format":"uuid","example":"b38f5318-a389-4278-9cbe-d16116750982","description":"The ID of the `external_account` receiving the payment instruction.\n"},"ultimate_receiver":{"$ref":"#/components/schemas/payment_order.ultimate_receiver"},"direct_debit_mandate":{"$ref":"#/components/schemas/payment_order.direct_debit_mandate"},"direct_debit_mandate_id":{"type":"string","format":"uuid","description":"The mandate's ID authorizing the direct debit. This attribute is filled only when the payment order's `direction` is `debit`.","example":"15ee5994-9019-478c-b27a-a4edfec17c58"},"direct_debit_sequence_type":{"$ref":"#/components/schemas/payment_order.direct_debit_sequence_type"},"intermediary_agents":{"$ref":"#/components/schemas/common.intermediary_agents"},"previous_instructing_agents":{"$ref":"#/components/schemas/common.previous_instructing_agents"},"receiving_agent_account":{"$ref":"#/components/schemas/common.receiving_agent_account"},"uetr":{"type":"string","format":"uuid","description":"Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI."},"swift_gpi":{"$ref":"#/components/schemas/payment_order.swift_gpi_details"},"purpose":{"type":"string","description":"The purpose code of the payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to `swift` and `chaps` payment types.","example":"SALA"},"category_purpose_code":{"type":"string","description":"The category purpose of the payment. Recommended for CHAPS payments.","example":"B2B"},"fee_option":{"type":"string","enum":["originator","receiver","shared"],"description":"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).","example":"shared"},"routing_instruction":{"type":"string","description":"Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to `swift` payments.","example":"Cross-border routing instructions"},"requested_execution_date":{"type":"string","description":"The requested execution date of the payment order.","format":"date","example":"2022-01-03"},"auto_approval":{"type":"boolean","default":false,"description":"The `auto_approval` flag determines whether a payment requires human intervention before execution.\n\nWhen `true`: The system bypasses all manual approval steps.\n- If a validation rule applies, the payment starts as `pending_approval`.\n- If no rules apply, the payment is immediately `approved`.\n\nWhen `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.\n","example":false},"payment_validation":{"type":"object","description":"Information about the payment validation, like the validation rules and validation statuses. `null` if no payment validation rule is attached to the payment order.","required":["status","validation_results"],"properties":{"status":{"type":"string","description":"The aggregated status of payment validation for this payment.","enum":["in_progress","successful","failed"]},"validation_results":{"type":"array","description":"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.","items":{"$ref":"#/components/schemas/common.payment_validation_result"}}}},"cbs_data":{"$ref":"#/components/schemas/common.cbs_data"},"retry_details":{"$ref":"#/components/schemas/payment_order.retry_details"},"treasury_option":{"type":"string","enum":["local","international","relocated","safeguarding"],"description":"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).","example":"local"},"confidentiality_option":{"type":"string","enum":["payroll"],"description":"Used in case of a confidential payment. Only `payroll` confidential payments are supported for now.","example":"payroll"},"settlement_method":{"type":"string","enum":["cover","instructed_agent","instructing_agent"],"description":"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.","example":"cover"},"settlement_information":{"$ref":"#/components/schemas/payment_order.settlement_information"},"fi_to_fi_option":{"type":"string","enum":["advi","core","cover"],"description":"The `fi_to_fi_option` attribute is mandatory when creating payment orders with type = `swift_fi_to_fi` or `target2_fi_to_fi`.","example":"core"},"related_payment_id":{"type":"string","format":"uuid","example":"a815e756-5576-4d40-9fbd-38ec304b856c","description":"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":{"type":"string","description":"Auto-filled based on the `related_payment_id`."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"custom_fields":{"$ref":"#/components/schemas/common.custom_fields"},"bank_data":{"type":"object","description":"Bank data, such as message and transaction IDs, in JSON format.","required":["file_id","message_id","transaction_id","end_to_end_id"],"properties":{"file_id":{"type":"string","format":"uuid","example":"a815e756-5576-4d40-9fbd-38ec304b856c"},"message_id":{"type":"string","example":"1gXrtKMxLJ"},"transaction_id":{"type":"string","example":"1zDrzOMxCJ"},"end_to_end_id":{"type":"string","example":"c3b2d737bc"}}},"initiated_at":{"type":"string","format":"date-time","example":"2022-01-03T11:53:19.568Z","description":"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":{"type":"string","nullable":true,"description":"Instructed agent of the payment order, either supplied at create time or filled automatically by Mambu Payments based on the payment's target scheme, correspondent bank or receiving account. For Swift payment orders, a value supplied at create time overrides the correspondent bank matched on the payment currency and is reported as the `AppHdr.To.FIId.FinInstnId.BICFI` and `InstdAgt.FinInstnId.BICFI` of the generated pacs.008 / pacs.009.\n","example":"SOMEBIC0XXX"},"addressee_bank_code":{"type":"string","nullable":true,"description":"Addressee BIC of the payment order, either supplied at create time or filled automatically by Mambu Payments based on the payment's target scheme, correspondent bank or receiving account.\n","example":"SOMEBIC0XXX"},"correspondent_bank_id":{"type":"string","format":"uuid","nullable":true,"description":"Correspondent bank ID applied to this payment order, either supplied by the customer at create time or auto-resolved at batching time from the legal entity's active correspondent banking rules. Only populated for Swift payments.\n"},"correspondent_bank_account_id":{"type":"string","format":"uuid","nullable":true,"description":"Correspondent bank account ID applied to this payment order. See `correspondent_bank_id` for resolution behaviour.\n"},"correspondent_banking_rule_id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the correspondent banking rule the correspondent bank and account above were resolved from at batching time. Null when the customer supplied the correspondent themselves at create time, as no rule was applied then.\n"},"created_at":{"type":"string","format":"date-time","example":"2022-01-03T11:53:19.734182Z","description":"The UTC timestamp of the creation of this payment order."}}},"payment_order.cancelation_details":{"type":"object","properties":{"reason":{"type":"string","description":"Reason code for the cancelation. Only used when canceling SEPA direct debit payment orders before settlement.","example":"DUPL"}}},"payment_order.search_result":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/payment_order.details"}}}},"incoming_payment.originating_account":{"type":"object","description":"The account from which the payment originates. This field is available only to financial institution customers and specific authorized 4th-party payments. For corporate customers, the originating account is automatically derived from the connected account information and must be left empty.","required":["bank_code","holder_name","creditor_identifier"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"The account number, for example an IBAN. Always present only for incoming payments types other than `swift_fi_to_fi` or `target2_fi_to_fi`."},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code. For example, a BIC or SWIFT code."},"fi_bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The `fi_bank_code` attribute is only set for incoming payments where type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/incoming_payment.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"creditor_identifier":{"type":"string","description":"The unique reference for organisations collecting payments by SEPA Direct Debit.","example":"FR12ZZZ123456"},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the originating account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the originating account. Not allowed if `organization_identification` is filled."}}},"incoming_payment.receiving_account":{"type":"object","description":"The receiving account of the payment.","required":["bank_code","holder_name"],"properties":{"account_number":{"type":"string","example":"FR7601234567891127967100082","description":"The account number, for example an IBAN. Always present only for incoming payments types other than `swift_fi_to_fi` or `target2_fi_to_fi`."},"bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The bank code. For example, a BIC or SWIFT code."},"fi_bank_code":{"type":"string","example":"BNPAFRPPXXX","description":"The `fi_bank_code` attribute is only set for incoming payments where type = `swift_fi_to_fi` or `target2_fi_to_fi`."},"holder_name":{"type":"string","example":"PartnerCo","description":"The name of the legal entity or individual holding the account."},"holder_address":{"$ref":"#/components/schemas/incoming_payment.address"},"bank_name":{"type":"string","example":"BankCo","description":"The name of the bank holding the account."},"bank_address":{"$ref":"#/components/schemas/common.address","description":"The address of the bank holding the account."},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the receiving account. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the receiving account. Not allowed if `organization_identification` is filled."}}},"incoming_payment.ultimate_originator":{"type":"object","description":"The ultimate originating account of the payment (sometimes called ultimate debtor for a credit transfer or ultimate creditor for a direct debit).","properties":{"holder_name":{"type":"string","example":"SoftwareCo","description":"The account holder name of the ultimate originator."},"holder_address":{"$ref":"#/components/schemas/common.address"},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the ultimate originator. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the ultimate originator account. Not allowed if `organization_identification` is filled."}}},"incoming_payment.ultimate_receiver":{"type":"object","description":"The ultimate receiving account of the payment (sometimes called ultimate creditor for a credit transfer or ultimate debtor for a direct debit).","properties":{"holder_name":{"type":"string","example":"SoftwareCo","description":"The account holder name of the ultimate receiver."},"holder_address":{"$ref":"#/components/schemas/common.address"},"organization_identification":{"$ref":"#/components/schemas/organization_identification","description":"The organization identification of the ultimate receiver. Not allowed if `private_identification` is filled."},"private_identification":{"$ref":"#/components/schemas/private_identification","description":"The private identification of the ultimate receiver account. Not allowed if `organization_identification` is filled."}}},"incoming_payment.creditor_reference_type":{"type":"object","description":"Specifies the type of creditor reference.","properties":{"code":{"type":"string","description":"Type of creditor reference.","enum":["dispatch_advice","foreign_exchange_deal_reference","purchase_order","related_payment_instruction","remittance_advice_message","structured_communication_reference","other"],"example":"dispatch_advice"},"issuer":{"type":"string","description":"Entity that assigns the credit reference type.","example":"Issuer"}}},"incoming_payment.creditor_reference_information":{"type":"object","description":"Reference information provided by the creditor to allow the identification of the underlying documents.","properties":{"type":{"$ref":"#/components/schemas/incoming_payment.creditor_reference_type"},"reference":{"type":"string","description":"Unique and unambiguous identification of the referred document.","example":"RF18539007547034"}}},"incoming_payment.referred_document_type":{"type":"object","description":"Specifies the type of referred document.","properties":{"code":{"type":"string","description":"Type of referred document.","enum":["commercial_invoice","credit_note_related_to_financial_adjustment","contract","credit_note","debit_note","dispatch_advice","debit_note_related_to_financial_adjustment","hire_invoice","invoice_signed","metered_service_invoice","proforma_invoice","purchase_order","quotation","self_billed_invoice","seller_presentment","time_sheet","usage_report","account_receivable_open_item","bill_of_lading","commercial_contract","statement_of_account","trade_services_utility_transaction","voucher","other"],"example":"commercial_invoice"},"issuer":{"type":"string","description":"Identification of the issuer of the reference document type.","example":"Issuer"}}},"incoming_payment.referred_document_information":{"type":"object","description":"The identification and the content of the referred document","properties":{"type":{"$ref":"#/components/schemas/incoming_payment.referred_document_type"},"number":{"type":"string","description":"Unique and unambiguous identification of the referred document.","example":"ABC-13679"},"related_date":{"type":"string","format":"date","description":"Date associated with the referred document.","example":"2024-03-15"}}},"incoming_payment.structured_reference":{"type":"array","description":"Structured reference data\n","items":{"type":"object","description":"One structured remittance reference block from the payment","properties":{"creditor_reference_information":{"$ref":"#/components/schemas/incoming_payment.creditor_reference_information"},"referred_document_information":{"type":"array","items":{"$ref":"#/components/schemas/incoming_payment.referred_document_information"}},"invoicer":{"description":"Identification of the organisation issuing the invoice.","type":"object","properties":{"name":{"type":"string","description":"Name by which a party is known and which is usually used to identify that party.","example":"Invoicer name"}}},"invoicee":{"description":"Identification of the party to whom an invoice is issued.","type":"object","properties":{"name":{"type":"string","description":"Name by which a party is known and which is usually used to identify that party.","example":"Invoicee name"}}},"additional_remittance_info":{"type":"array","description":"Additional information, in free text form, to complement the structured remittance information.","items":{"type":"string","example":"Payment for invoice INV-2024-001"}}}}},"incoming_payment.address":{"type":"object","description":"The address of the account holder.","properties":{"line_1":{"type":"string","description":"Line 1.","example":""},"line_2":{"type":"string","description":"Line 2.","example":""},"building_number":{"type":"string","description":"Building number.","example":"1"},"street_name":{"type":"string","description":"Street name.","example":"rue de l'Abondance"},"postal_code":{"type":"string","description":"Postal / zip code.","example":"69003"},"region_state":{"type":"string","description":"Region or state.","example":"Ile-de-France"},"city":{"type":"string","description":"City.","example":"Lyon"},"country":{"type":"string","description":"ISO 3166 alpha-2 country code.","example":"FR"},"department":{"type":["string","null"],"description":"Department name or code.","example":"Marketing"},"sub_department":{"type":["string","null"],"description":"Sub-department name.","example":"Content team"},"building_name":{"type":["string","null"],"description":"Name of the building.","example":"Bat. 4"},"floor":{"type":["string","null"],"description":"Floor number or identifier.","example":"3"},"postal_box":{"type":["string","null"],"description":"Postal box.","example":"67b"},"room":{"type":["string","null"],"description":"Room number.","example":"47"},"city_location_name":{"type":["string","null"],"description":"Specific city location or landmark.","example":"Confluences"},"district_name":{"type":["string","null"],"description":"District name or administrative region.","example":"District 9"}}},"incoming_payment.charges_information":{"type":"array","description":"Charges or fees applied to the incoming payment, as received from the sending bank. Only applicable to `swift` and `target2` incoming payments.","items":{"type":"object","required":["amount","currency","agent"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"description":"Charges amount applied, in the specified currency's smallest units.","example":50},"currency":{"type":"string","description":"Charges currency applied. [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes should be used.","example":"EUR"},"agent":{"type":"object","description":"Agent bearing the charges.","properties":{"bank_code":{"type":"string","description":"BIC or domestic bank code of the agent bearing the charges.","example":"SOMEBIC0XXX"},"bank_code_format":{"type":"string","description":"The bank code format of the agent bearing the charges. `other` is used when the sending bank identified the agent through a domestic clearing system code we cannot map to a more specific format.","enum":["bic","uk_sorting_code","us_aba_routing_number","tokenized","other"],"example":"bic"},"name":{"type":"string","description":"Name of the agent bearing the charges.","example":"Some Bank"}}}}}},"incoming_payment.details":{"type":"object","required":["id","status","status_details","object","created_at","reconciled_amount","reconciliation_status","type","direction","amount","currency","connected_account_id","originating_account","receiving_account","receiving_account_id","bank_data","value_date","requested_execution_date","idempotency_key","reference","direct_debit_mandate","direct_debit_mandate_id","direct_debit_sequence_type","metadata","initiated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The UUID of the incoming payment."},"status":{"type":"string","enum":["received","pending_approval","pending_return","returned","rejected","pending_confirmation","confirmed","pending_rejection"],"example":"received","description":"The lifecycle stage of this incoming payment. It will be updated as the incoming payment is processed. See [incoming payment's lifecycle](ref:incoming-payment-lifecycle)."},"status_details":{"type":"string","description":"The details of the status of this incoming payment.","example":""},"object":{"type":"string","description":"Type of the object, `incoming_payment`.","default":"incoming_payment","example":"incoming_payment"},"idempotency_key":{"type":"string","description":"An idempotency key is a unique value sent by the client, which the server uses to recognize subsequent retries of the same request.","example":"8A2gcC"},"bank_data":{"type":"object","description":"Bank data, such as message and transaction IDs, in JSON format.","required":["file_id","message_id","transaction_id","end_to_end_id"],"properties":{"file_id":{"type":"string","format":"uuid","example":"a815e756-5576-4d40-9fbd-38ec304b856c"},"message_id":{"type":"string","example":"1gXrtKMxLJ"},"transaction_id":{"type":"string","example":"1zDrzOMxCJ"},"end_to_end_id":{"type":"string","example":"c3b2d737bc"}}},"reconciliation_status":{"type":"string","enum":["partially_reconciled","reconciled","unreconciled","excluded"],"description":"The reconciliation status of the incoming payment, which is either `unreconciled`, `reconciled`, `partially_reconciled`, or `excluded`.","example":"partially_reconciled"},"initiated_at":{"type":"string","format":"date-time","description":"The payment order initiation UTC timestamp with ISO 8601 format to the milliseconds without trailing zeros. Only supported for `sepa_instant` payments.","example":"2024-04-12T14:23:45.123Z"},"reconciled_amount":{"type":"integer","format":"int64","example":1500,"minimum":0,"description":"The reconciled amount."},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of this incoming payment."},"type":{"$ref":"#/components/schemas/payment_type"},"direction":{"type":"string","description":"Either credit or debit. Describes the direction the money is flowing. A credit moves money from someone else's account to your account. A debit moves money from your account to someone else's account. An incoming payment of type:sepa and direction:credit is a SEPA Credit Transfer (SCT). An incoming payment of type:sepa and direction:debit is a SEPA Direct Debit (SDD). Only credit is supported for now.","default":"credit","enum":["credit"],"example":"credit"},"amount":{"type":"integer","description":"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`.","format":"int64","minimum":0,"example":3000},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code, in lowercase. Only `EUR` is supported for now.","enum":["EUR"],"example":"EUR"},"instructed_amount":{"type":"integer","format":"int64","minimum":0,"nullable":true,"description":"Instructed amount of the incoming payment, in the specified currency's smallest units, as received from the sending bank. It may differ from `amount` when charges are deducted along the payment chain. Only filled for `swift` and `target2` incoming payments, and only when the sending bank provided it.","example":2050},"instructed_amount_currency":{"type":"string","nullable":true,"description":"Instructed amount currency of the incoming payment ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)), as received from the sending bank. Only filled for `swift` and `target2` incoming payments, and only when the sending bank provided it.","example":"EUR"},"charges_information":{"$ref":"#/components/schemas/incoming_payment.charges_information"},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account that receives the incoming payment."},"originating_account":{"$ref":"#/components/schemas/incoming_payment.originating_account"},"receiving_account":{"$ref":"#/components/schemas/incoming_payment.receiving_account"},"ultimate_originator":{"$ref":"#/components/schemas/incoming_payment.ultimate_originator"},"ultimate_receiver":{"$ref":"#/components/schemas/incoming_payment.ultimate_receiver"},"receiving_account_id":{"type":"string","format":"uuid","description":"The ID of the internal account that receives the incoming payment."},"reference":{"type":"string","maxLength":140,"description":"The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.","example":"Invoice 1234"},"structured_reference":{"$ref":"#/components/schemas/incoming_payment.structured_reference"},"value_date":{"type":"string","description":"The value date of the incoming payment.","format":"date"},"requested_execution_date":{"type":"string","description":"The requested execution date of the incoming payment.","format":"date"},"purpose":{"type":"string","description":"The purpose code of the incoming payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to `swift` and `chaps` payment types.","example":"SALA"},"category_purpose_code":{"type":"string","description":"The category purpose of the incoming payment. Recommended for CHAPS payments.","example":"B2B"},"local_instrument":{"type":"string","description":"The local instrument code of the incoming payment, as carried in the underlying scheme message.","example":"INST"},"uetr":{"type":"string","format":"uuid","description":"Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI."},"direct_debit_mandate":{"type":["object","null"],"description":"The mandate authorizing the direct debit.","required":["reference","signature_date","type"],"properties":{"reference":{"type":"string","description":"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.","maxLength":35,"example":"REF-783232"},"signature_date":{"type":"string","description":"The signature date of the mandate.","format":"date"},"last_debit_collection_date":{"type":["string","null"],"format":"date","description":"The date of the last direct debit collection processed against this mandate."},"expiry_date":{"type":["string","null"],"format":"date","description":"The date after which the mandate is expired and cannot be used for subsequent direct debit collections."},"type":{"type":"string","description":"The type of the mandate.","enum":["sepa_core","sepa_b2b","bacs_debit"]},"sequence":{"type":"string","description":"Deprecated, use `frequency` instead.","deprecated":true,"enum":["one_off","recurring"],"example":"recurring"},"frequency":{"type":"string","description":"The frequency of the mandate, either `one_off` or `recurring`. Mandatory when type is `sepa_core` or `sepa_b2b`.","enum":["one_off","recurring"],"example":"recurring"}}},"direct_debit_mandate_id":{"type":"string","description":"The ID of the incoming payment’s direct debit mandate.","format":"uuid"},"direct_debit_sequence_type":{"$ref":"#/components/schemas/payment_order.direct_debit_sequence_type"},"intermediary_agents":{"$ref":"#/components/schemas/common.intermediary_agents"},"previous_instructing_agents":{"$ref":"#/components/schemas/common.previous_instructing_agents"},"routing_instruction":{"type":"string","description":"Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to `swift` payments.","example":"Cross-border routing instructions"},"payment_validation":{"type":"object","description":"Information about the payment validation, like the validation rules and validation statuses. `null` if no payment validation rule is attached to the incoming payment.","required":["status","validation_results"],"properties":{"status":{"type":"string","description":"The aggregated status of payment validation for this payment.","enum":["in_progress","successful","failed"]},"validation_results":{"type":"array","description":"Array of objects detailing the results of payment validation for a given payment validation rule. If the incoming payment has 2 rules attached, then this array will contain 2 objects.","items":{"$ref":"#/components/schemas/common.payment_validation_result"}}}},"cbs_data":{"$ref":"#/components/schemas/common.cbs_data"},"instructing_agent":{"type":"string","description":"When applicable, the instructing agent, or financial institution having sent the incoming payment."},"instructed_agent":{"type":"string","description":"When applicable, the instructed agent, or financial institution having received the incoming payment."},"settlement_method":{"type":"string","description":"When applicable, the settlement method of the incoming payment, whether `instructing_agent`, `instructed_agent`, or `cover`.","example":"cover"},"instructing_settlement_agent":{"type":"string","description":"The instructing settlement agent. Only applicable to swift payments."},"instructed_settlement_agent":{"type":"string","description":"The instructed settlement agent. Only applicable to swift payments."},"fee_option":{"type":"string","description":"Network payment fee preference. Only applicable to Swift payments such as `originator` (fee beared by the originating party), `receiver` (fee beared by the receiving party), or `shared` (fee split between the originating and the receiving parties)."},"fi_to_fi_option":{"type":"string","enum":["advi","core","cover"],"description":"Filled for incoming payments with type = `swift_fi_to_fi` or `target2_fi_to_fi`.","example":"core"},"related_payment_id":{"type":"string","format":"uuid","example":"a815e756-5576-4d40-9fbd-38ec304b856c","description":"Auto-filled for incoming payments with type = `swift_fi_to_fi` or `target2_fi_to_fi` and fi_to_fi_option = `cover`. If no related payment can be found by our system `related_payment_id`, and consequently `related_payment_type`, will be empty. In this case `related_payment` will contain data about the related payment."},"related_payment_type":{"type":"string","description":"The type of the related payment. Only filled when `related_payment_id` could be determined by our system."},"related_payment":{"type":"object","description":"See `related_payment_id` for details about when this property is present. If it's present, it will have the same properties as it's encompassing object (incoming payment)."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}}}},"incoming_payment.search_result":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/incoming_payment.details"}}}},"incoming_payment.update":{"type":"object","properties":{"receiving_account_id":{"type":"string","format":"uuid","description":"ID of the internal account to be matched as receiving account of the payment. Can only be set when incoming payment is recevied and has no `receiving_account_id`. Internal account must be `active` and linked to the incoming payment's connected account."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}}}},"incoming_payment.reject_details":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes)."}}},"incoming_payment.track_details":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["rejected","pending","executed","received"],"description":"Swift GPI tracker status.","example":"executed"},"status_code":{"type":"string","enum":["G000","G001","G002","G003","G004"],"description":"Swift GPI tracker status details, only mandatory when the status is \"pending\" or \"executed\". Includes native GPI codes.","example":"G001"},"rejection_reason_code":{"type":"string","description":"4 alphanumerical characters Swift GPI rejection code, only mandatory when the status is “rejected”.","example":"AC04"}}},"return.creation_details":{"type":"object","required":["related_payment_id","return_reason"],"properties":{"related_payment_id":{"type":"string","format":"uuid","description":"The ID of the incoming payment to be returned."},"return_reason":{"type":"string","description":"Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes). For FPS, refer to the 8 digits [FPS return reason codes](https://docs.numeral.io/reference/fps-reason-codes#return-reason-codes).\n","example":"AC06"},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"related_payment_suspended":{"type":"boolean","default":false,"description":"Indicates whether the funds should be debited from your suspense account or the customer account.\n`false` by default (i.e. funds will be debited on your customer account).\n"}}},"return.details":{"type":"object","required":["id","object","type","return_type","connected_account_id","related_payment_id","related_payment_type","direction","return_reason","status","status_details","metadata","bank_data","value_date","returned_amount","currency","receiving_account_number","reconciliation_status","reconciled_amount","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The UUID of the return."},"object":{"type":"string","enum":["return"],"description":"Label used to identify this kind of object","example":"return"},"type":{"type":"string","enum":["sepa","sepa_instant"],"description":"The payment scheme or network. Only `sepa` and `sepa_instant` are supported for now."},"direction":{"type":"string","description":"The direction of the return. `credit` for credit transfer returns (SCT/SCT Inst), and `debit` for direct debit returns (SDD).","enum":["credit","debit"]},"return_type":{"type":"string","description":"The type of the return. Authorized values include `return`, `refund` and `reversal`. Only available when related payment is a direct debit.","enum":["return","refund","reversal"]},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account."},"related_payment_id":{"type":"string","format":"uuid","description":"The ID of the payment being returned, either an incoming payment or a payment order."},"related_payment_type":{"type":"string","enum":["payment_order","incoming_payment"],"description":"The type of the payment corresponding to the return. It can be an [incoming payment](ref:incoming-payment-object) or a [payment order](ref:payment-order-object)."},"return_reason":{"type":"string","description":"The reason for returning the payment. Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes). For FPS, use one of the following 8-digit codes:\n- `00000001`: Beneficiary Sort Code/Account Number Unknown\n- `00000002`: Beneficiary Account Closed\n- `00000003`: Beneficiary Account Stopped\n- `00000004`: Beneficiary deceased\n- `00000005`: Account cannot be identified without data in Reference Information Field\n- `00000006`: Beneficiary Account Name does not match Beneficiary Account Number\n- `00000007`: Return requested by sender of original payment\n- `00000008`: Account is not in currency quoted\n- `00000009`: Beneficiary not expecting funds/instructed return\n- `00000010`: Terms and Conditions of Account do not permit crediting of these funds\n- `00000011`: Sending FPS Institution action required\n- `00000012`: Account Transferred\n- `00000013`: Payment cannot be applied because of Beneficiary sensitivities\n- `00000014`: Other\n"},"status":{"type":"string","enum":["received","pending_approval","approved","canceled","failed","processing","sent","executed","rejected"],"description":"The lifecycle stage of this return. It will be updated as the return is processed. See [return's lifecycle](ref:return-lifecycle)."},"status_details":{"type":"string","description":"The details of the status of this return."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"bank_data":{"type":"object","description":"Bank data, such as message and transaction IDs, in JSON format.","required":["file_id","message_id","transaction_id","end_to_end_id"],"properties":{"file_id":{"type":"string","format":"uuid"},"message_id":{"type":"string"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":"string"}}},"value_date":{"type":"string","format":"date","description":"The value date of the return."},"returned_amount":{"type":"integer","format":"int64","description":"The absolute value of the return in the specified currency's smallest unit.\nFor euro payments, the smallest unit is cents. €20 is represented as 2000.\n"},"currency":{"type":"string","enum":["EUR"],"description":"The currency of the return. Only `EUR` is supported for now."},"instructed_amount":{"type":"integer","format":"int64","minimum":0,"nullable":true,"description":"Instructed amount of the return, in the specified currency's smallest units. It may differ from `returned_amount` when charges are deducted along the payment chain. Only filled for `swift` and `target2` returns.","example":2050},"instructed_amount_currency":{"type":"string","nullable":true,"description":"Instructed amount currency of the return ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)). Only filled for `swift` and `target2` returns.","example":"EUR"},"fee_option":{"type":"string","nullable":true,"description":"Network payment fee preference. Only applicable to `swift` and `target2` returns, such as `originator` (fee beared by the originating party), `receiver` (fee beared by the receiving party), or `shared` (fee split between the originating and the receiving parties).","enum":["originator","receiver","shared"]},"receiving_account_number":{"type":"string","description":"The account receiving the return."},"originating_account_number":{"type":"string","description":"The account number of the originator of the return."},"originating_account_holder_name":{"type":"string","description":"The holder name of the originating account."},"originating_account_bank_name":{"type":"string","nullable":true,"description":"The bank name of the originating account."},"originating_account_bank_address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/common.address"}],"description":"The bank address of the originating account."},"receiving_account_bank_name":{"type":"string","nullable":true,"description":"The bank name of the receiving account."},"receiving_account_bank_address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/common.address"}],"description":"The bank address of the receiving account."},"reconciliation_status":{"type":"string","enum":["unreconciled","partially_reconciled","reconciled","excluded"],"description":"The reconciliation status of the return, which is either `unreconciled`, `reconciled`, `partially_reconciled`, or `excluded`."},"reconciled_amount":{"type":"integer","format":"int64","description":"The amount that is already reconciled.\nIt is the sum of the amount of the reconciliations related to this return.\n"},"payment_validation":{"type":"object","description":"Information about the payment validation, like the validation rules and validation statuses. `null` if no payment validation rule is attached to the return.","required":["status","validation_results"],"properties":{"status":{"type":"string","description":"The aggregated status of payment validation for this payment.","enum":["in_progress","successful","failed"]},"validation_results":{"type":"array","description":"Array of objects detailing the results of payment validation for a given payment validation rule. If the return has 2 rules attached, then this array will contain 2 objects.","items":{"$ref":"#/components/schemas/common.payment_validation_result"}}}},"cbs_data":{"$ref":"#/components/schemas/common.cbs_data"},"charges_information":{"type":"array","description":"Contains the charges or fees that could be included as part of a return.","items":{"$ref":"#/components/schemas/common.charges_information_item"},"example":[{"amount":1000,"currency":"EUR","agent":{"bank_code":"SOGEFRPP","name":"Société Générale"}}]},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of this return."}}},"return.cancel_details":{"type":"object","properties":{"reason":{"type":"string","description":"Cancelation reason."}}},"return.update_details":{"type":"object","properties":{"status":{"type":"string","description":"The new status of this return. See [return's lifecycle](ref:return-lifecycle).","enum":["executed","rejected"],"example":"rejected"},"status_details":{"type":"string","description":"The details of the status of this return. Required if `status` is provided.","maxLength":1000,"example":"DUPL"},"metadata":{"<<":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"description":"Additional client data in JSON format. See [Metadata](ref:metadata). Required if `status` is not provided."}}},"return.search_result":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/return.details"}}}},"return_request.creation_details":{"type":"object","required":["related_payment_id","return_reason"],"properties":{"related_payment_id":{"type":"string","format":"uuid","description":"The ID of the payment order to be returned."},"return_reason":{"type":"string","description":"Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes).","example":"AM05"},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}}}},"return_request.deny_details":{"type":"object","required":["return_reason"],"properties":{"return_reason":{"type":"string","description":"Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes)."}}},"return_request.details":{"type":"object","required":["id","object","type","connected_account_id","related_payment_id","related_payment_type","return_reason","status","status_details","metadata","bank_data","created_at","additional_information"],"properties":{"id":{"type":"string","format":"uuid","description":"The UUID of the return request."},"object":{"type":"string","enum":["return_request"],"description":"Label used to identify this kind of object","example":"return_request"},"type":{"type":"string","enum":["sepa","sepa_instant"],"description":"The payment scheme or network. Only `sepa` and `sepa_instant` are supported for now."},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account."},"related_payment_id":{"type":"string","format":"uuid","description":"The ID of the payment being returned, either an incoming payment or a payment order."},"related_payment_type":{"type":"string","enum":["payment_order","incoming_payment"],"description":"The type of the payment corresponding to the return request. It can be an [incoming payment](ref:incoming-payment-object) or a [payment order](ref:payment-order-object)."},"return_reason":{"type":"string","description":"The reason for asking the payment's return. Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](ref:sepa-reason-codes)."},"status":{"type":"string","enum":["received","accepted","denied","rejected","pending","failed","sent"],"description":"The lifecycle stage of this return request. It will be updated as the return request is processed. See [return request's lifecycle](ref:return-request-lifecycle)."},"status_details":{"type":"string","description":"The details of the status of this return request."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"bank_data":{"type":"object","description":"Bank data, such as message and transaction IDs, in JSON format.","required":["file_id","message_id","transaction_id","end_to_end_id"],"properties":{"file_id":{"type":"string","format":"uuid"},"message_id":{"type":"string"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":"string"}}},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of this return request."},"additional_information":{"type":"array","items":{"type":"string"},"description":"Additional free-text information provided by the bank when denying a return request (populated from the `<AddtlInf>` field of the inbound camt.029 message). Empty array when no additional information was provided.","example":["Insufficient funds","Account closed"]}}},"return_request.search_result":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/return_request.details"}}}},"return_request.accept_response":{"type":"object","required":["return","return_request"],"properties":{"return":{"$ref":"#/components/schemas/return.details"},"return_request":{"$ref":"#/components/schemas/return_request.details"}}}},"examples":{"incoming_payment.sepa_instant.confirmed":{"description":"Confirmed instant incoming payment.","value":{"id":"6607e355-7d2c-588b-9deb-403b0a91f89b","status":"confirmed","status_details":"","object":"incoming_payment","idempotency_key":"biy82a","created_at":"2022-01-03T14:18:03.841642Z","initiated_at":"2022-01-03T14:18:03.841Z","reconciled_amount":5000,"reconciliation_status":"reconciled","type":"sepa_instant","direction":"credit","amount":5000,"currency":"EUR","connected_account_id":"eca92b9e-6725-4233-9943-5e9bbf033e9c","originating_account":{"account_number":"FR7688511000011234567890107","bank_code":"BNPAFRPP","holder_address":{"city":"Paris","country":"FR","line_1":"119, avenue du General Michel Bizot","line_2":"75012 Paris","building_number":"119","street_name":"avenue du General Michel Bizot","postal_code":"","region_state":""},"holder_name":"PartnerCo","creditor_identifier":"","private_identification":{"birth_date":"1990-01-01","birth_city":"Paris","birth_country":"FR","other":{"identification":"123456789","identification_type":"passport_number"}}},"receiving_account":{"account_number":"FR7688511000011234567890107","bank_code":"SOGEFRPP","holder_address":{"city":"Paris","country":"FR","line_1":"1, rue de la Paix","line_2":"","building_number":"1","street_name":"rue de la Paix","postal_code":"75001","region_state":""},"holder_name":"TechCo","organization_identification":{"legal_entity_identifier":"529900T8BM49AURSDO55"}},"receiving_account_id":"8d97ed83-a6f7-4929-8e90-01b2912fb6a7","bank_data":{"end_to_end_id":"1zVrqOXmCS","file_id":"6fc0018b-4c4a-5d50-9f61-a054a1960bd9","message_id":"RirbvB2eEi","transaction_id":"1zVrqOXmCS"},"value_date":"2022-01-03","requested_execution_date":"2022-01-03","purpose":"SALA","category_purpose_code":"B2B","uetr":"d267652b-0767-4ea5-b2d1-675b0c5c8301","direct_debit_mandate":null,"direct_debit_mandate_id":"feefb18f-6b6e-42b7-bb5d-745b3acacc9b","direct_debit_sequence_type":"recurring","metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"reference":"Payment ID 1zVrqOXmCS","intermediary_agents":[{"financial_institution_identification":{"bank_code":"SOMEBIC0XXX","name":"Bank A","legal_entity_identifier":"219200WSGIIZEPF1P999","other":{"identification":"35664632","identification_type":"bank_identification"}}}],"routing_instruction":"Cross-border routing instructions"}},"incoming_payment.sepa_instant.rejected":{"description":"Rejected instant incoming payment.","value":{"id":"5136a26b-6281-4306-9ca0-a5f3b569eb1e","status":"rejected","status_details":"","object":"incoming_payment","idempotency_key":"8A2gcC","created_at":"2022-01-03T14:18:03.841642Z","initiated_at":"2022-01-03T14:18:03.841Z","reconciled_amount":0,"reconciliation_status":"unreconciled","type":"sepa_instant","direction":"credit","amount":1000,"currency":"EUR","connected_account_id":"eca92b9e-6725-4233-9943-5e9bbf033e9c","originating_account":{"account_number":"FR7688511000011234567890107","bank_code":"BNPAFRPP","holder_address":{"city":"Paris","country":"FR","line_1":"119, avenue du General Michel Bizot","line_2":"75012 Paris","building_number":"119","street_name":"avenue du General Michel Bizot","postal_code":"","region_state":""},"holder_name":"PartnerCo","creditor_identifier":"","organization_identification":{"legal_entity_identifier":"529900T8BM49AURSDO55"}},"receiving_account":{"account_number":"FR7688511000011234567890107","bank_code":"SOGEFRPP","holder_address":{"city":"Paris","country":"FR","line_1":"1, rue de la Paix","line_2":"","building_number":"1","street_name":"rue de la Paix","postal_code":"75001","region_state":""},"holder_name":"TechCo","private_identification":{"birth_date":"1990-01-01","birth_city":"Paris","birth_country":"FR","other":{"identification":"123456789","identification_type":"passport_number"}}},"receiving_account_id":"8d97ed83-a6f7-4929-8e90-01b2912fb6a7","bank_data":{"end_to_end_id":"1zVrqOXmCS","file_id":"6fc0018b-4c4a-5d50-9f61-a054a1960bd9","message_id":"RirbvB2eEi","transaction_id":"1zVrqOXmCS"},"value_date":"2022-01-03","requested_execution_date":"2022-01-03","purpose":"SALA","category_purpose_code":"B2B","uetr":"d267652b-0767-4ea5-b2d1-675b0c5c8301","direct_debit_mandate":null,"direct_debit_mandate_id":"50c7ce93-8b67-48f9-851a-b64246e9480a","direct_debit_sequence_type":"recurring","metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"reference":"Payment ID mjhQ5Z","intermediary_agents":[{"financial_institution_identification":{"bank_code":"SOMEBIC0XXX","name":"Bank A","legal_entity_identifier":"219200WSGIIZEPF1P999","other":{"identification":"35664632","identification_type":"bank_identification"}}}],"routing_instruction":"Cross-border routing instructions"}}}},"security":[{"sec0":[]}],"paths":{"/payment_orders":{"post":{"description":"Create a payment order to be sent to the bank. Once created, a payment order can be approved or canceled.\n\nCreate payment orders in batches using the [Bulk actions](ref:create-bulk-action) object.\n","summary":"Create payment order","operationId":"create-payment-order","tags":["Payment Orders"],"parameters":[{"$ref":"#/components/parameters/payment_orders.create_parameters.idempotency_key"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/payment_order.creation_details.sepa_credit"},{"$ref":"#/components/schemas/payment_order.creation_details.sepa_debit"},{"$ref":"#/components/schemas/payment_order.creation_details.sepa_instant"},{"$ref":"#/components/schemas/payment_order.creation_details.sepa_urgent"},{"$ref":"#/components/schemas/payment_order.creation_details.swift"},{"$ref":"#/components/schemas/payment_order.creation_details.swift_fi_to_fi"},{"$ref":"#/components/schemas/payment_order.creation_details.target2"},{"$ref":"#/components/schemas/payment_order.creation_details.target2_fi_to_fi"},{"$ref":"#/components/schemas/payment_order.creation_details.fps"},{"$ref":"#/components/schemas/payment_order.creation_details.bacs_debit"},{"$ref":"#/components/schemas/payment_order.creation_details.chaps"},{"$ref":"#/components/schemas/payment_order.creation_details.other"}]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"415":{"$ref":"#/components/responses/errors.415.unsupported_media_type"}}},"get":{"summary":"List payment orders","description":"List and filter payment orders.","operationId":"list-payment-orders","tags":["Payment Orders"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":25,"minimum":0,"maximum":100}},{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/list.common_parameters.sort_order"},{"name":"start_date","in":"query","description":"The creation date of the payment order.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the payment order.","schema":{"type":"string","format":"date"}},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to trigger the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","description":"The type of the payment order.","schema":{"$ref":"#/components/schemas/payment_type"}},{"name":"direction","in":"query","description":"The direction of the payment order.","schema":{"type":"string","enum":["credit","debit"]}},{"name":"status","in":"query","description":"The status of the payment order.","schema":{"type":"string","enum":["pending_approval","approved","processing","sent","rejected","canceled","executed","pending","denied","failed"]}},{"name":"start_value_date","in":"query","description":"The value date of the payment order.","schema":{"type":"string","format":"date"}},{"name":"end_value_date","in":"query","description":"The value date of the payment order.","schema":{"type":"string","format":"date"}},{"name":"amount_from","in":"query","description":"The amount of the payment order.","schema":{"type":"integer","minimum":0}},{"name":"amount_to","in":"query","description":"The amount of the payment order.","schema":{"type":"integer","minimum":0}},{"name":"currency","in":"query","description":"The ISO 4217 currency code of the payment order.","schema":{"type":"string"}},{"name":"mandate_reference","in":"query","description":"The reference of the direct debit mandate.","schema":{"type":"string","maxLength":35}},{"name":"reconciliation_status","in":"query","description":"The reconciliation status of the payment order.","schema":{"type":"string","enum":["reconciled","partially_reconciled","unreconciled","excluded"]}},{"name":"file_id","in":"query","description":"The ID of the file including the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"idempotency_key","in":"query","description":"The idempotency key of the payment order.","schema":{"type":"string"}},{"name":"auto_approval","in":"query","description":"If true, only payment orders which were automatically approved will be fetched.","schema":{"type":"boolean"}},{"name":"counterparty_id","in":"query","description":"The ID of the counterparty of the payment order.","schema":{"type":"string","format":"uuid"},"deprecated":true},{"name":"counterparty_account_id","in":"query","description":"The ID of the counterparty account receiving the payment order.","schema":{"type":"string","format":"uuid"},"deprecated":true},{"name":"account_holder_id","in":"query","description":"The ID of the account holder receiving the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"internal_account_id","in":"query","description":"The ID of the internal account linked to the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"external_account_id","in":"query","description":"The ID of the external account receiving the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"aggregation_reference","in":"query","description":"The aggregation reference of the payment order.","schema":{"type":"string","maxLength":140}},{"name":"direct_debit_mandate_id","in":"query","description":"The ID of the payment order's direct debit mandate.","schema":{"type":"string","format":"uuid"}},{"name":"retry_details.original_payment_id","in":"query","description":"The ID of the original payment order that led to the current object through a chain of retries.","schema":{"type":"string","format":"uuid"}},{"name":"uetr","in":"query","schema":{"type":"string","format":"uuid","description":"Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI."}},{"name":"settlement_method","in":"query","schema":{"type":"string","enum":["cover","instructed_agent","instructing_agent"],"description":"The settlement method of the payment order.","example":"cover"}},{"name":"correspondent_bank_id","in":"query","description":"The ID of the correspondent bank used to settle the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"correspondent_bank_account_id","in":"query","description":"The ID of the correspondent bank account used to settle the payment order.","schema":{"type":"string","format":"uuid"}},{"name":"correspondent_banking_rule_id","in":"query","description":"The ID of the correspondent banking rule the payment order was routed through.","schema":{"type":"string","format":"uuid"}},{"name":"cbs_data.transaction_id","in":"query","description":"The ID of the transaction (transaction_id) in CBS Data (cbs_data).","schema":{"type":"string"}},{"name":"validation.type","in":"query","description":"The type of payment validation.","schema":{"type":"string","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]}},{"name":"validation.status","in":"query","description":"The status of payment validation.","schema":{"type":"string","enum":["queued","in_progress","successful","failed","pending_investigation","pending_retry","canceled","technical_error"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/payment_orders/{id}/approve":{"post":{"summary":"Approve payment order","description":"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`.\n\nApprove payment orders in batches using the Bulk actions object.\n","operationId":"approve-payment-order","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/payment_orders/{id}/cancel":{"post":{"summary":"Cancel payment order","description":"Cancel a payment order. A payment order can be canceled from the `pending_approval` and `approved` statuses. Canceling a payment orders updates its status to `canceled`.\n\nCancel payment orders in batches using the [Bulk actions](ref:create-bulk-action) object.\n","operationId":"cancel-payment-order","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.cancelation_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/payment_orders/{id}/retry":{"post":{"summary":"Retry payment order","description":"Retry a payment order. Some of the parameters can be changed depending on the payment's type and direction.","operationId":"retry-payment-order","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true},{"name":"Idempotency-Key","in":"header","description":"An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.","schema":{"type":"string","example":"8A2gcC"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.manual_retry_creation"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/payment_orders/{id}/retry_cbs_transaction_booking":{"post":{"summary":"Retry CBS transaction booking","description":"Retries the CBS transaction booking for the given object. Use this when Mambu Payments has processed the payment but the corresponding booking in Mambu Core failed.","operationId":"retry-payment-order-cbs-transaction-booking","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/payment_orders/{id}/payment_validation":{"post":{"summary":"Update payment order validation","description":"Update a validation status for a payment order.","operationId":"update-payment-order-validation","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/common.update_payment_validation"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/payment_orders/{id}":{"post":{"summary":"Update payment order","description":"Update a payment order.","operationId":"update-payment-order","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.update_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"415":{"$ref":"#/components/responses/errors.415.unsupported_media_type"}}},"get":{"summary":"Retrieve payment order","description":"Retrieve the details of a payment order.","operationId":"retrieve-payment-order","tags":["Payment Orders"],"parameters":[{"name":"id","in":"path","description":"The ID of the payment order.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_order.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/incoming_payments/{id}/confirm":{"post":{"summary":"Confirm incoming payment","description":"Confirm an incoming payment in status `pending_confirmation`. This is only relevant for incoming payments with `type` = `sepa_instant`. Confirming an incoming payment updates its status to `confirmed`.","operationId":"confirm-incoming-payment","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"},"examples":{"default":{"$ref":"#/components/examples/incoming_payment.sepa_instant.confirmed"}}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/incoming_payments/{id}/reject":{"post":{"summary":"Reject incoming payment","description":"Reject an incoming payment. Only applies to the following payments:\n\n- Asynchronous SEPA instant incoming payments to reject: `type` = `sepa_instant`, `direction` = `credit`; `status` = `pending_confirmation`\n  - Set the incoming payment status to `rejected`.\n- SEPA direct debits incoming payments: `type` = `sepa`, `direction` = `debit`; `status` = `received`\n  - Set the incoming payment status to `pending_rejection`.\n  - This operation is possible only if the value date of the payment is not in the past.\n","operationId":"reject-incoming-payment","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.reject_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"},"examples":{"default":{"$ref":"#/components/examples/incoming_payment.sepa_instant.rejected"}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"415":{"$ref":"#/components/responses/errors.415.unsupported_media_type"}}}},"/incoming_payments/{id}/track":{"post":{"summary":"Track incoming payment","description":"Track Swift incoming payments with Swift GPI.","operationId":"track-incoming-payment","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.track_details"}}}},"responses":{"200":{"description":"Successfully processed. No content returned."},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/incoming_payments/{id}/retry_cbs_transaction_booking":{"post":{"summary":"Retry CBS transaction booking","description":"Retries the CBS transaction booking for the given object. Use this when Mambu Payments has processed the payment but the corresponding booking in Mambu Core failed.","operationId":"retry-incoming-payment-cbs-transaction-booking","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/incoming_payments/{id}/payment_validation":{"post":{"summary":"Update incoming payment validation","description":"Update a validation status for an incoming payment.","operationId":"update-incoming-payment-validation","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/common.update_payment_validation"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/incoming_payments/{id}":{"post":{"summary":"Update incoming payment","description":"Update an incoming payment.","operationId":"update-incoming-payment","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.update"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"415":{"$ref":"#/components/responses/errors.415.unsupported_media_type"}}},"get":{"summary":"Retrieve incoming payment","description":"Retrieve the details of an incoming payment.","operationId":"retrieve-incoming-payment","tags":["Incoming Payments"],"parameters":[{"name":"id","in":"path","description":"The ID of the incoming payment.","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/incoming_payments":{"get":{"summary":"List incoming payments","description":"List and filter incoming payments.","operationId":"list-incoming-payments","tags":["Incoming Payments"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":25,"minimum":0,"maximum":100}},{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/list.common_parameters.sort_order"},{"name":"start_date","in":"query","description":"The creation date of the incoming payment.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the incoming payment.","schema":{"type":"string","format":"date"}},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to receive the payment.","schema":{"type":"string"}},{"name":"type","in":"query","description":"The type of the incoming payment.","schema":{"$ref":"#/components/schemas/payment_type"}},{"name":"direction","in":"query","description":"The direction of the incoming payment.","schema":{"type":"string","enum":["credit","debit"]}},{"name":"status","in":"query","description":"The status of the incoming payment.","schema":{"type":"string","enum":["received","pending_approval","pending_return","returned","rejected","pending_confirmation","confirmed","pending_rejection"]}},{"name":"start_value_date","in":"query","description":"The value date of the incoming payment.","schema":{"type":"string","format":"date"}},{"name":"end_value_date","in":"query","description":"The value date of the incoming payment.","schema":{"type":"string","format":"date"}},{"name":"amount_from","in":"query","description":"The amount of the incoming payment.","schema":{"type":"integer","format":"int32","minimum":0}},{"name":"amount_to","in":"query","description":"The amount of the incoming payment.","schema":{"type":"integer","format":"int32","minimum":0}},{"name":"currency","in":"query","description":"The ISO 4217 currency code of the incoming payment.","schema":{"type":"string"}},{"name":"mandate_reference","in":"query","description":"The reference of the direct debit mandate.","schema":{"type":"string","maxLength":35}},{"name":"file_id","in":"query","description":"The ID of the file including the incoming payment.","schema":{"type":"string","format":"uuid"}},{"name":"reconciliation_status","in":"query","description":"The reconciliation status of the incoming payment.","schema":{"type":"string","enum":["reconciled","partially_reconciled","unreconciled","excluded"]}},{"name":"aggregation_reference","in":"query","description":"The aggregation reference of the incoming payment.","schema":{"type":"string","maxLength":140}},{"name":"direct_debit_mandate_id","in":"query","description":"The ID of the incoming payment’s direct debit mandate.","schema":{"type":"string","format":"uuid"}},{"name":"internal_account_id","in":"query","description":"The ID of the incoming payment’s receiving account.","schema":{"type":"string","format":"uuid"}},{"name":"uetr","in":"query","schema":{"type":"string","format":"uuid","description":"Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI."}},{"name":"settlement_method","in":"query","schema":{"type":"string","enum":["cover","instructed_agent","instructing_agent"],"description":"The settlement method of the incoming payment.","example":"cover"}},{"name":"cbs_data.transaction_id","in":"query","description":"The ID of the transaction (transaction_id) in CBS Data (cbs_data).","schema":{"type":"string"}},{"name":"validation.type","in":"query","description":"The type of payment validation.","schema":{"type":"string","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]}},{"name":"validation.status","in":"query","description":"The status of payment validation.","schema":{"type":"string","enum":["queued","in_progress","successful","failed","pending_investigation","pending_retry","canceled","technical_error"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/incoming_payment.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/returns":{"post":{"summary":"Create return","description":"Create a return on a payment. It only applies to financial institution payments.","operationId":"create-return","tags":["Returns"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.creation_details"}}}},"responses":{"200":{"description":"Successfully created return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"415":{"$ref":"#/components/responses/errors.415.unsupported_media_type"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}},"get":{"summary":"List returns","description":"List and filter returns.","operationId":"list-returns","tags":["Returns"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","format":"int32","default":25}},{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string"}},{"$ref":"#/components/parameters/list.common_parameters.sort_order"},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to trigger or receive the return.","schema":{"type":"string"}},{"name":"type","in":"query","description":"The type of the related payment.","schema":{"type":"string","enum":["sepa","sepa_instant"]}},{"name":"return_type","in":"query","description":"The type of the return. Authorized values include `return`, `refund` and `reversal`. Only available when related payment is a direct debit.","schema":{"type":"string","enum":["return","refund","reversal"]}},{"name":"status","in":"query","description":"The status of the return.","schema":{"type":"string","enum":["pending","sent","processing","executed","received","rejected"]}},{"name":"related_payment_id","in":"query","description":"The ID of the payment related to the return.","schema":{"type":"string","format":"uuid"}},{"name":"related_payment_type","in":"query","description":"The type of the payment related to the return, either `incoming_payment` or `payment_order`.","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"The creation date of the return.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the return.","schema":{"type":"string","format":"date"}},{"name":"start_value_date","in":"query","description":"The value date of the return.","schema":{"type":"string","format":"date"}},{"name":"end_value_date","in":"query","description":"The value date of the return.","schema":{"type":"string","format":"date"}},{"name":"direction","in":"query","description":"The direction of the return. `credit` for credit transfer returns (SCT/SCT Inst), and `debit` for direct debit returns (SDD).","schema":{"type":"string","enum":["credit","debit"]}},{"name":"reconciliation_status","in":"query","description":"The reconciliation status of the return.","schema":{"type":"string","enum":["reconciled","partially_reconciled","unreconciled","excluded"]}},{"name":"file_id","in":"query","description":"The ID of the file including the return.","schema":{"type":"string"}},{"name":"aggregation_reference","in":"query","description":"The aggregation reference of the return.","schema":{"type":"string","maxLength":140}},{"name":"validation.type","in":"query","description":"The type of payment validation.","schema":{"type":"string","enum":["internal_account_is_active","direct_debit_mandate_is_active","liquidity_screening","sanctions_screening","risk_screening","limits_screening","mambu_authorization"]}},{"name":"validation.status","in":"query","description":"The status of payment validation.","schema":{"type":"string","enum":["queued","in_progress","successful","failed","pending_investigation","pending_retry","canceled","technical_error"]}}],"responses":{"200":{"description":"List of filtered returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/returns/{id}":{"get":{"summary":"Retrieve return","description":"Retrieve the details of a return.","operationId":"retrieve-return","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successfully retrieved return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}},"post":{"summary":"Update return","description":"Update a return.","operationId":"update-return","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.update_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/returns/{id}/approve":{"post":{"summary":"Approve return","description":"Approve a return in status `pending_approval`. Approving a return updates its status to `approved`.","operationId":"approve-return","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successfully approved return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/returns/{id}/cancel":{"post":{"summary":"Cancel return","description":"Cancel a return in status `pending_approval`. Canceling a return updates its status to `canceled`.","operationId":"cancel-return","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.cancel_details"}}}},"responses":{"200":{"description":"Successfully canceled return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"},"409":{"$ref":"#/components/responses/errors.409.conflict"}}}},"/returns/{id}/retry_cbs_transaction_booking":{"post":{"summary":"Retry CBS transaction booking","description":"Retries the CBS transaction booking for the given object. Use this when Mambu Payments has processed the payment but the corresponding booking in Mambu Core failed.","operationId":"retry-return-cbs-transaction-booking","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successfully retried CBS transaction booking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/returns/{id}/payment_validation":{"post":{"summary":"Update return validation","description":"Update a validation status for a return.","operationId":"update-return-payment-validation","tags":["Returns"],"parameters":[{"name":"id","in":"path","description":"The ID of the return.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/common.update_payment_validation"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}}}}