{"openapi":"3.1.0","info":{"title":"Investigations","description":"Automate payments across banks with a single API","version":"1","contact":{"name":"API Support","email":"dev@numeral.io"}},"tags":[{"name":"Return Requests","description":"Return requests endpoints"},{"name":"Claims","description":"Claims endpoints"},{"name":"Inquiries","description":"Inquiries endpoints"}],"servers":[{"url":"https://sandbox.numeral.io/v1"}],"components":{"securitySchemes":{"sec0":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"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"}}},"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, rue de l'Abondance"},"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":""},"city":{"type":"string","example":"Lyon","description":"City."},"country":{"type":"string","example":"FR","description":"ISO 3166 alpha-2 country code."}}},"common.metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"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 or a payment orders."},"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)."},"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"},"file_reference":{"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."},"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"},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of this return."}}},"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 or a payment order."},"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"}}},"inquiry.creation_details":{"type":"object","required":["connected_account_id","related_request_type","related_request_id"],"properties":{"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account. The connected account is the account used to trigger the inquiry."},"related_request_type":{"type":"string","enum":["return_request","claim"],"description":"The related request type of the inquiry."},"related_request_id":{"type":"string","format":"uuid","description":"The ID of the related request object."}}},"inquiry.deny_details":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["CUST","LEGL","ARDT","AC04","AM04","NOAS","NOOR"],"description":"The reason for denying the inquiry."}}},"inquiry.details":{"type":"object","required":["id","object","status","status_details","connected_account_id","related_request_type","related_request_id","bank_data","created_at","date"],"properties":{"id":{"type":"string","format":"uuid","description":"The UUID of the inquiry."},"object":{"type":"string","enum":["inquiry"],"description":"Label used to identify this kind of object","example":"inquiry"},"status":{"type":"string","description":"The status of the inquiry. See [inquiry's lifecycle](ref:inquiry-lifecycle).","enum":["created","processing","sent","received","denied","archived"],"example":"received"},"status_details":{"type":"string","description":"The details of the status of the inquiry.","example":"AC04"},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account."},"related_request_type":{"type":"string","enum":["return_request","claim"],"description":"The type of the request related to the inquiry."},"related_request_id":{"type":"string","format":"uuid","description":"The ID of the request related to the inquiry."},"bank_data":{"type":"object","description":"Bank data, such as message and transaction IDs, in JSON `key:value` format.","required":["file_id","message_id","status_request_id"],"properties":{"file_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","example":"zNhzzPND67KMfbOs5U0d47dLRB"},"status_request_id":{"type":"string","example":"dtL9AGFHbeWQVABPcTt4oWIeTgFI"}}},"created_at":{"type":"string","format":"date-time","description":"The UTC timestamp of the creation of the inquiry."},"date":{"type":"string","format":"date","description":"The date of the inquiry."}}},"inquiry.search_result":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/inquiry.details"}}}},"claim.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"}}},"claim.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/claim.creditor_reference_type"},"reference":{"type":"string","description":"Unique and unambiguous identification of the referred document.","example":"RF18539007547034"}}},"claim.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"}}},"claim.referred_document_information":{"type":"object","description":"The identification and the content of the referred document","properties":{"type":{"$ref":"#/components/schemas/claim.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"}}},"claim.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/claim.creditor_reference_information"},"referred_document_information":{"type":"array","items":{"$ref":"#/components/schemas/claim.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"}}}}},"claim.related_account_info":{"type":"object","required":["account_number","bank_code","holder_name","holder_address"],"properties":{"account_number":{"type":"string","description":"The account number."},"bank_code":{"type":"string","description":"The bank code."},"holder_name":{"type":"string","description":"The name of the account holder."},"holder_address":{"$ref":"#/components/schemas/common.address"}}},"claim.related_payment_bank_data":{"type":"object","required":["message_id","end_to_end_id","transaction_id"],"properties":{"message_id":{"type":"string","description":"The message ID of the related payment."},"end_to_end_id":{"type":"string","description":"The end-to-end ID of the related payment."},"transaction_id":{"type":"string","description":"The transaction ID of the related payment."}}},"claim.related_payment":{"type":"object","required":["amount","currency","direction","value_date","reference","originating_account","receiving_account"],"description":"The related payment details.","properties":{"amount":{"type":"integer","format":"int64","description":"The amount of the related payment."},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code, in lowercase. Only `EUR` is supported for now.","enum":["EUR"]},"direction":{"type":"string","description":"The direction of the related payment."},"value_date":{"type":"string","format":"date","description":"The value date of the related payment."},"reference":{"type":"string","description":"The reference of the related payment."},"structured_reference":{"$ref":"#/components/schemas/claim.structured_reference"},"originating_account":{"$ref":"#/components/schemas/claim.related_account_info"},"receiving_account":{"$ref":"#/components/schemas/claim.related_account_info"},"bank_data":{"$ref":"#/components/schemas/claim.related_payment_bank_data"}}},"claim.creation_details":{"type":"object","required":["type","connected_account_id","related_payment_type","related_payment_id","description"],"properties":{"type":{"type":"string","enum":["sepa_non_receipt","sepa_value_date_correction"],"description":"The claim type. Both `sepa_non_receipt` and `sepa_value_date_correction` are supported."},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account."},"related_payment_type":{"type":"string","enum":["payment_order"],"description":"The payment type on which the claim applies. Only `payment_order` is supported when sending claims."},"related_payment_id":{"type":"string","description":"The ID of the payment on which the claim applies."},"description":{"type":"string","maxLength":140,"description":"Claim instructions for the receiving financial institution."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}}}},"claim.details":{"type":"object","required":["id","object","type","status","status_details","value_date","connected_account_id","related_payment_type","related_payment_id","related_payment","description","metadata","bank_data","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The UUID of the claim."},"object":{"type":"string","enum":["claim"],"description":"Label used to identify this kind of object","example":"claim"},"type":{"type":"string","description":"The type of the claim","enum":["sepa_non_receipt","sepa_value_date_correction"]},"status":{"type":"string","description":"The status of the claim. See [claim's lifecycle](ref:claim-lifecycle).","enum":["created","processing","sent","received","accepted","rejected"],"example":"received"},"status_details":{"type":"string","description":"The details of the status of the claim."},"value_date":{"type":"string","description":"The value date of the claim.","format":"date","example":"2024-01-03"},"connected_account_id":{"type":"string","format":"uuid","description":"The ID of the connected account."},"related_payment_type":{"type":"string","description":"The type of the payment related to the return, either `incoming_payment` or `payment_order`.","enum":["payment_order","incoming_payment"]},"related_payment_id":{"type":"string","description":"The ID of the payment on which the claim applies."},"related_payment":{"type":"object","$ref":"#/components/schemas/claim.related_payment"},"description":{"type":"string","maxLength":140,"description":"Claim instructions for the receiving financial institution."},"metadata":{"type":"object","description":"Additional client data in JSON format. See [Metadata](ref:metadata).","example":{"property_a":true,"property_b":"false"}},"investigation_fee":{"type":"object","description":"Investigation fee details, if provided by the scheme/bank.","properties":{"amount":{"type":"integer","format":"int64","description":"Fee amount in minor units.","example":150000},"currency":{"type":"string","description":"ISO 4217 currency.","example":"EUR"},"account_number":{"type":"string","description":"Account number to which the fee should be paid."},"bank_code":{"type":"string","description":"Bank identifier code associated with the fee account."}}},"compensation_fee":{"type":"object","description":"Compensation fee details, if provided by the scheme/bank.","properties":{"amount":{"type":"integer","format":"int64","description":"Fee amount in minor units.","example":250000},"currency":{"type":"string","description":"ISO 4217 currency.","example":"EUR"},"account_number":{"type":"string","description":"Account number to which the fee should be paid."},"bank_code":{"type":"string","description":"Bank identifier code associated with the fee account."}}},"bank_data":{"type":"object","description":"Bank data, such as assignment id and file IDs, in JSON format.","required":["reference","assignment_id","case_id","file_id"],"properties":{"reference":{"type":"string","example":"WfVCPfBzPjfEyO4CLpPDrjjYGSGXt0"},"assignment_id":{"type":"string","example":"oRiB7XRvqlfB6yGEikSFeBeCVkyo7h"},"case_id":{"type":"string","example":"AFpCILqubWQ5YLWePG5bYpw"},"file_id":{"type":"string","example":"a815e756-5576-4d40-9fbd-38ec304b856c"},"file_reference":{"type":"string","description":"The reference of the file containing the claim.","example":"FILE_REF_12345"}}},"created_at":{"type":"string","format":"date-time","example":"2024-01-03T11:53:19.734182Z","description":"The UTC timestamp of the creation of the claim."}}},"claim.search_result":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/claim.details"}}}},"claim.accept_details":{"type":"object","description":"Request body for accepting a claim.","properties":{"option":{"type":"string","enum":["ACVA","MODI"],"description":"The option for accepting the claim. Only used for `sepa_value_date_correction` claims. - `ACVA`: Accept value date correction - `MODI`: Modify value date correction\n"},"value_date":{"type":"string","format":"date","description":"Applicable value date of the payment. Automatically set to the payment's initial value_date if not filled. Only used for `sepa_non_receipt` claims.\n","example":"2024-01-03"}}},"claim.reject_details":{"type":"object","description":"Request body for rejecting a claim.","properties":{"option":{"type":"string","enum":["RJVA","CVAA"],"description":"The option for rejecting the claim. Only used for `sepa_value_date_correction` claims. - `RJVA`: Reject value date correction - `CVAA`: Cancel value date correction\n"},"reason":{"type":"string","enum":["NOOR","RNPR","ARJT","ARDT","RR04"],"description":"The reason for rejecting the claim. Only used for `sepa_non_receipt` claims. - `NOOR`: No original transaction found - `RNPR`: Request not processed - `ARJT`: Rejection by agent - `ARDT`: Rejection by debtor - `RR04`: Regulatory reason\n"}}}}},"security":[{"sec0":[]}],"paths":{"/return_requests":{"post":{"summary":"Create return request","description":"Create a return request for a payment order previously executed.","operationId":"create-return-request","tags":["Return Requests"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.creation_details"}}}},"responses":{"200":{"description":"Successfully created return request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.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 return requests","description":"List and filter return requests.","operationId":"list-return-requests","tags":["Return Requests"],"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 send or receive the return request.","schema":{"type":"string"}},{"name":"type","in":"query","description":"The type of the return request.","schema":{"type":"string","enum":["sepa","sepa_instant"]}},{"name":"status","in":"query","description":"The status of the return request.","schema":{"type":"string","enum":["received","sent","accepted","rejected","pending","denied"]}},{"name":"return_reason","in":"query","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).","schema":{"type":"string"}},{"name":"related_payment_id","in":"query","description":"The ID of the payment related to the return request.","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","enum":["payment_order","incoming_payment"]}},{"name":"start_date","in":"query","description":"The creation date of the return request.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the return request.","schema":{"type":"string","format":"date"}},{"name":"start_value_date","in":"query","description":"The start value date of the return request.","schema":{"type":"string","format":"date"}},{"name":"end_value_date","in":"query","description":"The end value date of the return request.","schema":{"type":"string","format":"date"}},{"name":"file_id","in":"query","description":"The ID of the file including the return request.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of filtered return requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/return_requests/{id}/accept":{"post":{"summary":"Accept return request","description":"Accept a return request for an incoming payment previously received. Accepting a return request creates a return. See [Create a return](ref:create-return).","operationId":"accept-return-request","tags":["Return Requests"],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid","description":"The ID of the return request."},"required":true}],"responses":{"200":{"description":"Successfully accepted return request, and the associated return which has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.accept_response"}}}},"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"}}}},"/return_requests/{id}/deny":{"post":{"summary":"Deny return request","description":"Deny a return request for an incoming payment previously received. No return will be created.","operationId":"deny-return-request","tags":["Return Requests"],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid","description":"The ID of the return request."},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.deny_details"}}}},"responses":{"200":{"description":"Successfully denied return request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.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"}}}},"/return_requests/{id}":{"get":{"summary":"Retrieve return request","description":"Retrieve the details of a return request.","operationId":"retrieve-return-request","tags":["Return Requests"],"parameters":[{"name":"id","in":"path","schema":{"type":"string","format":"uuid","description":"The ID of the return request."},"required":true}],"responses":{"200":{"description":"Successfully retrieved return request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_request.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/claims":{"post":{"summary":"Create claim","description":"Claims refer to formal requests between financial institutions to resolve payment issues,  specifically a `Claim Non-Receipt` to address missing funds not credited as expected,  and a `Claim for Value-Date Correction` to correct the date on which funds were or should have been credited.  This feature is only available to financial institution customers.","operationId":"create-claim","tags":["Claims"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.creation_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}},"get":{"summary":"List claims","description":"List and filter claims.","operationId":"list-claims","tags":["Claims"],"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":"start_date","in":"query","description":"The creation date of the claim.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the claim.","schema":{"type":"string","format":"date"}},{"name":"start_value_date","in":"query","description":"The value date of the claim.","schema":{"type":"string","format":"date"}},{"name":"end_value_date","in":"query","description":"The value date of the claim.","schema":{"type":"string","format":"date"}},{"name":"type","in":"query","description":"The type of the claim.","schema":{"type":"string","enum":["sepa_value_date_correction","sepa_non_receipt"]}},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to send or receive the claim.","schema":{"type":"string"}},{"name":"related_payment_type","in":"query","description":"The payment type on which the claim applies, either `incoming_payment` or `payment_order`.","schema":{"type":"string","enum":["payment_order","incoming_payment"]}},{"name":"related_payment_id","in":"query","description":"The ID of the payment (payment order or incoming payment) on which the claim applies.","schema":{"type":"string"}},{"name":"originating_account_number","in":"query","description":"The account number of the entity having sent the claim.","schema":{"type":"string"}},{"name":"receiving_account_number","in":"query","description":"The account number of the entity having received the claim.","schema":{"type":"string"}},{"name":"status","in":"query","description":"The status of the claim.","schema":{"type":"string","enum":["created","processing","sent","received","accepted","rejected"]}},{"name":"file_id","in":"query","description":"The ID of the file including the claim.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of filtered claims.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/claims/{id}/accept":{"post":{"summary":"Accept claim","description":"Accept a claim that has been received. This will update the claim status to `accepted`.","operationId":"accept-claim","tags":["Claims"],"parameters":[{"name":"id","in":"path","description":"The ID of the claim.","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.accept_details"}}}},"responses":{"200":{"description":"Successfully accepted claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.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"}}}},"/claims/{id}/reject":{"post":{"summary":"Reject claim","description":"Reject a claim that has been received. This will update the claim status to `rejected`.","operationId":"reject-claim","tags":["Claims"],"parameters":[{"name":"id","in":"path","description":"The ID of the claim.","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.reject_details"}}}},"responses":{"200":{"description":"Successfully rejected claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.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"}}}},"/claims/{id}":{"get":{"summary":"Retrieve claim","description":"Retrieve the details of a claim.","operationId":"retrieve-claim","tags":["Claims"],"parameters":[{"name":"id","in":"path","description":"The ID of the claim.","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successfully retrieved claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/claim.details"}}}},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/inquiries/{id}/deny":{"post":{"summary":"Deny inquiry (deprecated)","description":"**Deprecated.** This endpoint will be removed in a future version — the `denied` status on inquiries is also deprecated and will no longer be available.\n\nDeny an inquiry for a return request previously received. No return will be created.\n","operationId":"deny-inquiry","deprecated":true,"tags":["Inquiries"],"parameters":[{"name":"id","in":"path","description":"The ID of the inquiry to deny.","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.deny_details"}}}},"responses":{"200":{"description":"Successfully retrieved inquiry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.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"}}}},"/inquiries":{"post":{"description":"Create inquiry","summary":"Create inquiry","operationId":"create-inquiry","tags":["Inquiries"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.creation_details"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}},"get":{"summary":"List inquiries","description":"List and filter inquiries.","operationId":"list-inquiries","tags":["Inquiries"],"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":"start_date","in":"query","description":"The creation date of the inquiry.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the inquiry.","schema":{"type":"string","format":"date"}},{"name":"connected_account_id","in":"query","description":"The ID of the connected account used to receive the inquiry.","schema":{"type":"string"}},{"name":"status","in":"query","description":"The status of the inquiry.","schema":{"type":"string","enum":["created","processing","sent","received","denied","archived"],"example":"received"}},{"name":"related_request_type","in":"query","description":"The type of the request related to the inquiry. Only `return_request` and `claim` are supported.","schema":{"type":"string","enum":["return_request"]}},{"name":"related_request_id","in":"query","description":"The ID of the request related to the inquiry.","schema":{"type":"string","enum":["return_request"]}},{"name":"file_id","in":"query","description":"The ID of the file including the inquiry.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of filtered inquiries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.search_result"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}},"/inquiries/{id}":{"get":{"summary":"Retrieve inquiry","description":"Retrieve the details of an inquiry.","operationId":"retrieve-inquiry","tags":["Inquiries"],"parameters":[{"name":"id","in":"path","description":"The ID of the inquiry.","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successfully retrieved inquiry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inquiry.details"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"},"500":{"$ref":"#/components/responses/errors.500.internal_server_error"}}}}}}