{"openapi":"3.0.1","info":{"title":"Legacy - Payments API","description":"defaultDescription","version":"1"},"servers":[{"url":"https://pay-api.truelayer-sandbox.com","description":"Sandbox server"},{"url":"https://pay-api.truelayer.com","description":"Production server"}],"paths":{"/v2/single-immediate-payments-providers":{"get":{"description":"Returns a list of providers supported. Various query parameters can be used to filter returned providers.","operationId":"get-providers","summary":"Get providers","tags":["Payments"],"parameters":[{"name":"account_type","description":"Type of the account providers should support","in":"query","schema":{"type":"string"},"example":"sort_code_account_number,iban"},{"name":"auth_flow_type","description":"Auth flows providers should support","in":"query","schema":{"type":"string"},"example":"redirect,embedded"},{"name":"currency","description":"Currencies providers should support","in":"query","schema":{"type":"string"},"example":"GBP%2CEUR"},{"name":"client_id","description":"Client ID of the requester","in":"query","schema":{"type":"string"},"example":"sandbox-client-abc123"},{"name":"additional_input_type","description":"Embedded flow additional input types providers should support","in":"query","schema":{"type":"string"},"example":"text,select"},{"name":"country","description":"Country filters","in":"query","schema":{"type":"string"}},{"name":"release_channel","description":"Filter on release channels","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of providers","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProvidersResponse"}}}},"403":{"description":"Your are not authorised for the action"},"500":{"description":"Internal error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}}},"security":[]}},"/v2/single-immediate-payment-initiation-requests":{"post":{"description":"Initiate a payment","operationId":"initiate-payment","summary":"Initiate a payment","tags":["Payments"],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SingleImmediatePaymentInitiationRequest"}}}},"responses":{"200":{"description":"Initiation response","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SingleImmediatePaymentInitiationResponse"}}}},"400":{"description":"Invalid request","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InvalidRequestResponse"}}}},"403":{"description":"Your are not authorised for the action"},"500":{"description":"Internal error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"502":{"description":"Provider error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponse"}}}}},"security":[]}},"/v2/single-immediate-payments/{sip_id}/embedded-auth-steps/{step_id}/submission":{"post":{"description":"Some of the European banks require the embedded authorisation flow, which consists of multiple steps provided by the banks. Each step can be submitted via this endpoint. The response will include the information for the step to follow.\n","operationId":"submit-embedded-step","summary":"Submit embedded auth flow steps","tags":["Payments"],"parameters":[{"name":"sip_id","required":true,"in":"path","description":"Id of the payment","schema":{"type":"string"}},{"name":"step_id","required":true,"in":"path","description":"Id of the embedded authflow step","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmbeddedAuthflowInputSubmissionRequest"},{"$ref":"#/components/schemas/EmbeddedAuthflowCancelSubmissionRequest"}]}}}},"responses":{"200":{"description":"Response of the embedded auth flow step submission","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/EmbeddedAuthFlowResponse"},"examples":{"all_input_types":{"summary":"Example for all input types","value":{"result":{"step":{"type":"additional_inputs","step_id":"STEP_2","additional_inputs":{"otp":{"type":"text","mandatory":true,"sensitive":true,"min_length":6,"max_length":6,"regex":"^\\d{6}$","format":"numerical"}}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InvalidRequestResponse"}}}},"403":{"description":"Your are not authorised for the action"},"500":{"description":"Internal error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"502":{"description":"Provider error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponse"}}}}},"security":[]}},"/v2/single-immediate-payments/{sip_id}":{"get":{"description":"Get the payment details","operationId":"get-payment","summary":"Get a payment","tags":["Payments"],"parameters":[{"name":"sip_id","required":true,"in":"path","description":"Id of the payment","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment object as a result","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetSingleImmediatePaymentResponse"}}}},"403":{"description":"Your are not authorised for the action"},"500":{"description":"Internal error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InternalErrorResponse"}}}},"502":{"description":"Provider error","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponse"}}}}},"security":[]}}},"components":{"schemas":{"FeeOption":{"type":"object","properties":{"fee_option_id":{"description":"A unique identifier for the fee option, shared across providers. This should be provided on the single_immediate_payment.fee_option_id field on the initiation request.","type":"string"},"beneficiary_fee":{"description":"A value to indicate if the beneficiary would pay any fees on the transaction, when using this fee option.","type":"string","enum":["free","payable","unknown"]},"remitter_fee":{"description":"A value to indicate if the remitter would pay any fees on the transaction, when using this fee option.","type":"string","enum":["free","payable","unknown"]}}},"TextInput":{"type":"object","properties":{"type":{"description":"Value indicating the field type: text","type":"string","enum":["text"]},"display_text":{"description":"Text to describe what the field is asking for (English)","type":"string"},"provider_description":{"description":"Text directly from the bank relating to the field","type":"string"},"mandatory":{"description":"If the input must be provided","type":"boolean"},"sensitive":{"description":"If the input is sensitive (should be masked in UI)","type":"boolean"},"min_length":{"description":"The minimum length of the input text","type":"integer"},"max_length":{"description":"The maximum length of the input text","type":"integer"},"regex":{"description":"A regular expression the input text must match","type":"string"},"format":{"description":"A well known format, to facilitate being able to show useful prompts to the user.","type":"string","enum":["any","numerical","alphabetical","alphanumerical","email"]}}},"UriImage":{"type":"object","properties":{"type":{"description":"Type of the image data","type":"string","enum":["uri"]},"uri":{"description":"Uri of the image","type":"string"}}},"Base64Image":{"type":"object","properties":{"type":{"description":"Type of the image data","type":"string","enum":["base64"]},"base64":{"description":"base64 data of the image","type":"string"},"media_type":{"description":"Type of the media","type":"string"}}},"TextWithImageInput":{"type":"object","properties":{"type":{"description":"Value indicating the field type: text","type":"string","enum":["text_with_image"]},"display_text":{"description":"Text to describe what the field is asking for (English)","type":"string"},"provider_description":{"description":"Text directly from the bank relating to the field","type":"string"},"mandatory":{"description":"If the input must be provided","type":"boolean"},"sensitive":{"description":"If the input is sensitive (should be masked in UI)","type":"boolean"},"min_length":{"description":"The minimum length of the input text","type":"integer"},"max_length":{"description":"The maximum length of the input text","type":"integer"},"regex":{"description":"A regular expression the input text must match","type":"string"},"format":{"description":"A well known format, to facilitate being able to show useful prompts to the user.","type":"string","enum":["any","numerical","alphabetical","alphanumerical","email"]},"image":{"oneOf":[{"$ref":"#/components/schemas/UriImage"},{"$ref":"#/components/schemas/Base64Image"}]}}},"SelectInputOption":{"type":"object","properties":{"id":{"description":"Value to be provided on the initiation request, if the option is selected","type":"string"},"display_text":{"description":"Text to describe the option","type":"string"}}},"SelectInput":{"type":"object","required":["type","display_text","mandatory","options"],"properties":{"type":{"description":"Value indicating the field type: select","type":"string","enum":["select"]},"display_text":{"description":"Text to describe what the field is asking for (English)","type":"string"},"provider_description":{"description":"Text directly from the bank relating to the field","type":"string"},"mandatory":{"description":"If the input must be provided","type":"boolean"},"options":{"type":"array","description":"A list of id-display_text pairs to present to the end user as options (e.g. a drop down).","items":{"$ref":"#/components/schemas/SelectInputOption"}}}},"AdditionalInputs":{"description":"An optional dictionary of ID to additional inputs that must be collected from the end user to initiate a payment.  These inputs should be provided using the same IDs in the auth_flow.additional_inputs string dictionary on the initiation request","type":"object","oneOf":[{"$ref":"#/components/schemas/TextInput"},{"$ref":"#/components/schemas/TextWithImageInput"},{"$ref":"#/components/schemas/SelectInput"}]},"Embedded":{"type":"object","required":["additional_input_types"],"properties":{"additional_input_types":{"description":"A list of additional input field types that may be returned during the embedded authorisation flow (not inclusive of those required on initiation below).","type":"array","items":{"type":"string","enum":["text","text_with_image","select"]}},"additional_inputs":{"type":"object","$ref":"#/components/schemas/AdditionalInputs"}}},"Redirect":{"type":"object","properties":{"psu_ip_address_required":{"description":"Indicates if auth_flow.psu_ip_address is required on the initiation request.","type":"boolean"},"data_access_token_supported":{"description":"Indicates if auth_flow.data_access_token can be provided on the initiation request, to maintain long lived consents across products (Data API and Payment API),  where the provider only allows a single active consent across both AIS and PIS services.","type":"boolean"},"additional_inputs":{"type":"object","$ref":"#/components/schemas/AdditionalInputs"}}},"AuthFlow":{"type":"object","required":["types"],"properties":{"types":{"type":"string","enum":["embedded","redirect"]},"embedded":{"type":"object","$ref":"#/components/schemas/Embedded"},"redirect":{"type":"object","$ref":"#/components/schemas/Redirect"}}},"Currency":{"type":"object","properties":{"supported_currencies":{"type":"array","items":{"type":"string","enum":["GBP","EUR"]}}}},"Account":{"description":"A list of account types supported by the scheme.","type":"object","required":["types"],"properties":{"types":{"type":"array","items":{"type":"string","enum":["sort_code_account_number","iban","bban","nrb"]}}}},"Participant":{"type":"object","required":["account"],"properties":{"account":{"type":"object","$ref":"#/components/schemas/Account"},"name":{"description":"An object detailing the requirements for the name, if omitted then  setting the name on the initiation request is not supported for this scheme.","type":"object","properties":{"mandatory":{"description":"The corresponding field on the request is mandatory.","type":"boolean"},"min_length":{"description":"The corresponding field on the request must be at least this many characters.","type":"integer"},"max_length":{"description":"The corresponding field on the request must be at most this many characters.","type":"integer"},"regex":{"description":"The corresponding field on the request must match the regular expression.","type":"string"},"format":{"description":"A well known format to help you communicate to your client how the field will be validated.","type":"array","items":{"type":"string","enum":["any","numerical","alphabetical","alphanumerical","email"]}}}}}},"Beneficiary":{"type":"object","allOf":[{"$ref":"#/components/schemas/Participant"}]},"Remitter":{"type":"object","allOf":[{"$ref":"#/components/schemas/Participant"},{"type":"object","properties":{"mandatory":{"type":"boolean"}}}]},"SingleImmediatePaymentRequirement":{"type":"object","properties":{"currency":{"type":"object","$ref":"#/components/schemas/Currency"},"beneficiary":{"type":"object","$ref":"#/components/schemas/Beneficiary"},"remitter":{"type":"object","$ref":"#/components/schemas/Remitter"}}},"Requirement":{"type":"object","properties":{"auth_flow":{"description":"Which auth flows are supported and what fields are required/available to initiate a payment for those flows.","type":"object","$ref":"#/components/schemas/AuthFlow"},"single_immediate_payment":{"type":"object","$ref":"#/components/schemas/SingleImmediatePaymentRequirement"}}},"SingleImmediatePaymentScheme":{"type":"object","properties":{"scheme_id":{"description":"A unique identifier for the scheme, shared across providers. This should be provided on the single_immediate_payment.scheme_id field on the initiation request.","type":"string","enum":["faster_payments_service"]},"fee_options":{"description":"If present, then fees are payable to make a payment on the scheme, and you must choose an option in this list when initiating a payment.","type":"array","items":{"$ref":"#/components/schemas/FeeOption"}},"requirements":{"description":"Contains at least one set of requirements, one of which should be adhered to in order to create a valid initiation request for the scheme.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}}}},"ProviderStatus":{"type":"string","enum":["healthy","unhealthy"]},"ProviderAvailability":{"type":"object","title":"Provider Availability","properties":{"recommended_status":{"$ref":"#/components/schemas/ProviderStatus"},"updated_at":{"type":"string","format":"date-time","description":"The point in time when this data was collected. Value is in UTC."}},"required":["recommended_status","updated_at"]},"Provider":{"type":"object","properties":{"provider_id":{"description":"This is the provider ID that you will send us in the create payment request.","type":"string","example":"ob-natwest"},"logo_url":{"description":"This is the address of the logo asset in SVG form.","type":"string"},"icon_url":{"description":"This is the address of the icon asset in SVG form.","type":"string"},"display_name":{"description":"This is a readable name for the provider.","type":"string","example":"Natwest"},"country":{"description":"The ISO 3166-1 alpha-2 country code for the provider.","type":"string","example":"GB"},"divisions":{"description":"This array includes all divisions that are available on this provider, e.g. retail and business would indicate you can use this single provider to access both retail and business accounts.","type":"array","items":{"type":"string","enum":["retail","business"]}},"single_immediate_payment_schemes":{"type":"array","items":{"$ref":"#/components/schemas/SingleImmediatePaymentScheme"}},"availability":{"type":"object","$ref":"#/components/schemas/ProviderAvailability","description":"Whether the provider is currently available.\n> 🚧 This feature is in beta\n"}}},"ProvidersResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}},"InternalErrorResponse":{"type":"object","properties":{"error_description":{"type":"string"}}},"UKPaymentAccount":{"type":"object","description":"The details of the account owned by the participant.","required":["type","sort_code","account_number"],"properties":{"type":{"description":"The type of account.","type":"string","enum":["sort_code_account_number"]},"sort_code":{"description":"6 digit sort code (no spaces or dashes).","type":"string"},"account_number":{"description":"8 digit account number.","type":"string"}}},"IBANPaymentAccount":{"type":"object","description":"The details of the account owned by the participant.","required":["type","iban"],"properties":{"type":{"description":"The type of account.","type":"string","enum":["iban"]},"iban":{"description":"Valid International Bank Account Number (no spaces). Consists of a 2 letter country code,  followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN).","type":"string"}}},"BBANPaymentAccount":{"type":"object","description":"The details of the account owned by the participant.","required":["type","bban"],"properties":{"type":{"description":"The type of account.","type":"string","enum":["iban"]},"bban":{"description":"Valid Basic Bank Account Number (no spaces). Consists of up to 30 alphanumeric characters,  with a fixed length per country. Forms the latter part of the IBAN as described above.","type":"string"}}},"NRBPaymentAccount":{"type":"object","description":"The details of the account owned by the participant.","required":["type","nrb"],"properties":{"type":{"description":"The type of account.","type":"string","enum":["iban"]},"nrb":{"description":"Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number,  and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed.","type":"string"}}},"ParticipantDetailsInRequest":{"type":"object","required":["account"],"properties":{"account":{"oneOf":[{"$ref":"#/components/schemas/UKPaymentAccount"},{"$ref":"#/components/schemas/IBANPaymentAccount"},{"$ref":"#/components/schemas/BBANPaymentAccount"},{"$ref":"#/components/schemas/NRBPaymentAccount"}]},"name":{"description":"The name on the participant’s account.","type":"string"}}},"SingleReferences":{"type":"object","required":["type","reference"],"properties":{"type":{"description":"The type of references.","type":"string","enum":["single"]},"reference":{"description":"The reference to appear on the beneficiary’s and remitter’s statements.","type":"string"}}},"SeparateReferences":{"type":"object","required":["type","beneficiary","remitter"],"properties":{"type":{"description":"The type of references.","type":"string","enum":["separate"]},"beneficiary":{"description":"The reference to appear on the beneficiary’s statement.","type":"string"},"remitter":{"description":"The reference to appear on the remitter's statement.","type":"string"}}},"SingleImmediatePaymentEntity":{"description":"Specifies the details of the payment to be created.","type":"object","required":["payment_id","amount_in_minor","currency","provider_id","scheme_id","beneficiary"],"properties":{"single_immediate_payment_id":{"description":"The unique id of the payment you want to create. If two requests are received with the same id,  only the first one will be processed.","type":"string"},"amount_in_minor":{"description":"The amount, specified in terms of the fractional monetary unit of the payment currency, to be paid.","type":"integer"},"currency":{"description":"The ISO 4217 code of the currency for the payment.","type":"string"},"provider_id":{"description":"The id of the provider, as given on our /providers endpoint.","type":"string"},"scheme_id":{"description":"The id of the scheme to make the payment over. This must be one of the schemes  advertised by the provider on the /v2/single-immediate-payments-providers endpoint.","type":"string"},"fee_option_id":{"description":"The id indicating the desired distribution of fees between the beneficiary and remitter.  Must be a fee_option_id from one of the options advertised under that scheme on the /v2/single-immediate-payments-providers endpoint.  Should be omitted if there are no fee options (the scheme is free).","type":"string"},"beneficiary":{"description":"The details of the beneficiary receiving the payment. See the ParticipantDetails section below.","$ref":"#/components/schemas/ParticipantDetailsInRequest"},"remitter":{"description":"The details of the remitter sending the payment. See the ParticipantDetails section below.","$ref":"#/components/schemas/ParticipantDetailsInRequest"},"references":{"description":"The details of the reference, or references, for the payment. See the ReferencesDetails section below.","oneOf":[{"$ref":"#/components/schemas/SingleReferences"},{"$ref":"#/components/schemas/SeparateReferences"}]}}},"RedirectAuthFlowRequest":{"type":"object","required":["type","return_uri"],"properties":{"type":{"description":"The type of authorisation flow.","type":"string","enum":["redirect"]},"return_uri":{"description":"The URI we will return the user to after authorising the payment. When the user is redirected to this URI,  we will append a single_immediate_payment_id query parameter specifying the payment id and a type query parameter with value single_immediate_payment.","type":"string"},"psu_ip_address":{"description":"The IP address of the end user.","type":"string"},"data_access_token":{"description":"If the provider only allows a single active consent across both AIS and PIS services,  in order to prevent invalidating an existing AIS consent,  you can pass the data access token on this field,  and we will preserve the data consent when requesting authorisation for the payment.","type":"string"},"additional_inputs":{"description":"A dictionary of additional values required on a per-provider basis.  Please refer to our providers endpoint for details of the providers that require these.","type":"object","additionalProperties":{"type":"object"}}}},"EmbeddedAuthFlowRequest":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of authorisation flow.","type":"string","enum":["embedded"]},"additional_inputs":{"description":"A dictionary of additional values required on a per-provider basis.  Please refer to our providers endpoint for details of the providers that require these.","type":"object","additionalProperties":{"type":"object"}}}},"SingleImmediatePaymentInitiationRequest":{"type":"object","description":"Initiation request","required":["single_immediate_payment","auth_flow"],"properties":{"single_immediate_payment":{"$ref":"#/components/schemas/SingleImmediatePaymentEntity"},"auth_flow":{"description":"Specifies how the payment should be authorised","type":"object","oneOf":[{"$ref":"#/components/schemas/RedirectAuthFlowRequest"},{"$ref":"#/components/schemas/EmbeddedAuthFlowRequest"}]},"webhook_uri":{"description":"An address to which payment webhooks with the status of the payment should be sent. Has to be https.","type":"string"}}},"SingleImmediatePaymentResponse":{"description":"Response if the provider uses a redirect authorisation flow","required":["initiated_at","status"],"allOf":[{"$ref":"#/components/schemas/SingleImmediatePaymentEntity"},{"type":"object","properties":{"initiated_at":{"description":"The time the payment was initiated, in UTC formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ).","type":"string"},"status":{"description":"The status of the payment. For newly initiated payments, this will be initiated.","type":"string"}}}]},"RedirectAuthFlowResponse":{"type":"object","description":"Response if the provider uses a redirect redirect flow","properties":{"type":{"type":"string","description":"Value indicating this is a redirect authorisation flow: redirect","enum":["redirect"]},"uri":{"description":"The URI for the end user to authorise the payment in the bank’s UI.","type":"string"},"expiry":{"description":"An expiry time, if one is known, after which the URI to authorise the payment  will become invalid. In UTC, formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ).","type":"string"}}},"EmbeddedAuthStepOngoing":{"type":"object","description":"An object describing the next step in the ongoing authorisation flow.","properties":{"step_id":{"description":"The step id, needed to submit additional inputs.","type":"string"},"type":{"type":"string","enum":["additional_inputs"]},"additional_inputs":{"type":"object","$ref":"#/components/schemas/AdditionalInputs"}}},"EmbeddedAuthStepComplete":{"type":"object","description":"An object describing the completion of embedded auth flow","properties":{"type":{"description":"Value indicating no more steps: completed","type":"string","enum":["completed"]},"outcome":{"description":"The result of the authorisation.","type":"string","enum":["psu_cancelled","provider_rejected","authorised"]}}},"EmbeddedAuthFlowResponse":{"type":"object","description":"Response if the provider uses a redirect embedded flow","properties":{"step":{"oneOf":[{"$ref":"#/components/schemas/EmbeddedAuthStepOngoing"},{"$ref":"#/components/schemas/EmbeddedAuthStepComplete"}]},"type":{"type":"string","description":"Value indicating this is a embedded authorisation flow: embedded","enum":["embedded"]}}},"SingleImmediatePaymentInitiationResponse":{"type":"object","description":"Initiation response","required":["single_immediate_payment","auth_flow"],"properties":{"single_immediate_payment":{"$ref":"#/components/schemas/SingleImmediatePaymentResponse"},"auth_flow":{"oneOf":[{"$ref":"#/components/schemas/RedirectAuthFlowResponse"},{"$ref":"#/components/schemas/EmbeddedAuthFlowResponse"}]}}},"InvalidRequestResponse":{"type":"object","properties":{"error":{"type":"string","enum":["parameter_error"]},"error_description":{"type":"string"},"error_details":{"type":"object","properties":{"parameters":{"additionalProperties":{"description":"Problem description for the field in the request, described by its object path","type":"array","items":{"type":"string"}}}}}}},"ProviderErrorResponse":{"type":"object","properties":{"error_description":{"type":"string"}}},"EmbeddedAuthflowInputSubmissionRequest":{"type":"object","description":"A request object to input an embedded field for the embedded authflow","properties":{"type":{"type":"string","enum":["additional_inputs"]},"additional_inputs":{"additionalProperties":{"type":"object"}}}},"EmbeddedAuthflowCancelSubmissionRequest":{"type":"object","description":"A request object to input an embedded field for the embedded authflow","properties":{"type":{"type":"string","enum":["cancel"]}}},"GetSingleImmediatePaymentResponse":{"description":"Response returned on polling a payment","type":"object","properties":{"result":{"type":"object","properties":{"single_immediate_payment":{"$ref":"#/components/schemas/SingleImmediatePaymentResponse"}}}}}}},"x-readme":{"explorer-enabled":false}}